Metadata-Version: 2.4
Name: simready-package
Version: 2026.6.2
Summary: SimReady Asset Packaging Library
Author: NVIDIA Corporation
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.nvidia.com
Keywords: nvidia,simready,package
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: simready-validate>=2026.6.4
Provides-Extra: publish
Requires-Dist: ovpackage[local]>=0.1.0; extra == "publish"
Dynamic: license-file

# simready.package

Standalone Python library for packaging SimReady USD assets with pre- and
post-validation.  Orchestrates the **pre-validate → build → post-validate**
pipeline in a single `package()` call and writes a
`com.nvidia.simready.packaging.json` package definition.

---

## Installation

```bash
pip install simready-package

# Publishing via WRAPP also requires:
pip install "simready-package[publish]"
```

---

## Quick start

```python
import asyncio
import simready.package as sp

packager = sp.Packager(config_path="/workspace/project_config.toml")

result = asyncio.run(packager.package(
    sp.PackageSpec(
        name="crate_01",
        version="1.0.0",
        license_id="LicenseRef-NvidiaProprietary",
        source="/workspace/props/crate_01",
        root_usds=["crate_01.usd"],
    )
))

print(f"Package ready: {result.created.pkg_def_url}")
```

---

## Key concepts

### Two modes

| Mode | `repo` | Validation | Output |
|------|--------|-----------|--------|
| Local | `None` | Optional (`skip_*` flags) | `com.nvidia.simready.packaging.json` written into `source/` |
| Publish | set | Mandatory | Full WRAPP package published to repository (BOM, hashes, conformance) |

### Pre- and post-validation

`package()` runs pre-validation against the `Package-Candidate` profile before
building, and post-validation against the `Package` profile after building.
Both profiles are defined in SimReady foundations — no profile override is needed
or expected for standard packaging.

`package()` raises `ValidationFailed` when any feature fails (unless the phase
is skipped via `skip_pre_validation` / `skip_post_validation`).

### Profile and rule registration

Outside a Kit environment, pass rules and profiles to the `Packager` constructor:

```python
# From a project_config.toml (reads [validate] section)
packager = sp.Packager(config_path="/workspace/project_config.toml")

# Or from explicit paths
packager = sp.Packager(
    rules_and_requirements_paths=["nv_core/sr_specs/docs/capabilities"],
    features_paths=["nv_core/sr_specs/docs/features"],
    profiles_paths=["nv_core/sr_specs/docs/profiles/profiles.toml"],
)
```

Inside Kit, `omni.simready.validators` registers profiles automatically and the
constructor can be called with no arguments.

---

## Python API

### `Packager`

```python
packager = sp.Packager(
    *,
    config_path=None,                    # path to project_config.toml
    rules_and_requirements_paths=None,   # override individual paths
    features_paths=None,
    profiles_paths=None,
)

# Full pipeline
result = await packager.package(spec)            # -> PackageResult

# Pre-validation only
result = await packager.pre_validate(source, *, root_usds=None)   # -> PreValidationResult

# Post-validation only
result = await packager.post_validate(package_def, *)             # -> PostValidationResult
```

### `PackageSpec`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | `str` | required | Package name |
| `version` | `str` | required | Version string |
| `license_id` | `str` | required | SPDX license ID |
| `source` | `str` | required | Path to source asset folder |
| `repo` | `str \| None` | `None` | WRAPP repository URL. `None` = local, set = publish |
| `root_usds` | `list[str] \| None` | `None` | Root USD paths relative to `source`. Specify if the package contains nested USD files. |
| `profiles` | `list[str] \| None` | `None` | Pre-validation profile IDs. `None` → `["Package-Candidate"]` |
| `skip_pre_validation` | `bool` | `False` | Skip pre-validation (local only) |
| `skip_post_validation` | `bool` | `False` | Skip post-validation (local only) |

### `PackageResult`

| Field | Type | Description |
|-------|------|-------------|
| `spec` | `PackageSpec` | The spec used to produce this result |
| `created` | `CreatedPackage` | Produced artifact URLs |
| `pre_validation` | `PreValidationResult \| None` | Pre-validation outcome (`None` when skipped) |
| `post_validation` | `PostValidationResult \| None` | Post-validation outcome (`None` when skipped) |

### `CreatedPackage`

| Field | Type | Description |
|-------|------|-------------|
| `pkg_def_url` | `str` | Path/URL to `com.nvidia.simready.packaging.json` |
| `bom_url` | `str \| None` | BOM sidecar URL (WRAPP publish only) |
| `marker_url` | `str \| None` | `.wrapp` catalog marker URL (WRAPP publish only) |

---

## CLI

```bash
# Local packaging
simready-package \
  --name crate_01 --version 1.0.0 \
  --license LicenseRef-NvidiaProprietary \
  --project-config /workspace/project_config.toml \
  --root-usd crate_01.usd \
  /workspace/props/crate_01

# Publish to WRAPP (validation mandatory)
simready-package \
  --name crate_01 --version 1.0.0 \
  --license LicenseRef-NvidiaProprietary \
  --repo omniverse://nucleus.company.com/packages \
  --project-config /workspace/project_config.toml \
  --root-usd crate_01.usd \
  /workspace/props/crate_01

# Pre-validate only (no package build)
simready-package \
  --project-config /workspace/project_config.toml \
  --pre-validate-only \
  /workspace/props/crate_01

# Local packaging, skip validation
simready-package \
  --name crate_01 --version 1.0.0 \
  --license LicenseRef-NvidiaProprietary \
  --skip-pre-validation --skip-post-validation \
  /workspace/props/crate_01
```

Exit code: `0` = success, `1` = validation failed or error.

---

## License

Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: LicenseRef-NvidiaProprietary
