Feat: registry (backends / transports / schedulers)

.pre-commit-config.yaml

@@ -39,3 +39,4 @@ repos:
     hooks:
       - id: mypy
         exclude: tests
+        additional_dependencies: ["pydantic>=2.0.0"]

docs/dev/index.md

@@ -8,4 +8,4 @@ DiracX projects:
 - [Reference](reference/index.md): technical details
 - [Explanations](explanations/index.md): why things are done this way
 
-User documentation (`docs/user/`) will come once the library has a public API.
+For code that uses interCEde, see the [user documentation](../user/index.md).

docs/index.md

@@ -0,0 +1,13 @@
+# interCEde
+
+Unified interfaces to Computing Elements and batch systems for DIRAC / DiracX.
+
+A consumer submits and monitors jobs through one set of protocols, whatever the resource behind
+them. interCEde is stateless: it never changes a job on its own, and the consumer stores the job
+handles it gets back.
+
+- [User documentation](user/index.md): for code that uses interCEde, such as DiracX. Start with
+  the [API reference](user/reference/api.md): the protocols, data types and exceptions a consumer
+  may import.
+- [Developer documentation](dev/index.md): for working on interCEde itself, including the
+  integration test stacks.

docs/user/index.md

@@ -0,0 +1,8 @@
+# User documentation
+
+For code that uses interCEde, such as DiracX. Organised following [Diátaxis](https://diataxis.fr/),
+like the developer documentation:
+
+- [Reference](reference/index.md): the public API
+
+Tutorials, how-to guides and explanations will follow as the backends land.

docs/user/reference/api.md

@@ -0,0 +1,24 @@
+# API reference
+
+Everything listed here is importable from `intercede` and follows SemVer.
+Anything else, including every name starting with `_`, is internal.
+
+## Protocols
+
+::: intercede.protocols
+
+## Data types
+
+::: intercede.models
+
+## Configuration
+
+::: intercede.config
+
+## Registry
+
+::: intercede.registry
+
+## Exceptions
+
+::: intercede.exceptions

docs/user/reference/index.md

@@ -0,0 +1,3 @@
+# Reference
+
+- [API reference](api.md): the protocols, data types and exceptions a consumer may import

mkdocs.yml

@@ -0,0 +1,25 @@
+site_name: interCEde
+site_description: Unified interfaces to Computing Elements and batch systems for DIRAC / DiracX
+repo_url: https://github.com/DIRACGrid/intercede
+
+theme:
+  name: material
+  logo: assets/intercede-icon.svg
+  favicon: assets/intercede-icon.svg
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_source: false
+            members_order: source
+            merge_init_into_class: true
+
+validation:
+  links:
+    # The developer docs link to repository files outside docs/ (e.g. renovate.json),
+    # which resolve on GitHub but not in the built site.
+    not_found: info

pyproject.toml

@@ -17,7 +17,9 @@ requires-python = ">=3.11"
 keywords = []
 license = { text = "GPL-3.0-only" }
 dynamic = ["version"]
-dependencies = []
+dependencies = [
+  "pydantic>=2"
+]
 classifiers = [
   "Intended Audience :: Science/Research",
   "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
@@ -40,9 +42,6 @@ testing = [
   "ty",
 ]
 
-[tool.setuptools.packages.find]
-where = ["src"]
-
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]
@@ -60,6 +59,10 @@ markers = [
   "destructive_fetch: asserts one-shot/destructive output-retrieval semantics",
 ]
 
+[tool.mypy]
+strict = true
+plugins = ["pydantic.mypy"]
+files = ["src"]
 
 [tool.ruff]
 src = ["src", "tests"]
@@ -122,6 +125,7 @@ py311 = { features = ["testing", "py311"] }
 py312 = { features = ["testing", "py312"] }
 py313 = { features = ["testing", "py313"] }
 py314 = { features = ["testing", "py314"] }
+docs = { features = ["docs"], solve-group = "default" }
 
 [tool.pixi.feature.testing.pypi-dependencies]
 intercede = { path = ".", editable = true }
@@ -134,6 +138,16 @@ pre-commit = "*"
 pre-commit = { cmd = "pre-commit", description = "Run pre-commit" }
 
 
+# Features for building the documentation
+[tool.pixi.feature.docs.pypi-dependencies]
+intercede = { path = ".", editable = true }
+mkdocs = "<2"
+mkdocs-material = "*"
+mkdocstrings = { version = "*", extras = ["python"] }
+[tool.pixi.feature.docs.tasks]
+docs = { cmd = "mkdocs build --strict", description = "Build the documentation" }
+
+
 [tool.pixi.tasks]
 unit-test = { cmd = "pytest -v", description = "Run the unit tests" }
 

src/intercede/__init__.py

@@ -5,10 +5,83 @@
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as get_version
 
+from intercede import registry
+from intercede.config import BackendConfig
+from intercede.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    InterCEdeError,
+    RegistryError,
+    ResourceUnavailableError,
+    SpecificationRejectedError,
+)
+from intercede.models import (
+    ContainerSpec,
+    CopyVars,
+    Diagnostics,
+    FileRef,
+    JobHandle,
+    JobID,
+    JobOutput,
+    JobStatus,
+    OpOutcome,
+    OutputMember,
+    OutputSpec,
+    Resources,
+    StatusMap,
+    Submission,
+    SubmissionSpec,
+)
+from intercede.protocols import (
+    Diagnosable,
+    JobBackend,
+    Killable,
+    OutputRetriever,
+    Purgeable,
+    StatusReporter,
+    Submitter,
+)
+
 try:
     __version__ = get_version(__name__)
-    version = __version__
 except PackageNotFoundError:
-    version = "Unknown"
+    __version__ = "unknown"
+version = __version__
 
-__all__ = ["__version__"]
+__all__ = [
+    "__version__",
+    "registry",
+    # protocols
+    "Diagnosable",
+    "JobBackend",
+    "Killable",
+    "OutputRetriever",
+    "Purgeable",
+    "StatusReporter",
+    "Submitter",
+    # data types
+    "ContainerSpec",
+    "CopyVars",
+    "Diagnostics",
+    "FileRef",
+    "JobHandle",
+    "JobID",
+    "JobOutput",
+    "JobStatus",
+    "OpOutcome",
+    "OutputMember",
+    "OutputSpec",
+    "Resources",
+    "StatusMap",
+    "Submission",
+    "SubmissionSpec",
+    # configuration
+    "BackendConfig",
+    # exceptions
+    "AuthenticationError",
+    "ConfigurationError",
+    "InterCEdeError",
+    "RegistryError",
+    "ResourceUnavailableError",
+    "SpecificationRejectedError",
+]

src/intercede/_backends/__init__.py

@@ -0,0 +1 @@
+"""Internal backend implementations. Nothing here is public API."""

src/intercede/_backends/batch/__init__.py

@@ -0,0 +1 @@
+"""The composed backend: a transport combined with a scheduler."""