Skip to content

feat!: report a read error for a file path that cannot be read - #76

Merged
dfkunstler merged 1 commit into
mainfrom
61-report-read-error
Nov 17, 2026
Merged

dfkunstler merged 1 commit into
mainfrom
61-report-read-error

Conversation

@dfkunstler

Copy link
Copy Markdown
Member

Closes #61

What

A file-path parse (parse_oscal_file, parse_oscal_yaml_file, OscalDoc.from_file) now meets ERR-012 of the spec store.

  1. New OscalReadError(OSError). It is raised for each read failure that is not a missing path: a directory, a permission failure, a loop of symbolic links, an I/O error. Its errno, strerror, and filename come from the failure, and its message names the path. It is not a subclass of OscalParseError or of FileNotFoundError.
  2. _read_oscal_file no longer calls Path.exists(). The read itself finds the category: ENOENT, ENOTDIR, or a ValueError (a path with a NUL byte) gives FileNotFoundError; each other OSError gives OscalReadError. exists() hides the errno, and its answer for a non-ENOENT failure changes with the Python version (3.12: ELOOP/EBADF; 3.14: every OSError). The single read also removes the race between the check and the read.
  3. The conformance runner maps OscalReadError to read-error. The corpus case parse-file/directory passes and leaves the expected failures. test_every_category_is_mapped stays a strict xfail, now for builder-error (Derive the resource identifier from a key and report the builder-error category (BMB-004, ERR-013) #62) only.

BREAKING

A file-path parse raises OscalReadError, not OscalParseError, for a read failure. except OSError catches both OscalReadError and FileNotFoundError.

Tests

  1. New tests in tests/test_parser.py: directory, file with mode 0o000, loop of symbolic links, file in a directory with mode 0o000 (these permission tests skip as root), ENOTDIR, and a NUL byte.
  2. New test in tests/test_yaml_io.py: a directory raises OscalReadError.
  3. hatch run release passes: 3398 passed, 2 skipped, 31 xfailed. models.py has no drift.

Benchmarks

Median of 7 runs, 10.4 MB catalog, Python 3.14.8, GC on / GC off (ms). The change touches only the file-read path, which these scripts do not exercise. The differences are within run-to-run noise.

Path Before After
parse_oscal(bytes) 63.7 / 47.4 64.6 / 47.4
serialize_oscal(indent=None) 134.6 / 128.4 136.4 / 130.1
serialize_oscal() 143.6 / 135.7 146.4 / 142.5
model_dump_json() 140.1 / 133.3 142.1 / 136.5
pydantic_core.to_json(doc) 141.5 / 133.5 145.5 / 138.4

Peak memory is identical (36.5 / 84.3 / 144.4 / 146.4 MB), so PERFORMANCE.md needs no update.

OpenSpec

The change report-read-error is archived, and its delta is synced into openspec/specs/error-tests/spec.md.

Add OscalReadError, a subclass of OSError. A file-path parse
(parse_oscal_file, parse_oscal_yaml_file, OscalDoc.from_file) raises it
for each read failure that is not a missing path (ERR-012): a directory,
a permission failure, a loop of symbolic links, an I/O error. The read
itself finds the category, with no Path.exists() call, so the category no
longer changes with the Python version and the check no longer races the
read. FileNotFoundError is raised only for ENOENT, ENOTDIR, or a path the
operating system cannot represent.

The conformance runner maps OscalReadError to read-error, and the corpus
case parse-file/directory passes.

BREAKING CHANGE: a file-path parse raises OscalReadError, not
OscalParseError, for a read failure. except OSError catches both
OscalReadError and FileNotFoundError.

Closes #61
@dfkunstler
dfkunstler merged commit 71615ee into main Nov 17, 2026
12 checks passed
@dfkunstler
dfkunstler deleted the 61-report-read-error branch November 17, 2026 12:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Report the read-error category for a file-path parse that cannot read the file (ERR-012)

1 participant