arrakis-schema 0.1.0__tar.gz

arrakis_schema-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# build artifacts
+*.egg-info
+build/
+dist/
+site/
+__pycache__
+
+# test artifacts
+.coverage*

arrakis_schema-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: arrakis-schema
+Version: 0.1.0
+Summary: Schemas for the Arrakis API
+Project-URL: Homepage, https://git.ligo.org/ngdd/arrakis-schema
+Project-URL: Documentation, https://docs.ligo.org/ngdd/arrakis-schema
+Project-URL: Issue Tracker, https://git.ligo.org/ngdd/arrakis-schema/issues
+Project-URL: Source Code, https://git.ligo.org/ngdd/arrakis-schema.git
+Author-email: Patrick Godwin <patrick.godwin@ligo.org>, Jameson Graef Rollins <jameson.rollins@ligo.org>
+Maintainer-email: Patrick Godwin <patrick.godwin@ligo.org>
+License-Expression: LGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: arrakis[docs]; extra == 'dev'
+Requires-Dist: arrakis[lint]; extra == 'dev'
+Requires-Dist: arrakis[test]; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: markdown-callouts>=0.2; extra == 'docs'
+Requires-Dist: markdown-exec>=0.5; extra == 'docs'
+Requires-Dist: mkdocs-coverage>=0.2; extra == 'docs'
+Requires-Dist: mkdocs-gen-files>=0.3; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav>=0.4; extra == 'docs'
+Requires-Dist: mkdocs-material-igwn; extra == 'docs'
+Requires-Dist: mkdocs-section-index>=0.3; extra == 'docs'
+Requires-Dist: mkdocs>=1.3; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Requires-Dist: toml>=0.10; extra == 'docs'
+Provides-Extra: lint
+Requires-Dist: mypy; extra == 'lint'
+Requires-Dist: mypy-extensions; extra == 'lint'
+Requires-Dist: pip; extra == 'lint'
+Requires-Dist: ruff; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+<h1 align="center">arrakis-schema</h1>
+
+<p align="center">Schemas for the Arrakis API</p>
+
+<p align="center">
+</p>
+
+---
+
+## Endpoints
+
+The Arrakis server responds to API requests corresponding to the four
+main actions exposed by the client API:
+
+* **stream**
+* **describe**
+* **find**
+* **count**
+
+as well as two actions which aid in publication:
+
+* **partition**
+* **publish**
+
+All API requests are done in a two-stage approach by first sending an
+Arrow Flight descriptor to the server, returning back a Flight info object
+which contains the request and the server to contact, contained within
+a Flight ticket. This ticket is then sent to receive back the expected
+payload with a specific Arrow flight schema dependent on the request,
+serialized in the Arrow 
+![streaming format](https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format).
+
+The Flight descriptors sent to the server in the first stage are all
+specified here as JSON packets which are UTF-8-encoded, using the command
+variant of the Flight descriptor, which can be used to specify any
+application-specific command.
+
+## Schemas
+
+The generic Flight descriptor schema is described within each endpoint in
+`{endpoint}.json`. In addition, a generic descriptor specification for all
+endpoints is described in `descriptor.json`.
+
+## Usage
+
+
+```python
+
+from arrakis_schema import load_schema
+
+schema = load_schema("count.json")
+
+```

arrakis_schema-0.1.0/README.md

@@ -0,0 +1,53 @@
+<h1 align="center">arrakis-schema</h1>
+
+<p align="center">Schemas for the Arrakis API</p>
+
+<p align="center">
+</p>
+
+---
+
+## Endpoints
+
+The Arrakis server responds to API requests corresponding to the four
+main actions exposed by the client API:
+
+* **stream**
+* **describe**
+* **find**
+* **count**
+
+as well as two actions which aid in publication:
+
+* **partition**
+* **publish**
+
+All API requests are done in a two-stage approach by first sending an
+Arrow Flight descriptor to the server, returning back a Flight info object
+which contains the request and the server to contact, contained within
+a Flight ticket. This ticket is then sent to receive back the expected
+payload with a specific Arrow flight schema dependent on the request,
+serialized in the Arrow 
+![streaming format](https://arrow.apache.org/docs/format/Columnar.html#ipc-streaming-format).
+
+The Flight descriptors sent to the server in the first stage are all
+specified here as JSON packets which are UTF-8-encoded, using the command
+variant of the Flight descriptor, which can be used to specify any
+application-specific command.
+
+## Schemas
+
+The generic Flight descriptor schema is described within each endpoint in
+`{endpoint}.json`. In addition, a generic descriptor specification for all
+endpoints is described in `descriptor.json`.
+
+## Usage
+
+
+```python
+
+from arrakis_schema import load_schema
+
+schema = load_schema("count.json")
+
+```

arrakis_schema-0.1.0/arrakis_schema/__init__.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2025, California Institute of Technology and contributors
+#
+# You should have received a copy of the licensing terms for this
+# software included in the file "LICENSE" located in the top-level
+# directory of this package. If you did not, you can view a copy at
+# https://git.ligo.org/ngdd/arrakis-python/-/raw/main/LICENSE
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any, TypedDict
+
+from ._version import __version__
+
+
+class Request(TypedDict):
+    request: str
+    args: dict[str, Any]
+
+
+def load_schema(filename: str) -> Request:
+    """Load the schema associated with the filename.
+
+    Parameters
+    ----------
+    filename : str
+        The schema file to load.
+
+    Returns
+    -------
+    Request
+        The descriptor schema.
+
+    """
+    resource = resources.files().joinpath(filename)
+    with resources.as_file(resource) as path:
+        return json.loads(path.read_text())

arrakis_schema-0.1.0/arrakis_schema/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

arrakis_schema-0.1.0/arrakis_schema/count.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "arrakis-api-count",
+  "description": "v0.1",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "string",
+      "const": "Count"
+    },
+    "args": {
+      "type": "object",
+      "properties": {
+        "pattern": {
+          "type": "string"
+        },
+        "data_type": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["uint32", "uint64", "int32", "int64", "float32", "float64"]
+          }
+        },
+        "min_rate": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max_rate": {
+          "type": "integer",
+          "exclusiveminimum": 0
+        },
+        "publisher": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "pattern",
+        "data_type",
+        "min_rate",
+        "max_rate",
+        "publisher"
+      ]
+    }
+  },
+  "required": [
+    "request",
+    "args"
+  ]
+}

arrakis_schema-0.1.0/arrakis_schema/describe.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "arrakis-api-describe",
+  "description": "v0.1",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "string",
+      "const": "Describe"
+    },
+    "args": {
+      "type": "object",
+      "properties": {
+        "channels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "channels"
+      ]
+    }
+  },
+  "required": [
+    "request",
+    "args"
+  ]
+}

arrakis_schema-0.1.0/arrakis_schema/descriptor.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "arrakis-api-descriptor",
+  "description": "v0.1",
+  "type": "object",
+  "properties": {
+    "request": {
+      "enum": [
+        "Count",
+        "Describe",
+        "Find",
+        "Publish",
+        "Partition",
+        "Stream"
+      ]
+    },
+    "args": {
+      "type": "object"
+    }
+  },
+  "required": [
+    "request",
+    "args"
+  ]
+}

arrakis_schema-0.1.0/arrakis_schema/find.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "arrakis-api-find",
+  "description": "v0.1",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "string",
+      "const": "Find"
+    },
+    "args": {
+      "type": "object",
+      "properties": {
+        "pattern": {
+          "type": "string"
+        },
+        "data_type": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["uint32", "uint64", "int32", "int64", "float32", "float64"]
+          }
+        },
+        "min_rate": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max_rate": {
+          "type": "integer",
+          "exclusiveminimum": 0
+        },
+        "publisher": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "pattern",
+        "data_type",
+        "min_rate",
+        "max_rate",
+        "publisher"
+      ]
+    }
+  },
+  "required": [
+    "request",
+    "args"
+  ]
+}

arrakis_schema-0.1.0/arrakis_schema/partition.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "arrakis-api-partition",
+  "description": "v0.1",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "string",
+      "const": "Partition"
+    },
+    "args": {
+      "type": "object",
+      "properties": {
+        "publisher_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "publisher_id"
+      ]
+    }
+  },
+  "required": [
+    "request",
+    "args"
+  ]
+}

arrakis_schema-0.1.0/arrakis_schema/publish.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "arrakis-api-publish",
+  "description": "v0.1",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "string",
+      "const": "Publish"
+    },
+    "args": {
+      "type": "object",
+      "properties": {
+        "publisher_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "publisher_id"
+      ]
+    }
+  },
+  "required": [
+    "request",
+    "args"
+  ]
+}

arrakis_schema-0.1.0/arrakis_schema/stream.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "arrakis-api-stream",
+  "description": "v0.1",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "string",
+      "const": "Stream"
+    },
+    "args": {
+      "type": "object",
+      "properties": {
+        "channels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "start": {
+          "type": ["integer", "null"]
+        },
+        "end": {
+          "type": ["integer", "null"]
+        }
+      },
+      "required": [
+        "channels",
+        "start",
+        "end"
+      ]
+    }
+  },
+  "required": [
+    "request",
+    "args"
+  ]
+}

arrakis_schema-0.1.0/pyproject.toml

@@ -0,0 +1,205 @@
+[build-system]
+requires = [
+    "hatchling",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "arrakis-schema"
+authors = [
+    { name = "Patrick Godwin", email = "patrick.godwin@ligo.org" },
+    { name = "Jameson Graef Rollins", email = "jameson.rollins@ligo.org" },
+]
+maintainers = [
+    { name = "Patrick Godwin", email = "patrick.godwin@ligo.org" },
+]
+description = "Schemas for the Arrakis API"
+readme = "README.md"
+license = "LGPL-3.0-or-later"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Natural Language :: English",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Astronomy",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dynamic = ["version"]
+requires-python = ">=3.10"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+docs = [
+    "mkdocs >= 1.3",
+    "mkdocs-coverage >= 0.2",
+    "mkdocs-gen-files >= 0.3",
+    "mkdocs-literate-nav >= 0.4",
+    "mkdocs-material-igwn",
+    "mkdocs-section-index >= 0.3",
+    "mkdocstrings[python]",
+    "markdown-callouts >= 0.2",
+    "markdown-exec >= 0.5",
+    "toml >= 0.10",
+]
+lint = [
+    "mypy",
+    "mypy-extensions",
+    "pip", # mypy requires pip to install type stubs
+    "ruff",
+]
+dev = [
+    "arrakis[docs]",
+    "arrakis[lint]",
+    "arrakis[test]",
+]
+
+[project.urls]
+Homepage = "https://git.ligo.org/ngdd/arrakis-schema"
+Documentation = "https://docs.ligo.org/ngdd/arrakis-schema"
+"Issue Tracker" = "https://git.ligo.org/ngdd/arrakis-schema/issues"
+"Source Code" = "https://git.ligo.org/ngdd/arrakis-schema.git"
+
+[tool.hatch.version]
+path = "arrakis_schema/_version.py"
+
+[tool.hatch.build.targets.sdist.force-include]
+"../../endpoints/descriptor.json" = "arrakis_schema/descriptor.json"
+"../../endpoints/count/descriptor.json" = "arrakis_schema/count.json"
+"../../endpoints/describe/descriptor.json" = "arrakis_schema/describe.json"
+"../../endpoints/find/descriptor.json" = "arrakis_schema/find.json"
+"../../endpoints/partition/descriptor.json" = "arrakis_schema/partition.json"
+"../../endpoints/publish/descriptor.json" = "arrakis_schema/publish.json"
+"../../endpoints/stream/descriptor.json" = "arrakis_schema/stream.json"
+
+[tool.hatch.build.targets.wheel.force-include]
+"../../endpoints/descriptor.json" = "arrakis_schema/descriptor.json"
+"../../endpoints/count/descriptor.json" = "arrakis_schema/count.json"
+"../../endpoints/describe/descriptor.json" = "arrakis_schema/describe.json"
+"../../endpoints/find/descriptor.json" = "arrakis_schema/find.json"
+"../../endpoints/partition/descriptor.json" = "arrakis_schema/partition.json"
+"../../endpoints/publish/descriptor.json" = "arrakis_schema/publish.json"
+"../../endpoints/stream/descriptor.json" = "arrakis_schema/stream.json"
+
+[tool.hatch.envs.default]
+features = ["dev"]
+installer = "uv"
+
+[tool.hatch.envs.default.scripts]
+check = "mypy --install-types --non-interactive arrakis_schema"
+
+[tool.hatch.envs.docs]
+features = ["docs"]
+scripts.build = "mkdocs build --clean --strict"
+scripts.serve = "mkdocs serve"
+
+[tool.hatch.envs.hatch-static-analysis]
+config-path = "none"
+
+[tool.hatch.envs.hatch-test]
+features = ["test"]
+default-args = ["arrakis_schema/tests"]
+extra-args = ["-ra", "-v", "-s"]
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.10", "3.11", "3.12"]
+
+[tool.coverage.run]
+source = ["arrakis_schema"]
+omit = [
+    "arrakis_schema/tests/*",
+    "*/_version.py",
+]
+
+[tool.coverage.report]
+# print report with one decimal point
+precision = 1
+show_missing = true
+omit = [
+    "_version.py",
+    "tests/*",
+]
+
+[tool.mypy]
+check_untyped_defs = true
+ignore_missing_imports = true
+exclude = [
+    "docs",
+]
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    "W",
+    # pyflakes
+    "F",
+    # isort
+    "I",
+    # pep8-naming
+    "N",
+    # flake8-bandit
+    "S",
+    # flake8-blind-except
+    "BLE",
+    # flake8-boolean-trap
+    "FBT",
+    # flake8-bugbear
+    "B",
+    # flake8-builtins
+    "A",
+    # flake8-comprehensions
+    "C4",
+    # flake8-datetimez
+    "DTZ",
+    # flake8-errmsg
+    "EM",
+    # flake8-executable
+    "EXE",
+    # flake8-future-annotations
+    "FA",
+    # flake8-logging
+    "LOG",
+    # flake8-logging-format
+    "G",
+    # flake8-pytest-style
+    "PT",
+    # flake8-return
+    "RET",
+    # flake8-self
+    "SLF",
+    # flake8-simplify
+    "SIM",
+    # flake8-slots
+    "SLOT",
+    # flake8-type-checking
+    "TCH",
+    # tryceratops
+    "TRY",
+    # refurb
+    "FURB",
+    # ruff-specific rules
+    "RUF",
+]
+ignore = [
+    "E203",  # flags whitespace on slicing
+    "S101",  # assert statements
+    "B905",  # strict zip
+    "C414",  # unnecessary double-cast
+    "PT011",  # pytest generic raises
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]