koia-scene-model 1.0.0__tar.gz

koia_scene_model-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+packages/java/target/
+packages/python/dist/
+packages/python/**/__pycache__/
+packages/python/*.egg-info/
+*.tgz
+bash.exe.stackdump
+.venv/
+packages/java/.flattened-pom.xml

koia_scene_model-1.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: koia-scene-model
+Version: 1.0.0
+Summary: Pydantic models generated from the Koia scene JSON Schema, for programs that write scenes into CouchDB for Koia
+Project-URL: Homepage, https://github.com/centeractive/koia-scene-schema
+Author-email: centeractive ag <info@centeractive.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: test
+Requires-Dist: jsonschema==4.26.0; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# koia-scene-model
+
+Pydantic models generated from the [Koia scene JSON Schema](https://github.com/centeractive/koia-scene-schema), plus the packaged schemas.
+
+```python
+from koia_scene_model import SceneDocument, SceneColumn, schema_path
+
+scene = SceneDocument(creationTime=1767225600000, name='Logs', shortDescription='', database='data_1',
+                      columns=[SceneColumn(name='Data', dataType='Text')], schemaVersion='1.0')
+print(scene.model_dump_json(by_alias=True, exclude_none=True))
+```
+
+See [SPEC.md](https://github.com/centeractive/koia-scene-schema/blob/main/docs/SPEC.md) for the rules beyond the schema.

koia_scene_model-1.0.0/README.md

@@ -0,0 +1,13 @@
+# koia-scene-model
+
+Pydantic models generated from the [Koia scene JSON Schema](https://github.com/centeractive/koia-scene-schema), plus the packaged schemas.
+
+```python
+from koia_scene_model import SceneDocument, SceneColumn, schema_path
+
+scene = SceneDocument(creationTime=1767225600000, name='Logs', shortDescription='', database='data_1',
+                      columns=[SceneColumn(name='Data', dataType='Text')], schemaVersion='1.0')
+print(scene.model_dump_json(by_alias=True, exclude_none=True))
+```
+
+See [SPEC.md](https://github.com/centeractive/koia-scene-schema/blob/main/docs/SPEC.md) for the rules beyond the schema.

koia_scene_model-1.0.0/generate.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+# generates the pydantic models of the newest major into the file passed as $1 (default: koia_scene_model/v1.py)
+set -e
+cd "$(dirname "$0")"
+datamodel-codegen \
+  --input ../../schemas/1.0/scene.schema.json \
+  --input-file-type jsonschema \
+  --output-model-type pydantic_v2.BaseModel \
+  --use-title-as-name \
+  --disable-timestamp \
+  --target-python-version 3.10 \
+  --formatters black isort \
+  --output "${1:-koia_scene_model/v1.py}"

koia_scene_model-1.0.0/hatch_build.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+SCHEMAS = Path(__file__).parent.parent.parent / "schemas"
+
+
+class SchemasBuildHook(BuildHookInterface):
+    """
+    includes the repository schemas when building from the source tree, a build from the sdist finds them inside the package
+    """
+
+    def initialize(self, version, build_data):
+        if SCHEMAS.is_dir():
+            build_data["force_include"][str(SCHEMAS)] = "koia_scene_model/schemas"

koia_scene_model-1.0.0/koia_scene_model/__init__.py

@@ -0,0 +1,14 @@
+from importlib.resources import files
+
+from .v1 import ContextInfo, SceneColumn, SceneConfig, SceneDocument
+
+__all__ = ["ContextInfo", "SceneColumn", "SceneConfig", "SceneDocument", "schema_path"]
+
+
+def schema_path(version: str, kind: str):
+    """
+    :param version: scene format version, e.g. '1.0'
+    :param kind: 'scene' or 'entry'
+    :returns: the packaged JSON Schema file
+    """
+    return files(__package__) / "schemas" / version / f"{kind}.schema.json"

koia_scene_model-1.0.0/koia_scene_model/schemas/1.0/entry.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://www.koia.io/assets/scene-format/1.0/entry.schema.json",
+  "title": "EntryDocument",
+  "description": "Entry document in the entries database of a scene, format 1.0; property names equal the column names of the scene",
+  "type": "object",
+  "properties": {
+    "_id": {
+      "type": "string",
+      "description": "entry id, generated by CouchDB when omitted"
+    }
+  },
+  "additionalProperties": {
+    "anyOf": [
+      { "type": "string" },
+      { "type": "number" },
+      { "type": "boolean" }
+    ]
+  }
+}

koia_scene_model-1.0.0/koia_scene_model/schemas/1.0/scene.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://www.koia.io/assets/scene-format/1.0/scene.schema.json",
+  "title": "SceneDocument",
+  "description": "Scene document in the CouchDB database 'scenes', format 1.0",
+  "type": "object",
+  "required": ["creationTime", "name", "shortDescription", "database", "columns"],
+  "properties": {
+    "_id": {
+      "type": "string",
+      "description": "scene id, generated by CouchDB when omitted"
+    },
+    "_rev": {
+      "type": "string",
+      "description": "CouchDB revision, omitted on insert"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+$",
+      "description": "scene format the document complies with; documents without it are read as format 1.0"
+    },
+    "creationTime": {
+      "type": "integer",
+      "description": "creation time in milliseconds since the epoch; scenes without it are not listed by Koia"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "shortDescription": {
+      "type": "string"
+    },
+    "database": {
+      "type": "string",
+      "minLength": 1,
+      "description": "name of the CouchDB database that holds the entries of the scene"
+    },
+    "context": {
+      "type": "array",
+      "description": "name/value pairs describing the origin of the data",
+      "items": { "$ref": "#/definitions/contextInfo" }
+    },
+    "columns": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/column" }
+    },
+    "config": { "$ref": "#/definitions/config" }
+  },
+  "definitions": {
+    "column": {
+      "title": "SceneColumn",
+      "type": "object",
+      "required": ["name", "dataType"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "column name, equal to the property name in the entries"
+        },
+        "dataType": {
+          "type": "string",
+          "enum": ["Boolean", "Number", "Object", "Text", "Time"],
+          "description": "Time values are milliseconds since the epoch, Object values are JSON strings"
+        },
+        "width": {
+          "type": "number",
+          "minimum": 0
+        },
+        "format": {
+          "type": "string",
+          "description": "display format of Time values (e.g. 'yyyy-MM-dd HH:mm:ss,SSS')"
+        },
+        "indexed": {
+          "type": "boolean",
+          "description": "requires exactly one CouchDB index on this column in the entries database"
+        }
+      }
+    },
+    "contextInfo": {
+      "title": "ContextInfo",
+      "type": "object",
+      "required": ["name", "value"],
+      "properties": {
+        "name": { "type": "string" },
+        "value": { "type": "string" }
+      }
+    },
+    "config": {
+      "title": "SceneConfig",
+      "description": "owned by Koia; writers of format 1.0 SHOULD write {\"records\":[],\"views\":[]}, the form accepted by every Koia deployment",
+      "type": "object",
+      "properties": {
+        "records": { "type": "array", "items": {} },
+        "views": { "type": "array", "items": {} }
+      }
+    }
+  }
+}

koia_scene_model-1.0.0/koia_scene_model/v1.py

@@ -0,0 +1,74 @@
+# generated by datamodel-codegen:
+#   filename:  scene.schema.json
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, confloat, constr
+
+
+class DataType(Enum):
+    Boolean = 'Boolean'
+    Number = 'Number'
+    Object = 'Object'
+    Text = 'Text'
+    Time = 'Time'
+
+
+class SceneColumn(BaseModel):
+    name: constr(min_length=1) = Field(
+        ..., description='column name, equal to the property name in the entries'
+    )
+    dataType: DataType = Field(
+        ...,
+        description='Time values are milliseconds since the epoch, Object values are JSON strings',
+    )
+    width: confloat(ge=0.0) | None = None
+    format: str | None = Field(
+        None,
+        description="display format of Time values (e.g. 'yyyy-MM-dd HH:mm:ss,SSS')",
+    )
+    indexed: bool | None = Field(
+        None,
+        description='requires exactly one CouchDB index on this column in the entries database',
+    )
+
+
+class ContextInfo(BaseModel):
+    name: str
+    value: str
+
+
+class SceneConfig(BaseModel):
+    records: list[Any] | None = None
+    views: list[Any] | None = None
+
+
+class SceneDocument(BaseModel):
+    field_id: str | None = Field(
+        None, alias='_id', description='scene id, generated by CouchDB when omitted'
+    )
+    field_rev: str | None = Field(
+        None, alias='_rev', description='CouchDB revision, omitted on insert'
+    )
+    schemaVersion: constr(pattern=r'^[0-9]+\.[0-9]+$') | None = Field(
+        None,
+        description='scene format the document complies with; documents without it are read as format 1.0',
+    )
+    creationTime: int = Field(
+        ...,
+        description='creation time in milliseconds since the epoch; scenes without it are not listed by Koia',
+    )
+    name: constr(min_length=1)
+    shortDescription: str
+    database: constr(min_length=1) = Field(
+        ...,
+        description='name of the CouchDB database that holds the entries of the scene',
+    )
+    context: list[ContextInfo] | None = Field(
+        None, description='name/value pairs describing the origin of the data'
+    )
+    columns: list[SceneColumn] = Field(..., min_length=1)
+    config: SceneConfig | None = None

koia_scene_model-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "koia-scene-model"
+dynamic = ["version"]
+description = "Pydantic models generated from the Koia scene JSON Schema, for programs that write scenes into CouchDB for Koia"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "centeractive ag", email = "info@centeractive.com" }]
+requires-python = ">=3.10"
+dependencies = ["pydantic>=2,<3"]
+
+[project.urls]
+Homepage = "https://github.com/centeractive/koia-scene-schema"
+
+[project.optional-dependencies]
+test = ["pytest", "jsonschema==4.26.0"]
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../.." }
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["koia_scene_model"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

koia_scene_model-1.0.0/tests/test_scene_model.py

@@ -0,0 +1,20 @@
+import json
+from pathlib import Path
+
+import jsonschema
+import pytest
+
+from koia_scene_model import SceneDocument, schema_path
+
+VALID_EXAMPLES = sorted((Path(__file__).parent.parent.parent.parent / "examples" / "1.0" / "valid").glob("*.json"))
+
+
+@pytest.mark.parametrize("example", VALID_EXAMPLES, ids=lambda p: p.stem)
+def test_valid_example_validates_and_parses(example):
+    document = json.loads(example.read_text(encoding="utf-8"))
+    schema = json.loads(schema_path("1.0", "scene").read_text(encoding="utf-8"))
+
+    jsonschema.Draft7Validator(schema).validate(document)
+    scene = SceneDocument.model_validate(document)
+
+    jsonschema.Draft7Validator(schema).validate(scene.model_dump(mode="json", by_alias=True, exclude_none=True))