diff --git a/hugr-py/src/hugr/cfg.py b/hugr-py/src/hugr/cfg.py index c4c761ced..851f7913e 100644 --- a/hugr-py/src/hugr/cfg.py +++ b/hugr-py/src/hugr/cfg.py @@ -53,7 +53,7 @@ class Cfg(ParentBuilder[ops.CFG]): being a :class:`CFG `. Args: - input_types: The input types for the CFG, outputs are computed + input_types: The input types for the CFG. Outputs are computed by propagating types through the control flow graph to the exit block. Examples: @@ -96,7 +96,7 @@ def new_nested( Args: input_types: The input types for the CFG. hugr: The HUGR instance this CFG is part of. - parent: The parent node for the CFG, defaults to the root of the HUGR + parent: The parent node for the CFG: defaults to the root of the HUGR instance. Returns: @@ -175,7 +175,7 @@ def add_successor(self, pred: Wire) -> Block: """Start building a block that succeeds an existing block. Args: - pred: The wire from the predecessor block to the new block, the + pred: The wire from the predecessor block to the new block. The port of the wire determines the branching index of the new block. diff --git a/hugr-py/src/hugr/cond_loop.py b/hugr-py/src/hugr/cond_loop.py index b441a9f2c..264cad855 100644 --- a/hugr-py/src/hugr/cond_loop.py +++ b/hugr-py/src/hugr/cond_loop.py @@ -90,7 +90,7 @@ class Conditional(ParentBuilder[ops.Conditional]): Args: sum_ty: The sum type to branch on. other_inputs: The inputs for the conditional that aren't included in the - sum variants - passed to all cases. + sum variants. These are passed to all cases. Examples: >>> cond = Conditional(tys.Bool, [tys.Qubit]) @@ -124,9 +124,9 @@ def new_nested( Args: sum_ty: The sum type to branch on. other_inputs: The inputs for the conditional that aren't included in the - sum variants - passed to all cases. + sum variants. These are passed to all cases. hugr: The HUGR instance this Conditional is part of. - parent: The parent node for the Conditional, defaults to the root of + parent: The parent node for the Conditional: defaults to the root of the HUGR instance. Returns: @@ -157,7 +157,7 @@ def add_case(self, case_id: int) -> Case: other inputs to the conditional. Returns: - The new case builder. + The new case builder. Raises: ConditionalError: If the case index is out of range. @@ -185,7 +185,7 @@ def add_case(self, case_id: int) -> Case: @dataclass class TailLoop(_DfBase[ops.TailLoop]): - """Builder for a tail controlled loop. + """Builder for a tail-controlled loop. Args: just_inputs: Types that are only inputs to the loop body. @@ -202,7 +202,7 @@ def __init__(self, just_inputs: TypeRow, rest: TypeRow) -> None: super().__init__(root_op) def set_loop_outputs(self, sum_wire: Wire, *rest: Wire) -> None: - """Set the outputs of the loop body, the first wire must be the sum type + """Set the outputs of the loop body. The first wire must be the sum type that controls loop termination. Args: diff --git a/hugr-py/src/hugr/dfg.py b/hugr-py/src/hugr/dfg.py index fdddbfa0f..44e7b29ad 100644 --- a/hugr-py/src/hugr/dfg.py +++ b/hugr-py/src/hugr/dfg.py @@ -62,13 +62,13 @@ def _init_io_nodes(self, parent_op: DP): def new_nested( cls, parent_op: DP, hugr: Hugr, parent: ToNode | None = None ) -> Self: - """Start building a dataflow graph nested inside a larger hugr. + """Start building a dataflow graph nested inside a larger HUGR. Args: parent_op: The parent operation of the new dataflow graph. - hugr: The host hugr instance to build the dataflow graph in. - parent: Parent of new dataflow graph's root node, defaults to the - host hugr root. + hugr: The host HUGR instance to build the dataflow graph in. + parent: Parent of new dataflow graph's root node: defaults to the + host HUGR root. Example: >>> hugr = Hugr() @@ -90,7 +90,7 @@ def _output_op(self) -> ops.Output: return self.hugr._get_typed_op(self.output_node, ops.Output) def inputs(self) -> list[OutPort]: - """List all incoming wires, output ports of the input node. + """List all incoming wires (output ports of the input node). Example: >>> dfg = Dfg(tys.Bool) @@ -235,7 +235,7 @@ def add_conditional(self, cond_wire: Wire, *args: Wire) -> Conditional: graph. Args: - cond_wire: The wire holding the wire (of Sum type) to branch the + cond_wire: The wire holding the value (of Sum type) to branch the conditional on. args: Remaining input wires to the conditional. @@ -267,7 +267,7 @@ def insert_conditional( Args: cond: The conditional to insert. - cond_wire: The wire holding the wire (of Sum type) + cond_wire: The wire holding the value (of Sum type) to branch the Conditional on. args: Remaining input wires to the conditional. @@ -289,7 +289,7 @@ def add_if(self, cond_wire: Wire, *args: Wire) -> If: graph. Args: - cond_wire: The wire holding the Bool wire to branch the If on. + cond_wire: The wire holding the Bool value to branch the If on. args: Remaining input wires to the If (and subsequent Else). Returns: @@ -476,7 +476,7 @@ def load_function( instantiation: tys.FunctionType | None = None, type_args: Sequence[tys.TypeArg] | None = None, ) -> Node: - """Load a static function in to the graph as a higher-order value. + """Load a static function into the graph as a higher-order value. Args: func: The node corresponding to the function definition/declaration to load. diff --git a/hugr-py/src/hugr/function.py b/hugr-py/src/hugr/function.py index deb621f4d..05e8dee08 100644 --- a/hugr-py/src/hugr/function.py +++ b/hugr-py/src/hugr/function.py @@ -24,7 +24,7 @@ class Function(_DfBase[ops.FuncDefn]): Args: name: The name of the function. input_types: The input types for the function (output types are - computated by propagating types from input node through the graph). + computed by propagating types from input node through the graph). type_params: The type parameters for the function, if polymorphic. Examples: @@ -45,7 +45,7 @@ def __init__( @dataclass class Module: - """Build a top level HUGR module. + """Build a top-level HUGR module. Examples: >>> m = Module() diff --git a/hugr-py/src/hugr/hugr.py b/hugr-py/src/hugr/hugr.py index 4eca00962..2f2a53b20 100644 --- a/hugr-py/src/hugr/hugr.py +++ b/hugr-py/src/hugr/hugr.py @@ -126,7 +126,7 @@ def children(self, node: ToNode | None = None) -> list[Node]: """The child nodes of a given `node`. Args: - node: Parent node. Defaults to the Hugr root. + node: Parent node. Defaults to the HUGR root. Returns: List of child nodes. @@ -241,7 +241,7 @@ def _unused_sub_offset(self, port: P) -> _SubPort[P]: return sub_port def add_link(self, src: OutPort, dst: InPort) -> None: - """Add a link (edge) between two nodes to the HUGR, + """Add a link (edge) between two nodes to the HUGR, from an outgoing port to an incoming port. Args: @@ -503,14 +503,14 @@ def port_type(self, port: InPort | OutPort) -> Type | None: return None def insert_hugr(self, hugr: Hugr, parent: ToNode | None = None) -> dict[Node, Node]: - """Insert a HUGR in to this HUGR. + """Insert a HUGR into this HUGR. Args: hugr: HUGR to insert. - parent: Parent for root of inserted HUGR, defaults to None. + parent: Parent for root of inserted HUGR. Defaults to None. Returns: - Mapping from node indices in inserted to HUGR to their new indices + Mapping from node indices in inserted HUGR to their new indices in this HUGR. Examples: diff --git a/hugr-py/src/hugr/node_port.py b/hugr-py/src/hugr/node_port.py index db264d404..0ef173bb6 100644 --- a/hugr-py/src/hugr/node_port.py +++ b/hugr-py/src/hugr/node_port.py @@ -68,7 +68,7 @@ class ToNode(Wire, Protocol): """Protocol by any object that can be treated as a :class:`Node`.""" def to_node(self) -> Node: - """Convert in to a :class:`Node`.""" + """Convert to a :class:`Node`.""" ... # pragma: no cover @overload diff --git a/hugr-py/src/hugr/ops.py b/hugr-py/src/hugr/ops.py index 315bb70e6..506d8ecd2 100644 --- a/hugr-py/src/hugr/ops.py +++ b/hugr-py/src/hugr/ops.py @@ -31,7 +31,7 @@ def msg(self) -> str: @runtime_checkable class Op(Protocol): - """An abstract HUGR operation. Must be convertibl + """An abstract HUGR operation. Must be convertible to a serialisable :class:`BaseOp`. """ @@ -77,7 +77,7 @@ class DataflowOp(Op, Protocol): """ def outer_signature(self) -> tys.FunctionType: - """The external signature of this operation, defines the valid external + """The external signature of this operation. Defines the valid external connectivity of the node the operation belongs to. """ ... # pragma: no cover @@ -101,7 +101,7 @@ def port_type(self, port: InPort | OutPort) -> tys.Type: def __call__(self, *args) -> Command: """Calling with incoming :class:`Wire` arguments returns a - :class:`Command` which can be used to wire in the operation in to a + :class:`Command` which can be used to wire the operation into a dataflow graph. """ return Command(self, list(args)) @@ -139,7 +139,7 @@ class Command: """A :class:`DataflowOp` and its incoming :class:`Wire ` arguments. - Ephemeral, used to wire in operations to a dataflow graph. + Ephemeral: used to wire operations into a dataflow graph. Example: >>> Noop()(Node(0).out(0)) @@ -300,7 +300,7 @@ def _set_in_types(self, types: tys.TypeRow) -> None: class Tag(DataflowOp): """Tag a row of incoming values to make them a variant of a sum type. - Requires `sum_ty` to be set as all the variants cannot be extracted from + Requires `sum_ty` to be set as it is not possible to extract all the variants from just the input wires for one variant. """ @@ -323,7 +323,7 @@ def outer_signature(self) -> tys.FunctionType: class DfParentOp(Op, Protocol): """Abstract parent of dataflow graph operations. Can be queried for the - dataflow signature of their child graph. + dataflow signature of its child graph. """ def inner_signature(self) -> tys.FunctionType: @@ -427,7 +427,7 @@ def outer_signature(self) -> tys.FunctionType: @dataclass class DataflowBlock(DfParentOp): - """Parent of Non-entry basic block in a control flow graph.""" + """Parent of non-entry basic block in a control flow graph.""" #: Inputs types of the innner dataflow graph. inputs: tys.TypeRow @@ -520,8 +520,8 @@ def port_kind(self, port: InPort | OutPort) -> tys.Kind: @dataclass class Const(Op): - """A static constant value. Can be used with a :class:`LoadConst` to load in - to a dataflow graph. + """A static constant value. Can be used with a :class:`LoadConst` to load into + a dataflow graph. """ val: val.Value @@ -584,7 +584,7 @@ def __repr__(self) -> str: @dataclass() class Conditional(DataflowOp): - """Switch on the variants of an incoming sum type, evaluating the + """'Switch' operation on the variants of an incoming sum type, evaluating the corresponding one of the child :class:`Case` operations. """ @@ -869,7 +869,7 @@ class Call(_CallOrLoad, Op): Args: signature: Polymorphic function signature. instantiation: Concrete function signature. Defaults to None. - type_args: type arguments for polymorphic function. Defaults to None. + type_args: Type arguments for polymorphic function. Defaults to None. Raises: NoConcreteFunc: If the signature is polymorphic and no instantiation @@ -949,7 +949,7 @@ class LoadFunc(_CallOrLoad, DataflowOp): Args: signature: Polymorphic function signature. instantiation: Concrete function signature. Defaults to None. - type_args: type arguments for polymorphic function. Defaults to None. + type_args: Type arguments for polymorphic function. Defaults to None. Raises: NoConcreteFunc: If the signature is polymorphic and no instantiation @@ -1037,9 +1037,9 @@ def _set_in_types(self, types: tys.TypeRow) -> None: class AliasDecl(Op): """Declare an external type alias.""" - #: Alias name + #: Alias name. name: str - #: Type bound + #: Type bound. bound: tys.TypeBound num_out: int = field(default=0, repr=False) @@ -1058,9 +1058,9 @@ def port_kind(self, port: InPort | OutPort) -> tys.Kind: class AliasDefn(Op): """Declare a type alias.""" - #: Alias name + #: Alias name. name: str - #: Type definition + #: Type definition. definition: tys.Type num_out: int = field(default=0, repr=False) diff --git a/hugr-py/src/hugr/tys.py b/hugr-py/src/hugr/tys.py index 1c5503c17..7ad773b49 100644 --- a/hugr-py/src/hugr/tys.py +++ b/hugr-py/src/hugr/tys.py @@ -207,7 +207,7 @@ def to_serial(self) -> stys.Array: @dataclass() class Sum(Type): - """Algabraic sum over product type. Instances of this type correspond to + """Algebraic sum-over-product type. Instances of this type correspond to tuples (products) over one of the `variant_rows` in the sum type, tagged by the index of the row. """ @@ -285,7 +285,7 @@ def to_serial(self) -> stys.RowVar: @dataclass(frozen=True) class USize(Type): - """The prelude unsigned size type.""" + """The Prelude unsigned size type.""" def to_serial(self) -> stys.USize: return stys.USize() diff --git a/hugr-py/src/hugr/val.py b/hugr-py/src/hugr/val.py index c9c73e0e6..0236aabb8 100644 --- a/hugr-py/src/hugr/val.py +++ b/hugr-py/src/hugr/val.py @@ -16,7 +16,7 @@ @runtime_checkable class Value(Protocol): - """Abstract value definition. Must be serialisable in to a HUGR value.""" + """Abstract value definition. Must be serialisable into a HUGR value.""" def to_serial(self) -> sops.BaseValue: """Convert to serialisable model.""" @@ -37,7 +37,7 @@ def type_(self) -> tys.Type: @dataclass class Sum(Value): - """Sum of product value. + """Sum-of-product value. Example: >>> Sum(0, tys.Sum([[tys.Bool], [tys.Unit]]), [TRUE]) @@ -46,7 +46,7 @@ class Sum(Value): #: Tag identifying the variant. tag: int - #: Type of the sum, defines all possible variants. + #: Type of the sum: defines all possible variants. typ: tys.Sum #: The values of this variant row. vals: list[Value] @@ -96,7 +96,7 @@ def __repr__(self) -> str: def bool_value(b: bool) -> UnitSum: - """Convert a python bool to a HUGR bool value. + """Convert a python bool to a HUGR boolean value. Example: >>> bool_value(True)