oscal-bindings 0.1.0__tar.gz

oscal_bindings-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Build artifacts
+/build/
+/dist/
+*.egg-info/
+
+# Hatch / venv
+/.hatch/
+.venv/
+
+# Coverage
+.coverage
+.coverage.*
+/htmlcov/
+
+# Python
+__pycache__/
+*.py[cod]
+.mypy_cache
+.ruff_cache
+.pytest_cache
+
+# Property-based testing: remote corpus cache and Hypothesis example database
+/tests/.corpus_cache/
+.hypothesis/
+
+# Kiro: per-machine editor settings and spec execution history. Specs
+# (requirements/design/tasks) and steering are committed.
+/.kiro/settings/
+/.kiro/specs/**/tasks.meta.json
+
+.DS_Store
+tmp

oscal_bindings-0.1.0/DEVELOPING.md

@@ -0,0 +1,191 @@
+# Developing oscal-bindings (Python)
+
+## Workspace Setup
+
+```bash
+mise install --locked python uv pypi:hatch   # toolchain from mise.toml / mise.lock
+hatch run release                            # generates models, runs tests, builds docs
+```
+
+Hatch comes only from mise (see "Locked Environments"). If you have Hatch from pip,
+pipx, or brew, uninstall it so there's a single Hatch on the machine.
+
+## Development Workflow
+
+```bash
+hatch run generate         # regenerate models from schema + post-process
+hatch test --all --cover   # run tests with coverage across Python 3.11/3.12
+hatch run lint             # ruff check . && ruff format --check . (read-only)
+hatch run ruff format .    # apply formatting
+hatch run docs             # generate pdoc API docs
+hatch run release          # full pipeline: generate + lint + typing + test + coverage + docs
+```
+
+`hatch run lint` is the only lint/format entry point. It uses the Ruff pinned in the
+default env and the `[tool.ruff]` config in `pyproject.toml`, and `release` runs it
+right after `generate`. `hatch fmt` and `hatch check code` are not used here: they run
+in Hatch's `hatch-static-analysis` environment, which has Hatch's own ruleset and a
+line length of 120. That environment is intentionally left unrepaired, so don't fix it.
+Repairing it would bring back a second lint path with a different config.
+
+## Locked Environments
+
+Every Hatch env installs from a hashed lockfile generated by `hatch-pip-compile`
+(resolved and installed with `uv`): `requirements.txt` for `default`,
+`requirements/requirements-hatch-test.py3.{11,12}.txt` for the test matrix, and
+`requirements/requirements-hatch-build.txt` for the build frontend. `hatch-test` is
+constrained by `default`, so shared packages resolve to the same versions. The build
+backend is pinned exactly in `[build-system]`, because build isolation fetches it
+outside any lockfile.
+
+The locks matter for more than test stability. `datamodel-code-generator` formats its
+output with black and isort, which are its transitive dependencies. Without the lock,
+a new black release could change `v1/models.py` with no change in this repo.
+
+- Hatch re-locks an env automatically when its declared dependencies in
+  `pyproject.toml` change. Commit the updated lockfile with that change.
+- To upgrade on purpose: `PIP_COMPILE_UPGRADE=1 hatch env run --env default -- python --version`,
+  then the same with `--env hatch-test`. Afterwards, run `hatch run generate` and
+  review any `models.py` diff as formatter drift.
+- Hatch itself comes from mise, pinned in `mise.toml` together with the
+  `hatch-pip-compile` plugin and locked with its full dependency graph in `mise.lock`
+  and `.mise/locks/`. CI installs from the same files. Don't install Hatch any other
+  way (pip, pipx, brew). To bump it, edit the version in `mise.toml` and run
+  `mise lock` and then `mise install --locked python uv pypi:hatch`. The `hatch-test`
+  lockfiles depend on the Hatch version, because Hatch supplies that env's default
+  pytest/coverage ranges, so also run `hatch test --all` and commit the re-locked
+  `requirements-hatch-test.*.txt` files.
+- Do not add `mypy --install-types`: it installs stubs at run time, outside the lock.
+  Declare any stub packages mypy needs in the default env's `dependencies`.
+
+## Code Generation Pipeline
+
+1. `datamodel-codegen` converts the OSCAL JSON Schema to Pydantic v2 models (`src/oscal_bindings/v1/models.py`)
+   - Key flags: `--collapse-root-models`, `--use-annotated`, `--field-constraints`, `--reuse-model`
+2. `scripts/postprocess_models.py` renames classes from schema namespace paths to clean short names and renames the root model to `OscalDocument`
+
+Both steps take the schema and models paths explicitly — the `generate` script in
+`pyproject.toml` passes `--input`/`--output` to the generator and `--schema`/`--models`
+to the post-processor. Omitting either post-processor argument falls back to that
+argument's own default (`schemas/<ACTIVE_SCHEMA_RELEASE>/oscal_complete_schema.json`
+and `src/oscal_bindings/v1/models.py`); a missing path is a non-zero exit, not a
+silent no-op.
+
+The wrapper rename map is **schema-derived, not positional**. The post-processor scans
+the generated source for wrapper classes, reads each one's single body field (ignoring
+the `$schema` directive field), and publishes `<RootKey in PascalCase>Document` — so
+`catalog` → `CatalogDocument` regardless of the `Model1..8` ordinal the generator
+happened to assign. Two guards back it: an ambiguous wrapper (more than one body
+field) fails fast on the first offender, and a derived wrapper count that disagrees
+with the number of document types in the schema's top-level `oneOf` exits non-zero
+with both counts. A third guard catches duplicate `class <Name>(` definitions after
+all renames, accumulating every collision not covered by `COLLISION_OVERRIDES` into a
+single report rather than writing a file with colliding definitions.
+
+## Refreshing to a new OSCAL release
+
+Schemas are vendored per release under `schemas/<release>/`, filenames unchanged. The
+active bundle is selected **by explicit path only** — nothing scans, globs, or orders
+the `schemas/` directory, so adding a bundle changes nothing until the paths change.
+
+1. Add the new release's schema set under `schemas/<release>/` (keep the existing
+   bundle in place; the directories are a visible, reviewable history).
+2. Point the three references at the new release: `ACTIVE_SCHEMA_RELEASE` in
+   `scripts/postprocess_models.py`, and the `--input` / `--schema` paths in the
+   `generate` script in `pyproject.toml`.
+3. Update `__oscal_schema_version__` in `src/oscal_bindings/v1/__init__.py` to the new
+   release. It must match the release element of the schema `$id`
+   (`ns/oscal/1.0/<release>/…`).
+4. Run `hatch run generate` and review the `models.py` diff as schema-driven change
+   only. If the collision guard fires, add the new names to `COLLISION_OVERRIDES`
+   deliberately rather than suppressing the guard.
+5. Confirm all eight wrapper names survive and run `hatch test --all`.
+
+A minor or patch refresh regenerates `oscal_bindings.v1` in place. The package name
+changes only for a new OSCAL **major** version.
+
+## Key Design Decisions
+
+- **No RootModel wrappers for scalars** — fields like `uuid` are plain `str` with `Annotated` constraints, not wrapper objects.
+- **Clean class names** — derived from the part after `:` in the schema `$id` (e.g., `Parameter` not `OscalCompleteOscalControlCommonParameter`).
+- **Typed parser functions** — `parse_catalog()`, `parse_profile()`, etc. for type-safe document access.
+- **Collision handling** — 5 name collisions use module prefix (e.g., `SspControlImplementation` vs `ComponentDefinitionControlImplementation`).
+- **Hand-written extensions, not patched generated code** — uniform accessors (`OscalDoc`) and back-matter builders live under `extensions/` rather than being injected into `models.py`. This keeps the codegen pipeline a pristine `datamodel-codegen` run + a rename-only post-pass; convenience layers can evolve without touching generated output.
+- **Major-version namespace** — the bindings live in `oscal_bindings.v1`, named for the OSCAL major version with no minor or patch component. OSCAL is backward-compatible within a major version (newer schemas accept older documents; minor bumps have not added required fields), so the compatibility boundary is the major version and one binding set covers every 1.x producer. A minor-version namespace (`v1_2`, `v1_3`) was considered and rejected: it would encode a break at each routine refresh that does not exist. `__oscal_schema_version__` records the exact release the models were generated from. This mirrors NIST's own schema `$id` (`ns/oscal/1.0/1.2.2/...`), which scopes the namespace to the major line and hangs the release off it. OSCAL 2.0 is the trigger for a second version package; nothing is factored out between version packages before then, because the seam is unknowable until 2.0's differences are in hand.
+- **Strict models tie coverage to the vendored release** — every model carries `extra='forbid'`, so bindings generated from 1.2.3 reject a later 1.x document that uses a new field. "Supports OSCAL 1.x" therefore means "supports the vendored release and earlier"; `__oscal_schema_version__` makes that gap visible. `extra='ignore'` was rejected because `serialize_oscal` would silently drop unknown fields. An opt-in lenient mode is deferred, not rejected.
+- **Top level re-exports the version package** — `oscal_bindings/__init__.py` and the alias modules `oscal_bindings/models.py`, `oscal_bindings/parser.py`, `oscal_bindings/extensions/__init__.py` are pure re-exports from their `v1` counterparts. Names reached through either path are the same objects, so `oscal_bindings.X` and `oscal_bindings.v1.X` are interchangeable.
+
+## File Structure
+
+```
+src/oscal_bindings/
+  __init__.py              # Re-exports oscal_bindings.v1
+  models.py                # Alias module → v1.models
+  parser.py                # Alias module → v1.parser
+  extensions/__init__.py   # Alias module → v1.extensions
+  v1/                      # OSCAL 1.x version package (the implementation)
+    __init__.py            # Public API re-exports + __oscal_schema_version__
+    models.py              # Generated + post-processed Pydantic models
+    parser.py              # parse/serialize/validate + per-type typed parsers
+    extensions/            # Hand-written helpers layered on the generated models
+      __init__.py
+      document.py          # OscalDoc facade (uniform accessors)
+      builders.py          # make_hash / make_rlink / make_resource
+      validate_element.py  # Element-level schema validation
+schemas/
+  1.2.2/                   # Vendored schema bundles, one directory per OSCAL release
+  1.2.3/                   # Active bundle (selected by explicit path)
+scripts/
+  postprocess_models.py    # Class renaming, rename derivation, and guards
+tests/
+  test_parser.py           # Parser / serializer / validator tests
+  test_document.py         # OscalDoc facade tests
+  test_builders.py         # back-matter builder tests
+  test_validate_element.py # validate_element tests
+  test_oscal_bindings.py   # Import smoke + top-level/v1 path parity tests
+  test_postprocess.py      # Post-processor derivation and guard tests
+  test_prop_postprocess.py # Property tests for derivation and guards
+```
+
+## Adding an extension
+
+Hand-written helpers go under `src/oscal_bindings/v1/extensions/`:
+
+1. Add your module (e.g., `v1/extensions/foo.py`).
+2. Re-export public symbols from `v1/extensions/__init__.py`.
+3. Re-export from `src/oscal_bindings/v1/__init__.py` so callers can `from oscal_bindings.v1 import ...`.
+4. Add tests under `tests/`.
+
+Nothing else is needed for the top-level path: `oscal_bindings` takes its `__all__` from
+`oscal_bindings.v1.__all__`, so a name added to the version package surfaces at
+`from oscal_bindings import ...` automatically and the two surfaces cannot drift.
+Neither the version package nor the top-level package defines symbols of its own — that keeps the
+public API auditable in one file.
+
+## Testing
+
+```bash
+hatch test                 # quick test on default Python
+hatch test --all           # test across all matrix versions
+hatch test --all --cover   # with coverage (terminal report + htmlcov/)
+```
+
+With `--cover`, the combined coverage report prints to the terminal and is also
+written as HTML to `htmlcov/` (git-ignored). CI uploads it as the `coverage-html`
+artifact.
+
+## Releasing
+
+PyPI receives the exact wheel and sdist that CI built and tested; nothing rebuilds
+after CI.
+
+1. Bump `version` in `pyproject.toml` and merge it to `main`.
+2. Tag that commit `v<version>` (e.g. `v0.2.0`) and push the tag.
+3. CI (`build.yml`) fails fast if the tag isn't `v$(hatch version)`, runs the full
+   release chain, builds, and creates a **draft** GitHub release with the wheel and
+   sdist attached.
+4. Review the draft and publish it. That triggers `release.yml`, which downloads the
+   attached files, checks their filenames match the tag, and uploads them to PyPI
+   via trusted publishing.
+
+To retry a failed PyPI upload, run the `publish` workflow manually with the tag.

oscal_bindings-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

oscal_bindings-0.1.0/NOTICE

@@ -0,0 +1,15 @@
+oscal-bindings (Python)
+Copyright 2026 Always August, LLC
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This product includes the OSCAL JSON Schemas (schemas/<release>/) developed by
+the National Institute of Standards and Technology (NIST),
+https://github.com/usnistgov/OSCAL. The schemas are vendored unmodified.
+src/oscal_bindings/v1/models.py is generated from them by
+datamodel-code-generator and scripts/postprocess_models.py.
+
+As a work of the United States government, the NIST OSCAL materials are in the
+public domain within the United States and are made available worldwide under
+the CC0 1.0 Universal public domain dedication. NIST is acknowledged as the
+source of these materials; see https://www.nist.gov/open/license.