unitysvc-data

Standard examples and presets for UnitySVC — primary consumer is 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:

{
  "documents": {
    "Connectivity test":  { "$doc_preset": "s3_connectivity" },
    "Usage (Python)":     { "$doc_preset": { "name": "s3_code_example_v1",
                                             "description": "Lists objects in our bucket" } },
    "OpenAI-compat chat": { "$doc_preset": { "name": "llm_code_example_openai",
                                             "version_prefix": "/compatibility/v1" } }
  }
}

Two forms, one mechanism:

Bare string — {"$doc_preset": "preset_name"} — expands the preset with all defaults.
Flat dict — {"$doc_preset": {"name": "...", "<key>": ...}} — expands and overrides. Keys whose names match the preset's declared parameters substitute ${__name__} placeholders in the file body (see CONTRIBUTING.md). Other keys must be metadata fields (description, is_public, is_active, meta); anything else raises.

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:

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 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 upgrades. 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 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

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) 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.

Operating System
- OS Independent
Programming Language
- Python :: 3
- Python :: 3 :: Only
Typing
- Typed

Metadata

Operating System
- OS Independent
Programming Language
- Python :: 3
- Python :: 3 :: Only
Typing
- Typed

Release files for unitysvc-data 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unitysvc-data 0.2.3
File	Size	Uploaded	Provenance
unitysvc_data-0.2.3.tar.gz	242.2 kB	Sep 28, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for unitysvc-data 0.2.3
File	Interpreter	ABI	Platform	Reset
unitysvc_data-0.2.3-py3-none-any.whl 831.3 kB Sep 28, 2026 With provenance	Python 3	none	any	Details

Total release size: 1.1 MB

Release files / unitysvc_data-0.2.3.tar.gz

Download URL	unitysvc_data-0.2.3.tar.gz
Size	242.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`3e94c42776f20cc6ac7b9885bb2300fc6848d847770b5bb2eaea19adb3516220`
BLAKE2b-256 checksum How to use checksums	`10209918c7706e8b3c6ff0a70b71871fe8d1f614e5ee82e717cf4c931f54aa42`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/unitysvc/unitysvc-data
Publishing commit: github.com/unitysvc/unitysvc-data/tree/4def6de7ad7da94c670366dad8a0a02e63ce4fb8

Workflow

Publishing configuration: github.com/unitysvc/unitysvc-data/blob/4def6de7ad7da94c670366dad8a0a02e63ce4fb8/.github/workflows/publish.yml
Publishing logs: github.com/unitysvc/unitysvc-data/actions/runs/36494203992/attempts/1

Artifact

Subject: unitysvc_data-0.2.3.tar.gz
SHA-256 checksum: 3e94c42776f20cc6ac7b9885bb2300fc6848d847770b5bb2eaea19adb3516220 Verifying attestations

Release files / unitysvc_data-0.2.3-py3-none-any.whl

Download URL	unitysvc_data-0.2.3-py3-none-any.whl
Size	831.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c3ae300a876c818b932166a7c73805dae8fb1d69c9739b8af22dc61ad2716788`
BLAKE2b-256 checksum How to use checksums	`3138357a668c8351d2bd5af40d21eaf4d538a800615bf4083defc1693237f0b6`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/unitysvc/unitysvc-data
Publishing commit: github.com/unitysvc/unitysvc-data/tree/4def6de7ad7da94c670366dad8a0a02e63ce4fb8

Workflow

Publishing configuration: github.com/unitysvc/unitysvc-data/blob/4def6de7ad7da94c670366dad8a0a02e63ce4fb8/.github/workflows/publish.yml
Publishing logs: github.com/unitysvc/unitysvc-data/actions/runs/36494203992/attempts/1

Artifact

Subject: unitysvc_data-0.2.3-py3-none-any.whl
SHA-256 checksum: c3ae300a876c818b932166a7c73805dae8fb1d69c9739b8af22dc61ad2716788 Verifying attestations

Security for unitysvc-data 0.2.3

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for unitysvc_data-0.2.3.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/unitysvc/unitysvc-data
Publishing commit: github.com/unitysvc/unitysvc-data/tree/4def6de7ad7da94c670366dad8a0a02e63ce4fb8

Workflow

Publishing configuration: github.com/unitysvc/unitysvc-data/blob/4def6de7ad7da94c670366dad8a0a02e63ce4fb8/.github/workflows/publish.yml
Publishing logs: github.com/unitysvc/unitysvc-data/actions/runs/36494203992/attempts/1

Artifact

Subject: unitysvc_data-0.2.3.tar.gz
SHA-256 checksum: 3e94c42776f20cc6ac7b9885bb2300fc6848d847770b5bb2eaea19adb3516220 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.