vcti-usd-schema-report 0.1.0__tar.gz

vcti_usd_schema_report-0.1.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_usd_schema_report-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: vcti-usd-schema-report
+Version: 0.1.0
+Summary: Codeless OpenUSD schema for the VCollab report model, the slides of a report and the deck that arranges them: schema source, generated plugin, synthetic fixtures and a validator
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Repository, https://github.com/vcollab/vcti-python-usd-schema-report
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-usd-schema-report/blob/main/CHANGELOG.md
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: usd-core<27,>=26.11
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Provides-Extra: schema
+Requires-Dist: jinja2; extra == "schema"
+Dynamic: license-file
+
+# VCollab USD Report Schema
+
+Codeless OpenUSD schema for the VCollab report model, the slides of a report and the deck that arranges them: schema source, generated plugin, synthetic fixtures and a validator
+
+## Overview
+
+A VCollab report is a set of slides made from one or more models. It is
+defined by its variables and its workflow, which are stored as JSON;
+everything else is produced by running the workflow, and the server holds
+that as a USD stage. This package defines the part of that stage that holds
+the slides and the deck.
+
+The stage keeps two things apart. The **list** holds every slide and
+section, flat, each named by a prim path that never changes. The **deck**
+is a tree of nodes under `/Report/deck` that arranges some of them: each
+node places one item, nesting is the hierarchy, and the order of a node's
+children is the order of the deck. Renaming, reordering or moving an item
+touches its name or the nodes, never its path. A slide the deck does not
+reach is a view kept while working.
+
+This package ships that schema as a codeless USD plugin, the declarations
+it is generated from, three fixture reports that each exercise one group of
+contracts, authoring helpers that make the changes the viewer protocol's
+deck actions call for, and the validator a server-built stage must pass
+unchanged. It is a sibling of `vcti-usd-schema-delivery`, which describes a
+model. The schema is a candidate, and a slide's content, the capture of the
+screen, is not designed yet: a slide today is a name and the user's
+attributes.
+
+## Installation
+
+```bash
+pip install vcti-usd-schema-report
+```
+
+### In `requirements.txt`
+
+```
+vcti-usd-schema-report>=0.1.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-usd-schema-report>=0.1.0",
+]
+```
+
+---
+
+## Quick Start
+
+### Validate a stage
+
+```python
+from vcti.usd.schema.report import open_fixture, validate
+
+stage = open_fixture("results_deck")
+errors = validate(stage)
+print(errors)  # [] for a conforming stage
+```
+
+`open_fixture` and `open_stage` register the plugin first. Any failure is
+one string: the path of the prim it concerns, then a short stable phrase.
+
+### Open your own stage with the plugin registered
+
+```python
+from pxr import Usd
+
+from vcti.usd.schema.report import fixture_path, register_plugin
+
+register_plugin()
+stage = Usd.Stage.Open(str(fixture_path("nested_sections")))
+report = stage.GetPrimAtPath("/Report")
+print(report.GetTypeName(), report.GetAttribute("vct:schemaVersion").Get())
+```
+
+Registration is explicit and idempotent, and it also registers every
+installed sibling schema, such as the delivery schema's. USD only knows the
+plugins registered before it first looks up a typed prim, so a process that
+opens stages itself calls `register_plugin()` before the first one.
+
+### Build and edit a report
+
+The helpers take the prim name of anything they create, because allocating
+it is the server's rule, and return the item's path, its identity from then
+on.
+
+```python
+from vcti.usd.schema.report import (
+    DECK_PATH,
+    Position,
+    add_section,
+    add_slide,
+    logical_path,
+    move_item,
+    new_report_stage,
+    rename_item,
+    validate,
+)
+
+stage = new_report_stage()
+deck = Position(parent=DECK_PATH)
+overview = add_slide(stage, "s1", "Overview", position=deck)
+results = add_section(stage, "k1", "Results", position=deck)
+stress = add_slide(stage, "s2", "Stress", {"load_case": "LC1"}, Position(parent=results))
+kept = add_slide(stage, "s3", "Before the change")  # in the list, not in the deck
+
+rename_item(stage, results, "Findings")
+move_item(stage, overview, Position(after=stress))
+
+print(stress, logical_path(stage, stress))  # /Report/slides/s2 /Findings/Stress
+print(validate(stage))  # []
+```
+
+### From the command line
+
+```bash
+vcti-usd-report-validate report.usda other.usda
+```
+
+One line per stage, `PASS` or `FAIL`, each failure indented beneath it, and
+a non-zero exit status when any stage fails or cannot be opened.
+
+---
+
+## Key API
+
+| Name | What it does |
+|---|---|
+| `register_plugin()` | Register the shipped codeless plugin, and every installed sibling schema's, with this process, once |
+| `open_stage(path)`, `open_fixture(name)` | Open with the plugin registered |
+| `validate(stage)`, `validate_file(path)` | Every contract the schema states, as a list of messages |
+| `new_report_stage(path)` | A stage holding an empty report |
+| `add_slide`, `add_section`, `duplicate_slide`, `duplicate_section` | New items, optionally placed in the deck |
+| `rename_item`, `move_item`, `remove_item`, `set_attributes` | Changes to an item or to where it is |
+| `Position(parent=…)`, `Position(after=…)`, `Position(before=…)` | Where an item goes in the deck |
+| `node_of(stage, item)`, `logical_path(stage, item)` | An item's node, and the path rules look it up by |
+| `fixture_path(name)`, `fixture_paths()`, `FIXTURE_NAMES`, `build_fixtures(dir)` | The three shipped reports, and writing them again |
+| `render_schema()`, `write_schema(path)` | The `schema.usda` text, from the declarations |
+| `SCHEMA_VERSION`, `REPORT_PATH`, `DECK_PATH`, `ITEM_TYPES`, … | The fixed names |
+
+The types:
+
+| Type | Properties | Purpose |
+|---|---|---|
+| `VctReport` | `uniform string vct:schemaVersion` | Anchor for one report, at `/Report` |
+| `VctSlide` | `string vct:name`; `attr:*` | One slide, under `/Report/slides` |
+| `VctSection` | `string vct:name`; `attr:*` | One section, under `/Report/sections` |
+| `VctDeck` | none | The hierarchy's fixed root, `/Report/deck` |
+| `VctDeckNode` | `rel vct:item` | Places one slide or section in the deck |
+
+The fixtures, in reading order:
+
+| Fixture | Scenario | Contracts it exercises |
+|---|---|---|
+| `results_deck` | Three slides, one section | The list beside the hierarchy, a slide outside the deck, a user attribute |
+| `nested_sections` | Sections inside sections | Depth and order, an empty section, a section outside the deck, repeated names, scalar attribute types |
+| `working_views` | Two slides, nothing arranged | An empty deck; the scopes and the deck are always present |
+
+---
+
+## Dependencies
+
+- `usd-core` 26.11 or later within the 26 series, the OpenUSD Python
+  distribution. The shipped plugin was generated by that version's
+  `usdGenSchema`, so a new major is admitted only after regeneration.
+- `jinja2`, in the `schema` extra, only to regenerate the plugin.
+
+It does not depend on `vcti-usd-schema-delivery`.
+
+---
+
+## Documentation
+
+| If you want to… | Read |
+|---|---|
+| Get started using the package | Quick Start above |
+| Build, edit and read a report, fixture by fixture | [docs/patterns.md](docs/patterns.md) |
+| Understand the list, the deck and the decisions behind them | [docs/design.md](docs/design.md) |
+| Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
+| Add a type, a property, a check, an action or a fixture | [docs/extending.md](docs/extending.md) |
+| See what changed | [CHANGELOG.md](CHANGELOG.md) |

vcti_usd_schema_report-0.1.0/README.md

@@ -0,0 +1,185 @@
+# VCollab USD Report Schema
+
+Codeless OpenUSD schema for the VCollab report model, the slides of a report and the deck that arranges them: schema source, generated plugin, synthetic fixtures and a validator
+
+## Overview
+
+A VCollab report is a set of slides made from one or more models. It is
+defined by its variables and its workflow, which are stored as JSON;
+everything else is produced by running the workflow, and the server holds
+that as a USD stage. This package defines the part of that stage that holds
+the slides and the deck.
+
+The stage keeps two things apart. The **list** holds every slide and
+section, flat, each named by a prim path that never changes. The **deck**
+is a tree of nodes under `/Report/deck` that arranges some of them: each
+node places one item, nesting is the hierarchy, and the order of a node's
+children is the order of the deck. Renaming, reordering or moving an item
+touches its name or the nodes, never its path. A slide the deck does not
+reach is a view kept while working.
+
+This package ships that schema as a codeless USD plugin, the declarations
+it is generated from, three fixture reports that each exercise one group of
+contracts, authoring helpers that make the changes the viewer protocol's
+deck actions call for, and the validator a server-built stage must pass
+unchanged. It is a sibling of `vcti-usd-schema-delivery`, which describes a
+model. The schema is a candidate, and a slide's content, the capture of the
+screen, is not designed yet: a slide today is a name and the user's
+attributes.
+
+## Installation
+
+```bash
+pip install vcti-usd-schema-report
+```
+
+### In `requirements.txt`
+
+```
+vcti-usd-schema-report>=0.1.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-usd-schema-report>=0.1.0",
+]
+```
+
+---
+
+## Quick Start
+
+### Validate a stage
+
+```python
+from vcti.usd.schema.report import open_fixture, validate
+
+stage = open_fixture("results_deck")
+errors = validate(stage)
+print(errors)  # [] for a conforming stage
+```
+
+`open_fixture` and `open_stage` register the plugin first. Any failure is
+one string: the path of the prim it concerns, then a short stable phrase.
+
+### Open your own stage with the plugin registered
+
+```python
+from pxr import Usd
+
+from vcti.usd.schema.report import fixture_path, register_plugin
+
+register_plugin()
+stage = Usd.Stage.Open(str(fixture_path("nested_sections")))
+report = stage.GetPrimAtPath("/Report")
+print(report.GetTypeName(), report.GetAttribute("vct:schemaVersion").Get())
+```
+
+Registration is explicit and idempotent, and it also registers every
+installed sibling schema, such as the delivery schema's. USD only knows the
+plugins registered before it first looks up a typed prim, so a process that
+opens stages itself calls `register_plugin()` before the first one.
+
+### Build and edit a report
+
+The helpers take the prim name of anything they create, because allocating
+it is the server's rule, and return the item's path, its identity from then
+on.
+
+```python
+from vcti.usd.schema.report import (
+    DECK_PATH,
+    Position,
+    add_section,
+    add_slide,
+    logical_path,
+    move_item,
+    new_report_stage,
+    rename_item,
+    validate,
+)
+
+stage = new_report_stage()
+deck = Position(parent=DECK_PATH)
+overview = add_slide(stage, "s1", "Overview", position=deck)
+results = add_section(stage, "k1", "Results", position=deck)
+stress = add_slide(stage, "s2", "Stress", {"load_case": "LC1"}, Position(parent=results))
+kept = add_slide(stage, "s3", "Before the change")  # in the list, not in the deck
+
+rename_item(stage, results, "Findings")
+move_item(stage, overview, Position(after=stress))
+
+print(stress, logical_path(stage, stress))  # /Report/slides/s2 /Findings/Stress
+print(validate(stage))  # []
+```
+
+### From the command line
+
+```bash
+vcti-usd-report-validate report.usda other.usda
+```
+
+One line per stage, `PASS` or `FAIL`, each failure indented beneath it, and
+a non-zero exit status when any stage fails or cannot be opened.
+
+---
+
+## Key API
+
+| Name | What it does |
+|---|---|
+| `register_plugin()` | Register the shipped codeless plugin, and every installed sibling schema's, with this process, once |
+| `open_stage(path)`, `open_fixture(name)` | Open with the plugin registered |
+| `validate(stage)`, `validate_file(path)` | Every contract the schema states, as a list of messages |
+| `new_report_stage(path)` | A stage holding an empty report |
+| `add_slide`, `add_section`, `duplicate_slide`, `duplicate_section` | New items, optionally placed in the deck |
+| `rename_item`, `move_item`, `remove_item`, `set_attributes` | Changes to an item or to where it is |
+| `Position(parent=…)`, `Position(after=…)`, `Position(before=…)` | Where an item goes in the deck |
+| `node_of(stage, item)`, `logical_path(stage, item)` | An item's node, and the path rules look it up by |
+| `fixture_path(name)`, `fixture_paths()`, `FIXTURE_NAMES`, `build_fixtures(dir)` | The three shipped reports, and writing them again |
+| `render_schema()`, `write_schema(path)` | The `schema.usda` text, from the declarations |
+| `SCHEMA_VERSION`, `REPORT_PATH`, `DECK_PATH`, `ITEM_TYPES`, … | The fixed names |
+
+The types:
+
+| Type | Properties | Purpose |
+|---|---|---|
+| `VctReport` | `uniform string vct:schemaVersion` | Anchor for one report, at `/Report` |
+| `VctSlide` | `string vct:name`; `attr:*` | One slide, under `/Report/slides` |
+| `VctSection` | `string vct:name`; `attr:*` | One section, under `/Report/sections` |
+| `VctDeck` | none | The hierarchy's fixed root, `/Report/deck` |
+| `VctDeckNode` | `rel vct:item` | Places one slide or section in the deck |
+
+The fixtures, in reading order:
+
+| Fixture | Scenario | Contracts it exercises |
+|---|---|---|
+| `results_deck` | Three slides, one section | The list beside the hierarchy, a slide outside the deck, a user attribute |
+| `nested_sections` | Sections inside sections | Depth and order, an empty section, a section outside the deck, repeated names, scalar attribute types |
+| `working_views` | Two slides, nothing arranged | An empty deck; the scopes and the deck are always present |
+
+---
+
+## Dependencies
+
+- `usd-core` 26.11 or later within the 26 series, the OpenUSD Python
+  distribution. The shipped plugin was generated by that version's
+  `usdGenSchema`, so a new major is admitted only after regeneration.
+- `jinja2`, in the `schema` extra, only to regenerate the plugin.
+
+It does not depend on `vcti-usd-schema-delivery`.
+
+---
+
+## Documentation
+
+| If you want to… | Read |
+|---|---|
+| Get started using the package | Quick Start above |
+| Build, edit and read a report, fixture by fixture | [docs/patterns.md](docs/patterns.md) |
+| Understand the list, the deck and the decisions behind them | [docs/design.md](docs/design.md) |
+| Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
+| Add a type, a property, a check, an action or a fixture | [docs/extending.md](docs/extending.md) |
+| See what changed | [CHANGELOG.md](CHANGELOG.md) |

vcti_usd_schema_report-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-usd-schema-report"
+version = "0.1.0"
+description = "Codeless OpenUSD schema for the VCollab report model, the slides of a report and the deck that arranges them: schema source, generated plugin, synthetic fixtures and a validator"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    # The shipped plugin was generated by usdGenSchema 26.11; a new major is
+    # admitted only after the plugin is regenerated and checked against it.
+    "usd-core>=26.11,<27",
+]
+
+[project.urls]
+Repository = "https://github.com/vcollab/vcti-python-usd-schema-report"
+Changelog = "https://github.com/vcollab/vcti-python-usd-schema-report/blob/main/CHANGELOG.md"
+
+[project.scripts]
+vcti-usd-report-validate = "vcti.usd.schema.report.cli:main"
+
+# Every schema package of the family names its plugin directory here, and
+# each one's register_plugin() registers them all; see registry.py.
+[project.entry-points."vcti.usd.schema"]
+report = "vcti.usd.schema.report.registry:PLUGIN_DIR"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.usd.schema.report", "vcti.usd.schema.report.*"]
+
+[tool.setuptools.package-data]
+"vcti.usd.schema.report" = [
+    "py.typed",
+    "plugin/*.json",
+    "plugin/*.usda",
+    "stages/*.usda",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+# usdGenSchema, which regenerates the plugin, renders its output with jinja2.
+schema = ["jinja2"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.usd.schema.report --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "^\\s*\\.\\.\\.\\s*$",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]
+
+# usd-core ships no type information, so its modules are untyped here.
+[[tool.mypy.overrides]]
+module = ["pxr.*"]
+ignore_missing_imports = true

vcti_usd_schema_report-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_usd_schema_report-0.1.0/src/vcti/usd/schema/report/__init__.py

@@ -0,0 +1,110 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.usd.schema.report: the OpenUSD schema for the VCollab report model.
+
+A report's slides and its deck, as the stage the VCollab server holds once it
+has run the report's workflow. The stage keeps two things apart: the list,
+every slide and section, flat and named by prim path; and the deck, a tree of
+nodes that arranges some of them in order. This package ships that schema as
+a codeless USD plugin, the declarations it is generated from, three fixture
+reports that exercise its contracts, the authoring helpers that make the
+changes the protocol's deck actions call for, and the validator a
+server-built stage must pass.
+
+Typical use::
+
+    from vcti.usd.schema.report import open_fixture, validate
+
+    stage = open_fixture("results_deck")
+    assert validate(stage) == []
+"""
+
+from importlib.metadata import version
+
+from .builder import (
+    Position,
+    add_section,
+    add_slide,
+    build_fixtures,
+    duplicate_section,
+    duplicate_slide,
+    finish,
+    item_path,
+    logical_path,
+    move_item,
+    new_report_stage,
+    node_of,
+    remove_item,
+    rename_item,
+    set_attributes,
+)
+from .declarations import normalize_plugin_info, render_schema, write_schema
+from .fixtures import (
+    FIXTURE_NAMES,
+    STAGES_DIR,
+    fixture_path,
+    fixture_paths,
+    open_fixture,
+    open_stage,
+)
+from .registry import ENTRY_POINT_GROUP, PLUGIN_DIR, is_registered, plugin_dirs, register_plugin
+from .validator import validate, validate_file
+from .vocabulary import (
+    ATTRIBUTE_NAMESPACE,
+    DECK_NAME,
+    DECK_PATH,
+    ITEM_SCOPES,
+    ITEM_TYPES,
+    LIBRARY_NAME,
+    REPORT_PATH,
+    SCHEMA_VERSION,
+    SECTIONS_SCOPE,
+    SLIDES_SCOPE,
+)
+
+__version__ = version("vcti-usd-schema-report")
+
+__all__ = [
+    "ATTRIBUTE_NAMESPACE",
+    "DECK_NAME",
+    "DECK_PATH",
+    "ENTRY_POINT_GROUP",
+    "FIXTURE_NAMES",
+    "ITEM_SCOPES",
+    "ITEM_TYPES",
+    "LIBRARY_NAME",
+    "PLUGIN_DIR",
+    "REPORT_PATH",
+    "SCHEMA_VERSION",
+    "SECTIONS_SCOPE",
+    "SLIDES_SCOPE",
+    "STAGES_DIR",
+    "Position",
+    "__version__",
+    "add_section",
+    "add_slide",
+    "build_fixtures",
+    "duplicate_section",
+    "duplicate_slide",
+    "finish",
+    "fixture_path",
+    "fixture_paths",
+    "is_registered",
+    "item_path",
+    "logical_path",
+    "move_item",
+    "new_report_stage",
+    "node_of",
+    "normalize_plugin_info",
+    "open_fixture",
+    "open_stage",
+    "plugin_dirs",
+    "register_plugin",
+    "remove_item",
+    "rename_item",
+    "render_schema",
+    "set_attributes",
+    "validate",
+    "validate_file",
+    "write_schema",
+]