new_backend
¶
Scaffold a new circuit backend (stub, export, and test).
BackendNames
dataclass
¶
Derived names for a scaffolded circuit backend.
Source code in shadowsim/cli/new_backend.py
ScaffoldError
¶
pascal_to_snake
¶
normalize_base_name
¶
Validate PascalCase input and strip a trailing backend suffix.
CircuitBackend is removed first, then Backend, so Cirq and
CirqCircuitBackend both become Cirq.
Raises:
-
ScaffoldError–rawis empty, not PascalCase, or a reserved name.
Source code in shadowsim/cli/new_backend.py
normalize_kind
¶
Validate a backend kind.
expectation stores no shot budget, the same shape as the NumPy backend.
sampling stores shots, the same shape as the Aer backend.
Raises:
-
ScaffoldError–rawis notexpectationorsampling.
Source code in shadowsim/cli/new_backend.py
derive_names
¶
derive_names(raw: str) -> BackendNames
Derive class, module, and catalog id from a PascalCase name.
The catalog id is the class name with CircuitBackend and then
Backend removed, lowercased. WaveMatrix becomes wavematrix.
Source code in shadowsim/cli/new_backend.py
default_repo_root
¶
Resolve the repository root from the working directory or package location.
Raises:
-
ScaffoldError–Neither location contains
shadowsim/backends.
Source code in shadowsim/cli/new_backend.py
stub_path
¶
stub_path(repo_root: Path, names: BackendNames) -> Path
test_path
¶
test_path(repo_root: Path, names: BackendNames) -> Path
init_path
¶
check_collisions
¶
check_collisions(
repo_root: Path, names: BackendNames
) -> None
Raise if the stub, test, or export already exists for this name.
Raises:
-
ScaffoldError–A module, test, or export for
namesis already present, or the backends package init is missing.
Source code in shadowsim/cli/new_backend.py
render_stub
¶
render_stub(
names: BackendNames, *, kind: str = "expectation"
) -> str
Return the source for a new backend stub module.
expectation stores no shot budget. sampling stores shots.
Raises:
-
ScaffoldError–kindis notexpectationorsampling.
Source code in shadowsim/cli/new_backend.py
render_test
¶
render_test(
names: BackendNames, *, kind: str = "expectation"
) -> str
Return the source for a backend test that passes while the stub raises.
Raises:
-
ScaffoldError–kindis notexpectationorsampling.
Source code in shadowsim/cli/new_backend.py
patch_init_file
¶
patch_init_file(path: Path, names: BackendNames) -> None
Register the new backend in _EXPORTS, TYPE_CHECKING, and __all__.
The extra is None. _EXPORTS and the type-checking import are ordered
by module name. __all__ is ordered by class name.
Raises:
-
ScaffoldError–namesis already registered, or a required block is missing or unclosed.
Source code in shadowsim/cli/new_backend.py
create_backend
¶
create_backend(
raw_name: str,
*,
repo_root: Path | None = None,
kind: str = "expectation",
) -> BackendNames
Validate, check collisions, and write the stub, export, and test.
kind="expectation" writes a backend with no shots attribute.
kind="sampling" writes a backend that stores shots. On failure the
stub and test are removed and __init__.py is restored.
Raises:
-
ScaffoldError–The name or kind is invalid, or a file already exists.
Source code in shadowsim/cli/new_backend.py
build_parser
¶
Build the CLI argument parser.
Source code in shadowsim/cli/new_backend.py
main
¶
Run the new-backend scaffolding CLI.