Reading a file

from ub_needs_exchange import ExchangeError, load

try:
    version = load("needs.json").select_version(None)  # or a version's name
except ExchangeError as err:
    err.code       # what is wrong, e.g. "version_not_found"
    err.message    # for a person
else:
    records = version.records()
    for record in records:
        record.key        # the need's id
        record.fields     # its fields, schema defaults merged under them
    version.diagnostics   # findings about the version -- report them, or not
    [d for r in records for d in r.diagnostics]   # findings about each record

Every refusal is an ExchangeError whose code names the rule that was broken; every finding is a Diagnostic with a code, the path of what was found in the file, and a message.

Consumers decide the policy

This package decides nothing a consumer has reason to decide differently: which fields a project defines and which of a record’s keys it takes, the ids it accepts, the prefix it adds, how a record becomes a need, and whether a finding deserves a warning are each tool’s own.

The contract

design/exchange-contract.md is the normative specification, and tests/fixtures/needs_json_reading_conformance.toml is its executable half: a corpus of needs.json files and expected results that this package’s suite runs, and that ubCode is to vendor and run against its own readers.