Enable pydocstyle checks and improve some doc

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
       - id: debug-statements
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.16.14
+    rev: v1.16.17
     hooks:
       - id: typos
 
@@ -23,7 +23,7 @@ repos:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.291
+    rev: v0.0.292
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

pytket/phir/main.py

@@ -1,6 +1,4 @@
-"""
-NOTE: Just a placeholder to allow convenient testing of the flows
-"""
+"""NOTE: Just a placeholder to allow convenient testing of the flows."""
 
 from pytket.circuit import Circuit
 from pytket.qasm.qasm import circuit_from_qasm

pytket/phir/sharding/shard.py

@@ -6,9 +6,10 @@
 
 @dataclass
 class Shard:
-    """
+    """The Shard class.
+
     A shard is a logical grouping of operations that represents the unit by which
-    we actually do placement of qubits
+    we actually do placement of qubits.
     """
 
     # The schedulable command of the shard

pytket/phir/sharding/sharder.py

@@ -7,22 +7,31 @@
 
 
 class Sharder:
-    """
-    The sharder class is responsible for taking in a circuit in TKET representation
+    """The Sharder class.
+
+    Responsible for taking in a circuit in TKET representation
     and converting it into shards that can be subsequently handled in the
     compilation pipeline.
     """
 
     def __init__(self, circuit: Circuit) -> None:
+        """Create Sharder object.
+
+        Args:
+        ----
+            circuit: tket Circuit
+        """
         self._circuit = circuit
         print(f"Sharder created for circuit {self._circuit}")
         self._pending_commands: dict[UnitID, list[Command]] = {}
         self._shards: list[Shard] = []
 
     def shard(self) -> list[Shard]:
-        """
-        Performs the sharding algorithm on the circuit the Sharder was initialized
-        with, returning the list of Shards needed to schedule
+        """Performs sharding algorithm on the circuit the Sharder was initialized with.
+
+        Returns:
+        -------
+            list of Shards needed to schedule
         """
         print("Sharding begins....")
         # https://cqcl.github.io/tket/pytket/api/circuit.html#pytket.circuit.Command
@@ -31,9 +40,10 @@ def shard(self) -> list[Shard]:
         return self._shards
 
     def _process_command(self, command: Command) -> None:
-        """
-        Handles a given TKET command (operation, bits, etc) according to the type
-        and the extant context within the Sharder
+        """Handles a command per the type and the extant context within the Sharder.
+
+        Args:
+            command: tket command (operation, bits, etc)
         """
         print("Processing command: ", command.op, command.op.type, command.args)
         if command.op.type in NOT_IMPLEMENTED_OP_TYPES:
@@ -47,9 +57,13 @@ def _process_command(self, command: Command) -> None:
             self._add_pending_command(command)
 
     def _build_shard(self, command: Command) -> None:
-        """
+        """Builds a shard.
+
         Creates a Shard object given the extant sharding context and the schedulable
-        Command object passed in, and appends it to the Shard list
+        Command object passed in, and appends it to the Shard list.
+
+        Args:
+            command: tket command (operation, bits, etc)
         """
         shard = Shard(command, self._pending_commands, set())
         # TODO: Dependencies!
@@ -58,9 +72,13 @@ def _build_shard(self, command: Command) -> None:
         print("Appended shard:", shard)
 
     def _add_pending_command(self, command: Command) -> None:
-        """
+        """Adds a pending command.
+
         Adds a pending sub command to the buffer to be flushed when a schedulable
         operation creates a Shard.
+
+        Args:
+            command:  tket command (operation, bits, etc)
         """
         # TODO: Need to make sure 'args[0]' is the right key to use.
         if command.args[0] not in self._pending_commands:
@@ -69,9 +87,15 @@ def _add_pending_command(self, command: Command) -> None:
 
     @staticmethod
     def should_op_create_shard(op: Op) -> bool:
-        """
-        Returns `True` if the operation is one that should result in shard creation.
+        """Decide whether to create a shard.
+
         This includes non-gate operations like measure/reset as well as 2-qubit gates.
+
+        Args:
+            op: operation
+
+        Returns:
+            `True` if the operation is one that should result in shard creation
         """
         # TODO: This is almost certainly inadequate right now
         return (

requirements.txt

@@ -3,6 +3,6 @@ build==1.0.3
 mypy==1.5.1
 pre-commit==3.4.0
 pytest==7.4.2
-ruff==0.0.291
+ruff==0.0.292
 pytket==1.20.1
 wheel==0.41.2

ruff.toml

@@ -1,3 +1,4 @@
+# See https://docs.astral.sh/ruff/rules/
 target-version = "py310"
 
 line-length = 88
@@ -11,6 +12,7 @@ select = [
   "BLE",  # flake8-blind-except
   "C4",   # flake8-comprehensions
   "COM",  # flake8-commas
+  "D",    # pydocstyle
   "EM",   # flake8-errmsg
   "EXE",  # flake8-executable
   "F",    # pyFlakes
@@ -43,16 +45,23 @@ select = [
 ]
 
 ignore = [
-  "T201", # no prints flake-8
+  "T201",   # no prints flake-8
   "FIX002", # Allow todos
-  "TD002", # Allow no author todos
-  "TD003", # allow todos with no issues
+  "TD002",  # Allow no author todos
+  "TD003",  # allow todos with no issues
+  "D100",   # Missing docstring in public module
 ]
 
 [per-file-ignores]
-"__init__.py" = ["F401"]  # module imported but unused
+"__init__.py" = ["F401", "D104"]  # module imported but unused
+"docs/*"      = [
+    "D100",     # Missing docstring in public module
+    "INP001",   # File * is part of an implicit namespace package. Add an `__init__.py`.
+]
 "tests/*"     = [
-    "S101", # Use of `assert` detected
+    "INP001",
+    "D101",   # Missing docstring in public class
+    "S101",   # Use of `assert` detected
     "PLR2004" # Magic constants
   ]
 

tests/sample_data.py

@@ -12,4 +12,12 @@ class QasmFiles(Enum):
 
 
 def get_qasm_as_circuit(qasm_file: QasmFiles) -> Circuit:
+    """Utility function to convert a QASM file to Circuit.
+
+    Args:
+        qasm_file: enum for a QASM file
+
+    Returns:
+        Corresponding tket circuit
+    """
     return circuit_from_qasm(f"tests/data/qasm/{qasm_file.name}.qasm")

tests/test_sharder.py

@@ -5,6 +5,7 @@
 
 class TestSharder:
     def test_ctor(self) -> None:
+        """Simple test of Sharder construction."""
         sharder = Sharder(get_qasm_as_circuit(QasmFiles.baby))
         assert sharder is not None