fix: CircuitRef.download_circuit() now supports scope (#298)

quantinuum-richard-morrison · web-flow · commit 38832296c248 · 2025-11-25T11:20:41.000Z
diff --git a/integration/test_scope.py b/integration/test_scope.py
@@ -1,7 +1,7 @@
 """Test basic functionality relating to setting 'scope' for API requests."""
 
 import qnexus as qnx
-from qnexus.models.filters import ScopeFilterEnum
+from qnexus.models.scope import ScopeFilterEnum
 
 
 def test_user_scope(
diff --git a/qnexus/client/circuits.py b/qnexus/client/circuits.py
@@ -27,7 +27,6 @@
     ProjectRefFilter,
     PropertiesFilter,
     ScopeFilter,
-    ScopeFilterEnum,
     SortFilter,
     SortFilterEnum,
     TimeFilter,
@@ -38,6 +37,7 @@
     ExecutionProgram,
     ProjectRef,
 )
+from qnexus.models.scope import ScopeFilterEnum
 
 
 class Params(
diff --git a/qnexus/client/gpu_decoder_configs.py b/qnexus/client/gpu_decoder_configs.py
@@ -23,12 +23,12 @@
     ProjectRefFilter,
     PropertiesFilter,
     ScopeFilter,
-    ScopeFilterEnum,
     SortFilter,
     SortFilterEnum,
     TimeFilter,
 )
 from qnexus.models.references import DataframableList, GpuDecoderConfigRef, ProjectRef
+from qnexus.models.scope import ScopeFilterEnum
 
 
 class Params(
diff --git a/qnexus/client/hugr.py b/qnexus/client/hugr.py
@@ -32,7 +32,6 @@
     ProjectRefFilter,
     PropertiesFilter,
     ScopeFilter,
-    ScopeFilterEnum,
     SortFilter,
     SortFilterEnum,
     TimeFilter,
@@ -43,6 +42,7 @@
     HUGRRef,
     ProjectRef,
 )
+from qnexus.models.scope import ScopeFilterEnum
 
 
 class Params(
diff --git a/qnexus/client/jobs/__init__.py b/qnexus/client/jobs/__init__.py
@@ -37,7 +37,6 @@
     ProjectRefFilter,
     PropertiesFilter,
     ScopeFilter,
-    ScopeFilterEnum,
     SortFilter,
     SortFilterEnum,
     TimeFilter,
@@ -61,6 +60,7 @@
     SystemRef,
     WasmModuleRef,
 )
+from qnexus.models.scope import ScopeFilterEnum
 from qnexus.models.utils import assert_never
 
 EPOCH_START = datetime(1970, 1, 1, tzinfo=timezone.utc)
diff --git a/qnexus/client/jobs/_compile.py b/qnexus/client/jobs/_compile.py
@@ -15,7 +15,6 @@
 )
 from qnexus.models import BackendConfig
 from qnexus.models.annotations import Annotations, CreateAnnotations, PropertiesDict
-from qnexus.models.filters import ScopeFilterEnum
 from qnexus.models.job_status import JobStatus, JobStatusEnum
 from qnexus.models.references import (
     CircuitRef,
@@ -27,6 +26,7 @@
     JobType,
     ProjectRef,
 )
+from qnexus.models.scope import ScopeFilterEnum
 
 
 @accept_circuits_for_programs
diff --git a/qnexus/client/jobs/_execute.py b/qnexus/client/jobs/_execute.py
@@ -19,7 +19,6 @@
 )
 from qnexus.models import BackendConfig, StoredBackendInfo, to_pytket_backend_info
 from qnexus.models.annotations import Annotations, CreateAnnotations, PropertiesDict
-from qnexus.models.filters import ScopeFilterEnum
 from qnexus.models.job_status import JobStatus, JobStatusEnum
 from qnexus.models.language import Language
 from qnexus.models.references import (
@@ -39,6 +38,7 @@
     ResultVersions,
     WasmModuleRef,
 )
+from qnexus.models.scope import ScopeFilterEnum
 from qnexus.models.utils import assert_never, truncate_to_2dp
 
 
diff --git a/qnexus/client/projects.py b/qnexus/client/projects.py
@@ -20,13 +20,13 @@
     FuzzyNameFilter,
     PaginationFilter,
     ScopeFilter,
-    ScopeFilterEnum,
     SortFilter,
     SortFilterEnum,
     TimeFilter,
 )
 from qnexus.models.job_status import WAITING_STATUS, JobStatusEnum
 from qnexus.models.references import DataframableList, ProjectRef
+from qnexus.models.scope import ScopeFilterEnum
 
 # Colour-blind friendly colours from https://www.nature.com/articles/nmeth.1618
 _COLOURS = ["#e69f00", "#56b4e9", "#009e73", "#f0e442", "#0072b2", "#d55e00", "#cc79a7"]
diff --git a/qnexus/client/qir.py b/qnexus/client/qir.py
@@ -24,7 +24,6 @@
     ProjectRefFilter,
     PropertiesFilter,
     ScopeFilter,
-    ScopeFilterEnum,
     SortFilter,
     SortFilterEnum,
     TimeFilter,
@@ -35,6 +34,7 @@
     ProjectRef,
     QIRRef,
 )
+from qnexus.models.scope import ScopeFilterEnum
 
 
 class Params(
diff --git a/qnexus/client/roles.py b/qnexus/client/roles.py
@@ -10,8 +10,8 @@
 from qnexus.client import get_nexus_client
 from qnexus.context import merge_scope_from_context
 from qnexus.models import Role, RoleInfo
-from qnexus.models.filters import ScopeFilterEnum
 from qnexus.models.references import BaseRef, DataframableList, TeamRef
+from qnexus.models.scope import ScopeFilterEnum
 
 Permission = Literal["ASSIGN", "DELETE", "WRITE", "READ"]
 RoleName = Literal["Administrator", "Contributor", "Reader", "Maintainer"]
diff --git a/qnexus/client/teams.py b/qnexus/client/teams.py
@@ -3,8 +3,8 @@
 import qnexus.exceptions as qnx_exc
 from qnexus.client import get_nexus_client
 from qnexus.context import merge_scope_from_context
-from qnexus.models.filters import ScopeFilterEnum
 from qnexus.models.references import DataframableList, TeamRef
+from qnexus.models.scope import ScopeFilterEnum
 
 
 @merge_scope_from_context
diff --git a/qnexus/client/users.py b/qnexus/client/users.py
@@ -5,8 +5,8 @@
 import qnexus.exceptions as qnx_exc
 from qnexus.client import get_nexus_client
 from qnexus.context import merge_scope_from_context
-from qnexus.models.filters import ScopeFilterEnum
 from qnexus.models.references import UserRef
+from qnexus.models.scope import ScopeFilterEnum
 
 
 def get_self() -> UserRef:
diff --git a/qnexus/client/wasm_modules.py b/qnexus/client/wasm_modules.py
@@ -25,12 +25,12 @@
     ProjectRefFilter,
     PropertiesFilter,
     ScopeFilter,
-    ScopeFilterEnum,
     SortFilter,
     SortFilterEnum,
     TimeFilter,
 )
 from qnexus.models.references import DataframableList, ProjectRef, WasmModuleRef
+from qnexus.models.scope import ScopeFilterEnum
 
 
 class Params(
diff --git a/qnexus/context.py b/qnexus/context.py
@@ -8,8 +8,8 @@
 from typing import Any, Callable, Generator, ParamSpec, TypeVar
 
 from qnexus.models.annotations import PropertiesDict
-from qnexus.models.filters import ScopeFilterEnum
-from qnexus.models.references import ProjectRef
+from qnexus.models.references.projects import ProjectRef
+from qnexus.models.scope import ScopeFilterEnum
 
 logger = logging.getLogger(__name__)
 
diff --git a/qnexus/models/filters.py b/qnexus/models/filters.py
@@ -11,6 +11,7 @@
 from qnexus.models import CredentialIssuer, JobStatusEnum
 from qnexus.models.annotations import PropertiesDict
 from qnexus.models.references import JobType, ProjectRef
+from qnexus.models.scope import ScopeFilterEnum
 from qnexus.models.utils import AllowNone
 
 
@@ -267,15 +268,6 @@ class CredentialsFilter(BaseModel):
     issuer: CredentialIssuer | str | None = None
 
 
-class ScopeFilterEnum(str, Enum):
-    """ScopeFilterEnum model."""
-
-    USER = "user"
-    ORG_ADMIN = "org_admin"
-    GLOBAL_ADMIN = "global_admin"
-    HIGHEST = "highest"
-
-
 class ScopeFilter(BaseModel):
     """Filter by scope."""
 
diff --git a/qnexus/models/references/__init__.py b/qnexus/models/references/__init__.py
@@ -4,7 +4,6 @@
 
 from abc import abstractmethod
 from copy import copy
-from datetime import datetime
 from enum import Enum
 from typing import (
     Annotated,
@@ -23,18 +22,54 @@
 import pandas as pd
 from hugr.package import Package
 from hugr.qsystem.result import QsysResult
-from pydantic import BaseModel, ConfigDict, Field, field_serializer
+from pydantic import ConfigDict, Field
 from pytket.backends.backendinfo import BackendInfo
 from pytket.backends.backendresult import BackendResult
 from pytket.circuit import Circuit
 from pytket.wasm.wasm import WasmModuleHandler
 from quantinuum_schemas.models.backend_config import BackendConfig
 
+from qnexus.context import merge_scope_from_context
 from qnexus.exceptions import IncompatibleResultVersion
 from qnexus.models.annotations import Annotations
 from qnexus.models.job_status import JobStatus, JobStatusEnum
+from qnexus.models.references.base import BaseRef
+from qnexus.models.references.projects import ProjectRef
+from qnexus.models.scope import ScopeFilterEnum
 from qnexus.models.utils import assert_never
 
+__all__ = [
+    "BaseRef",  # re-export
+    "CircuitRef",
+    "CompilationPassRef",
+    "CompilationResultRef",
+    "CompileJobRef",
+    "Dataframable",
+    "DataframableList",
+    "deserialize_nexus_ref",
+    "ExecuteJobRef",
+    "ExecutionProgram",
+    "ExecutionResult",
+    "ExecutionResultRef",
+    "GpuDecoderConfigRef",
+    "HUGRRef",
+    "IncompleteJobItemRef",
+    "JobRef",
+    "JobType",
+    "JobType",
+    "ProjectRef",  # re-export
+    "QIRRef",
+    "QIRResult",
+    "ref_name_to_class",
+    "Ref",
+    "ResultType",
+    "ResultVersions",
+    "SystemRef",
+    "TeamRef",
+    "UserRef",
+    "WasmModuleRef",
+]
+
 
 class Dataframable(Protocol):
     """Protocol for structural subtyping of classes that
@@ -62,14 +97,6 @@ def df(self) -> pd.DataFrame:
         return pd.concat([item.df() for item in self], ignore_index=True)
 
 
-class BaseRef(BaseModel):
-    """Base pydantic model."""
-
-    model_config = ConfigDict(frozen=True)
-
-    id: UUID
-
-
 class TeamRef(BaseRef):
     """Proxy object to a Team in Nexus."""
 
@@ -108,38 +135,6 @@ def df(self) -> pd.DataFrame:
         )
 
 
-class ProjectRef(BaseRef):
-    """Proxy object to a Project in Nexus."""
-
-    annotations: Annotations
-    contents_modified: datetime
-    archived: bool = Field(default=False)
-    id: UUID
-    type: Literal["ProjectRef"] = "ProjectRef"
-
-    @field_serializer("contents_modified")
-    def serialize_modified(self, contents_modified: datetime | None) -> str | None:
-        """Custom serializer for datetimes."""
-        if contents_modified:
-            return str(contents_modified)
-        return None
-
-    def df(self) -> pd.DataFrame:
-        """Present in a pandas DataFrame."""
-        return pd.DataFrame(
-            {
-                "name": self.annotations.name,
-                "description": self.annotations.description,
-                "created": self.annotations.created,
-                "modified": self.annotations.modified,
-                "contents_modified": self.contents_modified,
-                "archived": self.archived,
-                "id": self.id,
-            },
-            index=[0],
-        )
-
-
 class SystemRef(BaseRef):
     """Proxy object to a System in Nexus."""
 
@@ -169,13 +164,16 @@ class CircuitRef(BaseRef):
     _circuit: Circuit | None = None
     type: Literal["CircuitRef"] = "CircuitRef"
 
-    def download_circuit(self) -> Circuit:
+    @merge_scope_from_context
+    def download_circuit(
+        self, scope: ScopeFilterEnum = ScopeFilterEnum.USER
+    ) -> Circuit:
         """Get a copy of the circuit as a pytket ``Circuit`` object."""
         if self._circuit:
             return self._circuit.copy()
         from qnexus.client.circuits import _fetch_circuit
 
-        self._circuit = _fetch_circuit(self)
+        self._circuit = _fetch_circuit(self, scope=scope)
         return self._circuit.copy()
 
     def df(self) -> pd.DataFrame:
@@ -380,9 +378,11 @@ def df(self) -> pd.DataFrame:
                     "project": self.project.annotations.name,
                     "backend_config": self.backend_config.__class__.__name__,
                     "system": self.system.name if self.system else "Unknown",
-                    "cost": self.last_status_detail.cost
-                    if self.last_status_detail
-                    else "Unknown",
+                    "cost": (
+                        self.last_status_detail.cost
+                        if self.last_status_detail
+                        else "Unknown"
+                    ),
                     "id": self.id,
                 },
                 index=[0],
diff --git a/qnexus/models/references/base.py b/qnexus/models/references/base.py
@@ -0,0 +1,10 @@
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseRef(BaseModel):
+    """Base pydantic model."""
+
+    model_config = ConfigDict(frozen=True)
+    id: UUID
diff --git a/qnexus/models/references/projects.py b/qnexus/models/references/projects.py
diff --git a/qnexus/models/scope.py b/qnexus/models/scope.py
diff --git a/tests/test_circuits.py b/tests/test_circuits.py
diff --git a/tests/test_context.py b/tests/test_context.py
diff --git a/tests/test_filters.py b/tests/test_filters.py

Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,6 @@`
`15`	`15`	`)`
`16`	`16`	`from qnexus.models import BackendConfig`
`17`	`17`	`from qnexus.models.annotations import Annotations, CreateAnnotations, PropertiesDict`
`18`		`-from qnexus.models.filters import ScopeFilterEnum`
`19`	`18`	`from qnexus.models.job_status import JobStatus, JobStatusEnum`
`20`	`19`	`from qnexus.models.references import (`
`21`	`20`	`CircuitRef,`
`@@ -27,6 +26,7 @@`
`27`	`26`	`JobType,`
`28`	`27`	`ProjectRef,`
`29`	`28`	`)`
	`29`	`+from qnexus.models.scope import ScopeFilterEnum`
`30`	`30`
`31`	`31`
`32`	`32`	`@accept_circuits_for_programs`
Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,6 @@`
`19`	`19`	`)`
`20`	`20`	`from qnexus.models import BackendConfig, StoredBackendInfo, to_pytket_backend_info`
`21`	`21`	`from qnexus.models.annotations import Annotations, CreateAnnotations, PropertiesDict`
`22`		`-from qnexus.models.filters import ScopeFilterEnum`
`23`	`22`	`from qnexus.models.job_status import JobStatus, JobStatusEnum`
`24`	`23`	`from qnexus.models.language import Language`
`25`	`24`	`from qnexus.models.references import (`
`@@ -39,6 +38,7 @@`
`39`	`38`	`ResultVersions,`
`40`	`39`	`WasmModuleRef,`
`41`	`40`	`)`
	`41`	`+from qnexus.models.scope import ScopeFilterEnum`
`42`	`42`	`from qnexus.models.utils import assert_never, truncate_to_2dp`
`43`	`43`
`44`	`44`