unitysvc-data 0.1.0__py3-none-any.whl

unitysvc_data-0.1.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: unitysvc-data
+Version: 0.1.0
+Summary: Standard examples and presets for UnitySVC data packages
+Author-email: Bo Peng <bo.peng@unitysvc.com>
+Maintainer-email: Bo Peng <bo.peng@unitysvc.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/unitysvc/unitysvc-data
+Project-URL: Issues, https://github.com/unitysvc/unitysvc-sellers/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Dynamic: license-file
+
+# unitysvc-data
+
+Standard examples and presets for UnitySVC — primary consumer is
+[unitysvc-sellers](https://github.com/unitysvc/unitysvc-sellers), but the
+same preset / manifest machinery is intended to serve other parts of the
+platform too.
+
+A data-first Python package that ships:
+
+- Example files (connectivity tests, usage snippets, descriptions)
+  organised under `src/unitysvc_data/examples/<gateway>/<family>/`.
+- A generated manifest (`_manifest.json`) mapping every preset name to
+  its metadata and bundled file.
+- Two primitives for consumers:
+  - `doc_preset(source, **overrides)` — returns a full document
+    record (category, description, mime_type, file_path, ...) ready
+    to drop into `listing.json`. This is the expansion the SDK
+    applies to `$preset` JSON sentinels at upload time.
+  - `file_preset(source)` — returns the raw UTF-8 content of the
+    preset's bundled file. Useful when the example isn't a listing
+    document (embed as snippet, feed to a test harness, etc.).
+
+Both accept either a bare name (`"s3_connectivity"`,
+`"s3_connectivity_v1"`) or a `{"$preset": "...", "$with": {...}}`
+sentinel, so the same function works from JSON walkers and from
+programmatic Python code.
+
+Sellers reference a preset from their `listing.json` like this:
+
+```json
+{
+  "documents": {
+    "Connectivity test": { "$preset": "s3_connectivity" },
+    "Usage (Python)":    { "$preset": "s3_code_example_v1",
+                           "$with": { "description": "Lists objects in our bucket" } }
+  }
+}
+```
+
+The SDK walks the parsed listing and calls `doc_preset(...)` on each
+sentinel, substituting the bundled file's absolute path into
+`file_path`, then feeds the result into the existing upload pipeline.
+No custom URL scheme, no extra render pass.
+
+## CLI
+
+Installing the package provides a `usvc_data` command for shell-level
+access to the same data:
+
+```bash
+usvc_data list                                       # every preset + aliases
+usvc_data list --json                                # machine-readable form
+
+usvc_data info s3_connectivity                       # README prose for a preset
+
+usvc_data doc-preset s3_connectivity                 # expanded JSON record
+usvc_data doc-preset s3_connectivity --with '{"description":"ours"}'
+usvc_data doc-preset s3_connectivity --compact       # single-line JSON
+
+usvc_data file-preset s3_connectivity                # raw file content to stdout
+usvc_data file-preset s3_connectivity > /tmp/s3.py   # pipe to file (raw template)
+```
+
+Note that `file-preset` returns the raw file content — `.j2` templates
+come through with Jinja2 markers intact. The sellers SDK renders them
+with per-listing context at upload time; if you pipe a `.j2` preset
+directly to an executable file you'll get a template, not a runnable
+script.
+
+`--with` accepts a JSON object whose keys are the overridable fields
+(`description`, `is_active`, `is_public`, `meta`). Forbidden keys and
+unknown preset names exit with status 1 and a message on stderr.
+
+## Layout
+
+```
+src/unitysvc_data/
+├── __init__.py              # example_path / read_example / list_examples
+├── presets.py               # doc_preset / file_preset / PRESETS / ALIASES
+├── cli.py                   # usvc_data entry point
+├── _manifest.json           # generated — committed — source of truth at runtime
+└── examples/
+    ├── api/                 # generic HTTP services
+    │   └── connectivity/
+    │       ├── README.md                 # front-matter + prose
+    │       └── connectivity-v1.sh.j2
+    ├── llm/                 # LLM gateway
+    │   └── request-template/
+    │       ├── README.md
+    │       └── request-template-v1.json
+    ├── s3/                  # S3-compatible storage gateway
+    │   ├── code-example/ ...
+    │   ├── connectivity/ ...
+    │   └── description/ ...
+    └── smtp/                # SMTP relay
+        └── connectivity/ ...
+
+tools/
+└── build.py                 # regenerate _manifest.json + MANIFEST.md
+```
+
+Each gateway holds one or more **preset families** (e.g. `s3/connectivity/`).
+A family directory contains:
+
+- `README.md` with TOML front-matter delimited by `+++` lines. The
+  front-matter has every piece of metadata for the family
+  (`preset_name`, `category`, `mime_type`, `file`, `description`,
+  `is_active`, `is_public`, `meta`). Prose under the front-matter
+  documents the example and any per-version differences.
+- One file per version, named `<stem>-v<N>.<suffix>` where stem and
+  suffix come from the `file` field — so `file = "connectivity.sh.j2"`
+  matches `connectivity-v1.sh.j2`, `connectivity-v2.sh.j2`, ....
+
+Versions are **discovered automatically** by scanning the family
+directory; authors never list them explicitly. Adding a new version
+is purely "drop a new `-v<N>.<ext>` file and rebuild."
+
+[`MANIFEST.md`](MANIFEST.md) at the repo root is the human-readable
+roster of every preset, also generated by `tools/build.py`.
+
+## Preset naming
+
+| Form                              | Resolves to                                | Use when             |
+|-----------------------------------|--------------------------------------------|----------------------|
+| `s3_connectivity_v1`              | version 1 of the `s3/connectivity` family  | pinning to an exact version |
+| `s3_connectivity` (alias)         | latest version of that family              | tracking the latest  |
+
+Seller data that pins to a versioned name stays byte-identical across
+`pip upgrade`s. Data that uses the alias tracks the newest version
+automatically.
+
+## Versioning discipline
+
+- Example files are **append-only**. `connectivity-v1.py.j2` is
+  frozen forever; fixes ship as `connectivity-v2.py.j2` dropped into
+  the same directory.
+- The version-less alias always points at the highest-`v` file in the
+  family. Landing a new version shifts the alias automatically the
+  next time `python tools/build.py` runs.
+- `preset_name` is globally unique across the whole tree — declaring
+  the same `preset_name` in two READMEs is a build error.
+- Package version bumps are additive (new version or new family →
+  minor bump; never mutate existing `_vN` → no breaking release).
+  Bump major only to remove a `_vN` (should be vanishingly rare).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full walkthrough: how
+to add a new family, how to publish a new version, front-matter
+reference, filename conventions, and the pre-submission checklist.
+
+In one line: drop your file at
+`src/unitysvc_data/examples/<gateway>/<family>/<stem>-v<N>.<ext>[.j2]`,
+write the family's `README.md`, run `python tools/build.py`, open the PR.
+
+## Development
+
+```bash
+uv pip install -e '.[test]'
+pytest -q                      # runs tests + manifest-freshness check
+python tools/build.py          # regenerate manifest + roster
+python tools/build.py --check  # CI mode: non-zero exit if stale
+```
+
+CI ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) runs
+`tools/build.py --check`, `ruff`, `pytest` on Python 3.11 and 3.12,
+then builds a wheel and verifies it includes every example file and
+the manifest.

unitysvc_data-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+unitysvc_data/__init__.py,sha256=-Mg_L5BqNopq3EfIEdlgtr7g2EjZEUL1OkQJ9eP_-8w,3959
+unitysvc_data/_manifest.json,sha256=yD2BXbRwm-967Dd3YX52MFCvei5jmx9coPGidfWUgmU,3060
+unitysvc_data/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+unitysvc_data/cli.py,sha256=kToGFS4rh21UXmcnxc8fQUBBoAZGJYmbUsl03wwZ_ko,7638
+unitysvc_data/presets.py,sha256=7PCqNa0V5oErUb5Ms5Hx12m6iKKhnBOehTzAhs5UILY,9619
+unitysvc_data/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+unitysvc_data/examples/api/connectivity/README.md,sha256=EZf0VpBZn_wHr2nGZsIxVUr2o89V0dfQM4cakwUSxp8,1539
+unitysvc_data/examples/api/connectivity/connectivity-v1.sh.j2,sha256=vGUxlzDFeGJ8wbKZxNUVG1M0n29Wb9J0wYlUWd_WCcc,1543
+unitysvc_data/examples/llm/request-template/README.md,sha256=srOQmgMsDwkUhEqqvDbSoRIV6X3V578DHP1k6ErZ4_4,1487
+unitysvc_data/examples/llm/request-template/request-template-v1.json,sha256=pEF5s-GtkY-_eBjRPw_jNlPesqm2kTKWWMjK_-VBnmc,210
+unitysvc_data/examples/s3/code-example/README.md,sha256=FE2PY7qGCeVA58oXK2S9lveGgS5ITqvq8rEe4KC6c7k,1693
+unitysvc_data/examples/s3/code-example/code-example-v1.py.j2,sha256=n1Lin6fAh-xjMu_xGHuY49-XlfNjvL5UP2HkxSN_Qtg,1499
+unitysvc_data/examples/s3/connectivity/README.md,sha256=sivOsJdxf0aDJOEmh0IJSd7jnT6q4eG8-Ie_3fvUdak,2186
+unitysvc_data/examples/s3/connectivity/connectivity-v1.py.j2,sha256=gj9fjsfi93XKwfDDOJwtQwfuorROs9MvA4eNbuJxywE,2626
+unitysvc_data/examples/s3/description/README.md,sha256=GiHa76dov92xqmrV4sok8qXc9N48xPp-Ap3_aG0AtNM,1594
+unitysvc_data/examples/s3/description/description-v1.md,sha256=GbGvXwKC5O9CNb5B96lku8om8t74jd-flt31FXazxMQ,620
+unitysvc_data/examples/smtp/connectivity/README.md,sha256=cNTZBxYQnPH67lLwCiXhQM8nAqsivlH7c9Q4V7Xilpk,1627
+unitysvc_data/examples/smtp/connectivity/connectivity-v1.sh.j2,sha256=HwNH8fRq86eP_XmkXygAxCktD9gKTX-WhyDgwXczGNw,1203
+unitysvc_data-0.1.0.dist-info/licenses/LICENSE,sha256=nqI6E90zC14DP1BXSSVWY3KgvMtqcwe8gWfIvhgk9mU,1065
+unitysvc_data-0.1.0.dist-info/METADATA,sha256=UfhiF2VMhBDgpxSKvPL69yIv2bvPwGXYxm2qo9_Iq0U,7984
+unitysvc_data-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+unitysvc_data-0.1.0.dist-info/entry_points.txt,sha256=5d3hgMaHr8sqhCuz-Sbvv6_C88lxzrAhbcHjkwPyobA,53
+unitysvc_data-0.1.0.dist-info/top_level.txt,sha256=4HJ6YIx3VwbJSiWZLO5C07WObytQu27IArcZy9sHPB8,14
+unitysvc_data-0.1.0.dist-info/RECORD,,

unitysvc_data-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

unitysvc_data-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+usvc_data = unitysvc_data.cli:main

unitysvc_data-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UnitySVC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unitysvc_data-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+unitysvc_data