refactor: changes visibility of classes and methods in schemav1

docs/library/reference/qref.md

@@ -1,6 +1,5 @@
 ::: qref
     handler: python
     options:
-        members:
-            - generate_program_schema
-            - SchemaV1
+        filters:
+            - "!__all__"

docs/library/reference/qref.schema_v1.md

@@ -0,0 +1,6 @@
+::: qref.schema_v1
+    handler: python
+    options:
+        filters:
+            - "!^_[^_]"
+            - "!SchemaV1"

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
       - library/userguide.md
       - API Reference:
           - qref: library/reference/qref.md
+          - qref.schema_v1: library/reference/qref.schema_v1.md
           - qref.experimental.rendering: library/reference/qref.experimental.rendering.md
   - development.md
 theme:

src/qref/__init__.py

@@ -16,7 +16,8 @@
 
 from typing import Any
 
-from ._schema_v1 import SchemaV1, generate_schema_v1
+from .schema_v1 import SchemaV1, generate_schema_v1
+from .verification import verify_topology
 
 SCHEMA_GENERATORS = {"v1": generate_schema_v1}
 MODELS = {"v1": SchemaV1}
@@ -41,4 +42,4 @@ def generate_program_schema(version: str = LATEST_SCHEMA_VERSION) -> dict[str, A
         raise ValueError(f"Unknown schema version {version}")
 
 
-__all__ = ["generate_program_schema", "SchemaV1"]
+__all__ = ["generate_program_schema", "SchemaV1", "verify_topology"]

src/qref/_schema_v1.py → src/qref/schema_v1.py

@@ -31,50 +31,58 @@
 NAME_PATTERN = "[A-Za-z_][A-Za-z0-9_]*"
 NAMESPACED_NAME_PATTERN = rf"{NAME_PATTERN}\.{NAME_PATTERN}"
 
-Name = Annotated[str, StringConstraints(pattern=rf"^{NAME_PATTERN}$")]
-NamespacedName = Annotated[str, StringConstraints(pattern=rf"^{NAMESPACED_NAME_PATTERN}")]
-OptionallyNamespacedName = Annotated[
+_Name = Annotated[str, StringConstraints(pattern=rf"^{NAME_PATTERN}$")]
+_NamespacedName = Annotated[str, StringConstraints(pattern=rf"^{NAMESPACED_NAME_PATTERN}")]
+_OptionallyNamespacedName = Annotated[
     str, StringConstraints(pattern=rf"^(({NAME_PATTERN})|({NAMESPACED_NAME_PATTERN}))$")
 ]
 _Value = Union[int, float, str]
 
 
-def sorter(key):
+def _sorter(key):
     def _inner(v):
         return sorted(v, key=key)
 
     return _inner
 
 
-name_sorter = AfterValidator(sorter(lambda p: p.name))
-source_sorter = AfterValidator(sorter(lambda c: c.source))
+_name_sorter = AfterValidator(_sorter(lambda p: p.name))
+_source_sorter = AfterValidator(_sorter(lambda c: c.source))
 
 
-class _PortV1(BaseModel):
-    name: Name
+class PortV1(BaseModel):
+    """Description of Port in V1 schema"""
+
+    name: _Name
     direction: Literal["input", "output", "through"]
     size: Optional[_Value]
     model_config = ConfigDict(title="Port")
 
 
-class _ConnectionV1(BaseModel):
-    source: OptionallyNamespacedName
-    target: OptionallyNamespacedName
+class ConnectionV1(BaseModel):
+    """Description of Connection in V1 schema"""
+
+    source: _OptionallyNamespacedName
+    target: _OptionallyNamespacedName
 
     model_config = ConfigDict(title="Connection", use_enum_values=True)
 
 
-class _ResourceV1(BaseModel):
-    name: Name
+class ResourceV1(BaseModel):
+    """Description of Resource in V1 schema"""
+
+    name: _Name
     type: Literal["additive", "multiplicative", "qubits", "other"]
     value: Union[int, float, str, None]
 
     model_config = ConfigDict(title="Resource")
 
 
-class _ParamLinkV1(BaseModel):
-    source: Name
-    targets: list[NamespacedName]
+class ParamLinkV1(BaseModel):
+    """Description of Parameter link in V1 schema"""
+
+    source: _Name
+    targets: list[_NamespacedName]
 
     model_config = ConfigDict(title="ParamLink")
 
@@ -87,15 +95,15 @@ class RoutineV1(BaseModel):
         SchemaV1.
     """
 
-    name: Name
-    children: Annotated[list[RoutineV1], name_sorter] = Field(default_factory=list)
+    name: _Name
+    children: Annotated[list[RoutineV1], _name_sorter] = Field(default_factory=list)
     type: Optional[str] = None
-    ports: Annotated[list[_PortV1], name_sorter] = Field(default_factory=list)
-    resources: Annotated[list[_ResourceV1], name_sorter] = Field(default_factory=list)
-    connections: Annotated[list[_ConnectionV1], source_sorter] = Field(default_factory=list)
-    input_params: list[Name] = Field(default_factory=list)
+    ports: Annotated[list[PortV1], _name_sorter] = Field(default_factory=list)
+    resources: Annotated[list[ResourceV1], _name_sorter] = Field(default_factory=list)
+    connections: Annotated[list[ConnectionV1], _source_sorter] = Field(default_factory=list)
+    input_params: list[_Name] = Field(default_factory=list)
     local_variables: list[str] = Field(default_factory=list)
-    linked_params: Annotated[list[_ParamLinkV1], source_sorter] = Field(default_factory=list)
+    linked_params: Annotated[list[ParamLinkV1], _source_sorter] = Field(default_factory=list)
     meta: dict[str, Any] = Field(default_factory=dict)
 
     model_config = ConfigDict(title="Routine")
@@ -105,7 +113,7 @@ def __init__(self, **data: Any):
 
     @field_validator("connections", mode="after")
     @classmethod
-    def _validate_connections(cls, v, values) -> list[_ConnectionV1]:
+    def _validate_connections(cls, v, values) -> list[ConnectionV1]:
         children_port_names = [
             f"{child.name}.{port.name}"
             for child in values.data.get("children")

src/qref/verification.py

@@ -16,7 +16,7 @@
 from dataclasses import dataclass
 from typing import Optional, Union
 
-from ._schema_v1 import RoutineV1, SchemaV1
+from .schema_v1 import RoutineV1, SchemaV1
 
 
 @dataclass
@@ -36,6 +36,8 @@ def __bool__(self) -> bool:
 def verify_topology(routine: Union[SchemaV1, RoutineV1]) -> TopologyVerificationOutput:
     """Checks whether program has correct topology.
 
+    Correct topology cannot include cycles or disconnected ports.
+
     Args:
         routine: Routine or program to be verified.
     """