Skip to content

API.md

Latest commit

 

History

History
77 lines (55 loc) · 3.46 KB

API.md

File metadata and controls

77 lines (55 loc) · 3.46 KB
Raw

API reference

from ontology_config_generator import (
    ConfigSpec, generate_configs, extract_named, DEFAULT_NAMESPACE,
)

rdflib is imported lazily: import ontology_config_generator works without it, but generate_configs and extract_named require it at call time (install via the dev or rdf extra).

DEFAULT_NAMESPACE

"http://example.org/ontology/core/" — the neutral default IRI prefix the bound class local-names resolve against. Override per call with namespace=.

ConfigSpec

Dataclass — one row of the spec table (one output config).

Field Type Meaning
filename str Output file name, e.g. "regions.json".
extract dict[str, str | list[str]] Maps an output JSON key → a bound class local-name (or a list of them, whose extractions are concatenated). Empty ⇒ a static-only config.
binds_to str | None Optional descriptive label recorded in _generated.binds_to. Defaults to a +-join of the extracted class names (or "(static)").
static dict Optional baseline shape merged under the extraction (fixed scaffolding for configs the TTL has nothing to extract for).
Method Returns
ConfigSpec.from_obj(obj) (classmethod) Coerce a ConfigSpec or a plain dict into a ConfigSpec (a ConfigSpec is returned as-is).

generate_configs(spec_table, extension_path, output_dir, *, namespace=DEFAULT_NAMESPACE, starter_dir=None) -> dict[str, str]

Generate one JSON config per spec from an extension TTL.

  • spec_table — a list of ConfigSpec or plain dicts (coerced via from_obj).
  • extension_path — path to the extension .ttl (or None). Degrade-open: a missing or unparseable file logs a warning and yields starter/static-shaped configs (empty extractions) — it never raises.
  • output_dir — created if needed; one <filename> is written per spec.
  • namespace — the IRI the bound class local-names resolve against.
  • starter_dir — optional directory of read-only starter JSON templates loaded per filename as the shape base.

For each spec: load the starter (if any) + static as the base, run extract_named for every key → class pair, deep-merge the extracted lists into the base (a non-empty extracted list overrides the base list; an empty one preserves it), stamp _generated, and write the file.

Each written config gains a _generated block:

{"from": "<extension path or null>", "namespace": "<ns>",
 "binds_to": "<label>", "extracted_count": <int>}

Returns {filename: "ok (<n> extracted)"}.

extract_named(graph, class_local, *, namespace=DEFAULT_NAMESPACE) -> list[dict]

Generic OWL extraction over a parsed rdflib.Graph. Returns every named subclass (rdfs:subClassOf) and every named individual (rdf:type) of <namespace><class_local>, as:

[{"id": <local name>, "label": <rdfs:label or id>, "description": <rdfs:comment or "">}]

Blank-node subjects are skipped, and each subject appears at most once even if it is both a subclass and an instance. An unknown class (or a namespace that doesn't match the graph) returns [].

CLI

python -m ontology_config_generator \
  --extension EXT.ttl --spec-table SPECS.json --output-dir OUT/ \
  [--namespace IRI] [--starter-dir DIR]

--spec-table is a JSON file that is either a top-level list of spec objects, or an object with a "specs" list. Logs one line per generated config.