Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .agents/summary/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@ graph LR
| Symbol | Kind | Purpose |
|--------|------|---------|
| `parse_oscal(data)` | function | `str \| bytes` → `OscalDocument` via `model_validate_json` |
| `parse_oscal_file(path)` | function | Reads file as **bytes**, delegates to `parse_oscal` |
| `parse_oscal_file(path)` | function | Reads file as **bytes**, delegates to `parse_oscal`; `FileNotFoundError` for a missing path, `OscalReadError` for another read failure |
| `OscalReadError` | exception | Subclass of `OSError`; a file-path parse raises it for a read failure that is not a missing path |
| `serialize_oscal(model, *, indent=2)` | function | `model_dump_json(by_alias=True, exclude_none=True)` |
| `validate_oscal(data)` | function | Returns `bool`, swallows errors |
| `parse_catalog`, `parse_profile`, `parse_component_definition`, `parse_system_security_plan`, `parse_assessment_plan`, `parse_assessment_results`, `parse_plan_of_action_and_milestones`, `parse_mapping_collection` | functions | Typed parsers; each `hasattr`-checks `doc.root` for the expected body attr, else raises `OscalParseError` |
Expand Down
3 changes: 2 additions & 1 deletion .agents/summary/interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@ sequenceDiagram
|-----------|----------|
| Invalid JSON / invalid UTF-8 bytes | `OscalParseError` (from `parse_oscal`) |
| Schema validation failure | `OscalParseError` with `.errors` = Pydantic error dicts |
| File missing | `FileNotFoundError` (from `parse_oscal_file`, includes path) |
| File missing (`ENOENT`, `ENOTDIR`, or an unrepresentable path) | `FileNotFoundError` (from a file-path parse, includes path) |
| File that cannot be read for another reason (directory, permission, symlink loop, I/O error) | `OscalReadError` (a subclass of `OSError`, outside the parse errors; `filename` and message name the path) |
| Typed parser, wrong document type | `OscalDocumentTypeMismatchError("Document is not a …")` (subclass of `OscalParseError`) |
| `assessment_period()` on non-AP/AR | `OscalAccessError` |
| `OscalDoc(...)` with unrelated object | `TypeError` |
Expand Down
2 changes: 1 addition & 1 deletion .agents/summary/review_notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Cross-document facts were verified against the source files (`v1/parser.py`, `v1
| Top level is a pure re-export; `__all__` derived from `v1.__all__` | ✅ | codebase_info, architecture, components, interfaces, index agree; asserted by `tests/test_oscal_bindings.py` |
| Active schema release `1.2.3` / `__oscal_schema_version__` | ✅ | index, codebase_info, architecture, data_models, workflows, dependencies agree; tests assert it against the release of the pin and the artifact schema `$id` |
| Names come only from `names.json` (hoist + post-processor guards; no naming rule in the binding) | ✅ | architecture, workflows, interfaces, components, data_models, index agree |
| Exceptions `OscalParseError` (with `.errors`) / `OscalAccessError` | ✅ | Consistent; `validate_element` raises `OscalUnknownElementTypeError` for an unrecognized type, a separate category |
| Exceptions `OscalParseError` (with `.errors`) / `OscalAccessError` / `OscalReadError` (read failure, beside `FileNotFoundError`) | ✅ | Consistent; `validate_element` raises `OscalUnknownElementTypeError` for an unrecognized type, a separate category |
| `serialize_oscal` defaults (`indent=2`, `by_alias`, `exclude_none`) | ✅ | Matches source |
| Two `RootModel`s: `OscalDocument`, `MappingCollectionMappings` | ✅ | architecture, components, data_models, workflows agree |
| Single runtime dependency (Pydantic v2) | ✅ | dependencies.md matches `pyproject.toml` |
Expand Down
2 changes: 1 addition & 1 deletion .agents/summary/workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ flowchart TD
F -->|no| E
```

`parse_oscal_file` reads the file as **bytes** (`read_bytes()`) and delegates to `parse_oscal`, so file parsing skips a decode step. A missing file raises `FileNotFoundError` before parsing.
`parse_oscal_file` reads the file as **bytes** (`read_bytes()`) and delegates to `parse_oscal`, so file parsing skips a decode step. A missing file raises `FileNotFoundError` and any other read failure raises `OscalReadError`, both before parsing; the read itself finds the category, with no `exists()` call.

## 3. Uniform Access via `OscalDoc`

Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,7 @@ See `.agents/summary/workflows.md` for the flow diagram.
## Repo-Specific Patterns & Gotchas

- **Parsers accept `str | bytes`.** Passing `bytes` (from HTTP/S3/file) skips a UTF-8 decode; `parse_oscal_file` reads bytes deliberately. Invalid UTF-8 surfaces as `OscalParseError`, not `UnicodeDecodeError`.
- **A file-path parse finds the error category from the read itself.** `_read_oscal_file` (`v1/parser.py`) makes no `Path.exists()` call: `read_bytes` raises, and `ENOENT`, `ENOTDIR`, or a `ValueError` (a NUL byte) gives `FileNotFoundError`; each other `OSError` gives `OscalReadError(OSError)`, which is not a parse error and not a not-found error (ERR-012). `exists()` hides the `errno` and changes its answer with the Python version. `parse_oscal_file`, `parse_oscal_yaml_file`, and `OscalDoc.from_file` all share this path.
- **Typed parsers return the wrapper, not the body.** `parse_catalog()` returns `CatalogDocument` (access `.catalog.metadata...`). It `hasattr`-checks `doc.root` and raises `OscalDocumentTypeMismatchError("Document is not a Catalog")` (a subclass of `OscalParseError`) on mismatch.
- **`OscalDoc` collapses per-type dispatch.** Use it when you don't want to branch on document type — `doc.metadata`, `doc.uuid`, `doc.oscal_version`, `doc.body` work uniformly via the `_WRAPPER_TO_BODY_ATTR` map. `assessment_period()` is defined **only** for Assessment Plan / Assessment Results (raises `OscalAccessError` otherwise).
- **Valid OSCAL by default; construct by name, validate by alias.** `OscalBaseModel` (`v1/_base.py`) gives every object model alias keys (`media-type`, `document-ids`) and no `null` on all serialization paths (`model_dump*`, `to_json`, `TypeAdapter`); `exclude_none=False` is a no-op, `by_alias=False` emits names. Constructor kwargs accept field names or aliases (`BackMatterResourceRlink(media_type=...)`), so the builders construct directly. OSCAL input stays alias-only: dict input rejects name keys with `extra_forbidden` at every depth (`extra='forbid'`). **Don't add `validate_by_name`/`populate_by_name` to the base config**, and don't remove `__pydantic_base_init__` from its `__init__`: either makes `model_validate*` accept name-keyed OSCAL (DEVELOPING "Valid OSCAL by default"; tripwire tests guard both). JSON input rejects name keys too, which needs the pydantic ≥2.14.2 floor (2.13.x–2.14.1 silently dropped them, [#6](https://github.com/cairn-proofs/oscal-bindings-python/issues/6)).
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -302,7 +302,7 @@ Each OSCAL document type has a dedicated parser:
- `parse_plan_of_action_and_milestones(json)` → `PlanOfActionAndMilestonesDocument`
- `parse_mapping_collection(json)` → `MappingCollectionDocument`

A typed parser raises `OscalDocumentTypeMismatchError` for a document of another type. It is a subclass of `OscalParseError`, so `except OscalParseError` also catches it. `validate_element` raises `OscalUnknownElementTypeError` for an element type that the library does not recognize. That error is a category of its own, outside the parse errors. Test the category of an error with `isinstance`.
A typed parser raises `OscalDocumentTypeMismatchError` for a document of another type. It is a subclass of `OscalParseError`, so `except OscalParseError` also catches it. `validate_element` raises `OscalUnknownElementTypeError` for an element type that the library does not recognize. That error is a category of its own, outside the parse errors. A file-path parse raises `FileNotFoundError` when no file can exist at the path, and `OscalReadError` for each other read failure (a directory, a permission failure, a loop of symbolic links). `OscalReadError` is a subclass of `OSError`, not of `OscalParseError` or of `FileNotFoundError`, so `except OSError` catches both file categories and `except OscalParseError` catches neither. Test the category of an error with `isinstance`.

## Building

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-17
91 changes: 91 additions & 0 deletions openspec/changes/archive/2026-11-17-report-read-error/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Design

## Context

See [proposal.md - Why](proposal.md#why) for the motivation. These facts constrain the approach.

1. Three file-path parses read the file through `_read_oscal_file` in `parser.py`: `parse_oscal_file`,
`parse_oscal_yaml_file` (through `_yaml_loader.py`), and `OscalDoc.from_file` (through `parse_oscal_file`). Thus one
edit to `_read_oscal_file` gives the same behavior to all three.
2. `Path.read_bytes` raises a subclass of `OSError` for each read failure. The subclass follows the `errno`: `ENOENT`
gives `FileNotFoundError`, `ENOTDIR` gives `NotADirectoryError`, `EISDIR` gives `IsADirectoryError`, and `EACCES`
gives `PermissionError`. `ELOOP` gives a plain `OSError`.
3. The conformance runner (`category` in `tests/test_conformance.py`) maps a class to a category.
`test_every_category_is_mapped` is a strict expected failure until each category of the corpus has a class. The
builder-error category ([#62]) has no class yet.
4. A name in `v1.__all__` must be in the surface snapshot (`tests/support/version_package.py`) and in
`openspec/traceability.json`.

## Goals / Non-Goals

**Goals:**

1. The category of a read failure is the same on each supported Python version.

**Non-Goals:**

1. A change to the message of the not-found error.

## Decisions

### D1: `OscalReadError` is a subclass of `OSError`

The not-found category is `FileNotFoundError`, which is a subclass of `OSError`. A read error is also a failure of the
operating system to give the bytes of a file. With `OscalReadError(OSError)`, the two file categories have one parent
in the Python hierarchy:

```
OSError
+-- FileNotFoundError (not-found)
+-- OscalReadError (read error)
```

1. A caller catches each failure to read a file with `except OSError`, and catches no parse error with it.
2. `OscalReadError` has `errno`, `strerror`, and `filename` from `OSError`, with no new code.
3. The binding raises it as `OscalReadError(e.errno, e.strerror, str(path)) from e`. `OSError.__str__` then gives
`[Errno 21] Is a directory: 'documents/valid'`, which names the path (ERR-012).
4. Python maps an `errno` to a subclass only when the code calls `OSError` itself. A call to a subclass does not get
this mapping. Thus `OscalReadError(errno.EISDIR, ...)` stays an `OscalReadError`.

The class is in `parser.py`, below `OscalDocumentTypeMismatchError`. It goes through the re-export chain: `v1/__init__.py`
and the explicit import list and `__all__` of the alias module `src/oscal_bindings/parser.py`.

Alternative: `OscalReadError(Exception)`, beside `OscalAccessError`. A caller then needs two `except` clauses to catch
each failure to read a file, and the error has no `errno`. Rejected.

### D2: The read itself finds the category, with no `exists()` call

`_read_oscal_file` calls `read_bytes` with no check before it, and maps the exception:

1. `FileNotFoundError` or `NotADirectoryError` gives `FileNotFoundError` with the current message,
`OSCAL file not found: <path>`, raised `from` the original error.
2. Each other `OSError` gives `OscalReadError`, as [D1](#d1-oscalreaderror-is-a-subclass-of-oserror) shows.
3. A `ValueError` (a path that the operating system cannot represent, such as one with a NUL byte or an
unencodable surrogate) gives `FileNotFoundError` with the current message, raised `from` the original error. No
file can exist at such a path, and the failure has nothing to do with OSCAL. This keeps the current behavior.

The exception that the read raises is the only fact that decides. `Path.exists()` hides the `errno`, and its result for a failure
that is not `ENOENT` changes with the Python version. The check before the read also allowed a race: the path can change
between `exists()` and `read_bytes`. A single read removes the race.

Alternative: keep `exists()` and add a `try` around it. The result of `exists()` is still a bool, so the `errno` stays
hidden. Rejected.

### D3: Tests of read failures that the corpus cannot hold

The corpus holds only the directory case. The unit tests in `tests/test_parser.py` create each other case in `tmp_path`:

1. A file with mode `0o000` (ERR-012.02).
2. A loop of two symbolic links.
3. A file in a directory with mode `0o000`.

A process with root privileges reads each of these paths. Thus each of these tests is skipped when `os.geteuid() == 0`.
Each test sets the mode back in a `finally` block, so that pytest can delete `tmp_path`.

## Risks / Trade-offs

1. [Code that catches `OscalParseError` around a file-path parse stops catching a read failure.] → The commit is a
`feat!` with a `BREAKING CHANGE` footer, and the README says that `except OSError` catches both file categories.
2. [A test run as root skips the permission tests.] → The CI runner is not root, so CI runs them.

[#62]: https://github.com/cairn-proofs/oscal-bindings-python/issues/62
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Proposal

## Why

The store requirement ERR-012 (cairn-proofs/oscal-bindings-specs#41, PR cairn-proofs/oscal-bindings-specs#55) says that a
file-path parse that cannot read the file at a path reports the read-error category of ERR-001. A path that the platform
reports as missing is the exception. It is not-found (ERR-006). A read error names the path. It is not a parse error and
not a not-found error ([#61]).

The binding does not meet ERR-012:

1. The binding has no read-error category. `_read_oscal_file` in `src/oscal_bindings/v1/parser.py` raises
`OscalParseError` for each read failure. Thus a directory gives a parse error, and the corpus case
`parse-file/directory` is an expected failure.
2. `_read_oscal_file` calls `Path.exists()` before the read, and raises `FileNotFoundError` when `exists()` is false. On
Python 3.12, `exists()` is false for `ELOOP` and `EBADF`. Thus a loop of symbolic links gives not-found. On Python 3.14,
`exists()` is false for each `OSError`. Thus a path with a directory that the caller cannot search gives not-found. The
category of a read failure changes with the Python version.

The pin is at `v0.8.0+oscal.1.2.3` (#70), the release that has ERR-012. Thus the fix is now possible.

## What Changes

1. A new exception `OscalReadError`, a subclass of `OSError`. It is not a subclass of `OscalParseError` or of
`FileNotFoundError`. Each file-path parse raises it for a read failure that is not a missing path. Its `errno`,
`strerror`, and `filename` come from the failure, and its message names the path.
2. A file-path parse raises `FileNotFoundError` only when the read fails with `ENOENT` or `ENOTDIR`. The binding does not
call `Path.exists()` to find the category.
3. **BREAKING**: a file-path parse does not raise `OscalParseError` for a read failure. Code that catches
`OscalParseError` for a directory, a permission failure, or an I/O error does not catch the new error. Code that
catches `OSError` catches both the read error and not-found.
4. The conformance runner maps `OscalReadError` to the category `read-error`. The corpus case `parse-file/directory`
passes.

## Capabilities

### New Capabilities

None.

### Modified Capabilities

1. `error-tests`: the list of categories and classes gets the read-error category and its class `OscalReadError`.

## Impact

1. Code: `src/oscal_bindings/v1/parser.py` and the re-exports in `src/oscal_bindings/v1/__init__.py` and the alias
module `src/oscal_bindings/parser.py`. The YAML file parser and `OscalDoc.from_file` use `_read_oscal_file`, so they
get the same behavior with no edit to their code.
2. Tests: `tests/test_conformance.py`, `tests/support/expected_failures.py`, `tests/test_parser.py`, and
`tests/test_yaml_io.py`.
3. Docs: the `Raises` sections of `parse_oscal_file` and `parse_oscal_yaml_file`, `README.md`, `AGENTS.md`, and
`.agents/summary/interfaces.md`.
4. Public API: one new exception class, and the exception that a file-path parse raises for a read failure.

[#61]: https://github.com/cairn-proofs/oscal-bindings-python/issues/61
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Spec Delta

## MODIFIED Requirements

### Requirement: The class of an error is its category

For each category in this list, an error SHALL be in the category exactly when it is an instance of the class:

1. Parse error: `OscalParseError`.
2. Document-type mismatch: `OscalDocumentTypeMismatchError`, a subclass of `OscalParseError`.
3. Unknown element type: `OscalUnknownElementTypeError`, which is not a subclass of `OscalParseError`.
4. Access error: `OscalAccessError`.
5. Not-found: `FileNotFoundError`.
6. Read error: `OscalReadError`, a subclass of `OSError`, which is not a subclass of `OscalParseError` or of
`FileNotFoundError`.

A caller tests a category with `isinstance`.

#### Scenario: A document-type mismatch is also a parse error

- **WHEN** the caller parses a profile with the catalog parser
- **THEN** the error is an instance of `OscalDocumentTypeMismatchError` and an instance of `OscalParseError`

#### Scenario: A parse error of another kind is not a document-type mismatch

- **WHEN** the caller parses input that is not valid JSON
- **THEN** the error is an instance of `OscalParseError` and not an instance of `OscalDocumentTypeMismatchError`

#### Scenario: An unknown element type is not a parse error

- **WHEN** the caller validates an element with an element type that the binding does not recognize
- **THEN** the error is an instance of `OscalUnknownElementTypeError` and not an instance of `OscalParseError`

#### Scenario: A read error is not a parse error or a not-found error

- **WHEN** the caller parses a file at a path that is a directory
- **THEN** the error is an instance of `OscalReadError` and an instance of `OSError`
- **AND** the error is not an instance of `OscalParseError` and not an instance of `FileNotFoundError`

## ADDED Requirements

### Requirement: A file-path parse finds the category of a read failure from the read

A file-path parse SHALL find the category of a read failure from the error of the read itself:

1. When no file can exist at the path (`ENOENT`, `ENOTDIR`, or a `ValueError` for a path that the operating system
cannot represent), the error is not-found.
2. For each other read failure, the error is a read error. Its `filename` is the path, and its message names the path.

A file-path parse does not test whether the path exists before the read.

#### Scenario: A missing path is not-found

- **WHEN** the caller parses a file at a path that does not exist
- **THEN** the error is an instance of `FileNotFoundError`

#### Scenario: A path below a regular file is not-found

- **WHEN** the caller parses a file at a path whose parent is a regular file
- **THEN** the error is an instance of `FileNotFoundError` and not an instance of `OscalReadError`

#### Scenario: A path that the operating system cannot represent is not-found

- **WHEN** the caller parses a file at a path that contains a NUL byte
- **THEN** the error is an instance of `FileNotFoundError` and not an instance of `OscalReadError`

#### Scenario: A file without read permission is a read error

- **WHEN** the caller parses a file that the caller has no permission to read
- **THEN** the error is an instance of `OscalReadError`, and its message names the path

#### Scenario: A loop of symbolic links is a read error

- **WHEN** the caller parses a file at a path that is a loop of symbolic links
- **THEN** the error is an instance of `OscalReadError`, and its message names the path

#### Scenario: A directory that the caller cannot search is a read error

- **WHEN** the caller parses a file at a path through a directory that the caller has no permission to search
- **THEN** the error is an instance of `OscalReadError`, and its message names the path
Loading
Loading