Python API reference¶

pip install ontoenv    # Python 3.11+

The package exposes the Rust core through PyO3 bindings, with native rdflib interop. Pre-built wheels are published on PyPI; no Rust toolchain is required.

This page groups the API by purpose. Generated API has the generated signatures and docstrings.

Opening an environment¶

Call	Behavior
`OntoEnv.connect(path, , graph_store=None, sync="auto", read_only=False, *options)`	Create if missing, reopen if present. The normal entry point.
`OntoEnv.create(path, , graph_store=None, *options)`	Create a new environment; fails if one exists unless `overwrite=True`.
`OntoEnv.open(path, , graph_store=None, read_only=False, *options)`	Open an existing environment; fails if missing. Never synchronizes.
`OntoEnv.adopt(path, graph_store, , overwrite=False, *options)`	Index an already-populated custom store for the first time.
`OntoEnv.recover(path, , graph_store=None, *options)`	Rebuild the catalog after `CatalogRecoveryError`.
`OntoEnv(temporary=True, **options)`	In-memory environment; nothing is persisted.

sync accepts "auto" (default), "full", or "catalog" — see Staying in sync.

**options accepts any key from Configuration. On reopen, an omitted option preserves its saved value; an explicit value — including False, "default", and [] — overrides it. Writable connections persist overrides; read-only ones keep them session-local.

Direct constructor

OntoEnv(path=None, recreate=False, read_only=False, temporary=False,
        search_directories=None, includes=None, excludes=None,
        include_ontologies=None, exclude_ontologies=None,
        strict=None, offline=None, require_ontology_names=None,
        use_cached_ontologies=None, resolution_policy=None,
        remote_cache_ttl_secs=None, graph_store=None, root=".")

Supported and used internally, but the named methods above express intent more clearly. Note that recreate=True deletes and rebuilds the target .ontoenv directory — it is not a reconnect.

Deprecated since version 0.6: create_or_use_cached=True emits DeprecationWarning; use OntoEnv.connect(path). Removal planned for 0.7.

Deprecated since version 0.6: init_from_store=True; use OntoEnv.adopt(path, graph_store).

Closing¶

env.close() — release resources.
env.flush() — write pending changes to storage.
with OntoEnv.connect(...) as env: — calls close() on exit.

Adding ontologies¶

Method	Returns / notes
`add(location, overwrite=False, fetch_imports=True, force=False, rename=None)`	The ontology’s IRI. location is a path, URL, or `rdflib.Graph`.
`add_no_imports(location, overwrite=False, force=False, rename=None)`	As `add` but never follows `owl:imports`.
`rename_graph_iri(uri, new_iri)`	The new IRI. Rewrites the stored graph and rebuilds the import graph.

rename= rewrites every occurrence of the declared IRI in the stored graph, except owl:versionIRI values. See Rename and alias ontologies.

Refreshing¶

Method	Reconciles
`update(location=None, *, force=False)`	Ontology sources — files and URLs — following their imports. Without location, all configured sources.
`refresh_from_store(graphs=None, full=False)`	Graphs changed directly in a custom store. Returns a `SyncReport` with `added`, `changed`, `removed`.

graphs= is an exact set of backend graph IDs and is never expanded. full=True cannot be combined with it.

Deprecated since version 0.6: update(all=True); use update(force=True).

Reading graphs¶

Every read comes in a read-only view and a mutable copy. See Views and copies.

Method	Returns
`get_graph(uri)`	Read-only store-backed `rdflib.Graph`. Mutation raises `ValueError`.
`copy_graph(uri, graph=None)`	Mutable `rdflib.Graph`. Raises `UnresolvedImportError` for a known unresolved import, `ValueError` for an unknown IRI.
`get_closure(uri, recursion_depth=-1, remove_owl_imports=True, rewrite_sh_prefixes=True)`	`(ViewGraph, closure_names)` — flattened, de-duplicated view over the ontology and its transitive imports.
`copy_closure(uri, graph=None, rewrite_sh_prefixes=True, remove_owl_imports=True, recursion_depth=-1)`	`(Graph, closure_iris)` — same triple set, materialized and mutable.
`get_union(uris, include_closures=False, recursion_depth=-1)`	`(ViewGraph, graph_iris)` — raw merge of the listed graphs; no transform, no cross-graph de-duplication.
`copy_union(uris, root, graph=None, include_closures=False, rewrite_sh_prefixes=False, remove_owl_imports=False, recursion_depth=-1)`	`(Graph, graph_iris)` — raw by default; pass the transform flags to opt in, with root driving declaration and prefix cleanup.
`get_dataset()`	Read-only `rdflib.Dataset` view of the whole environment.
`copy_dataset(dataset=None)`	Mutable `rdflib.Dataset` copy.
`refresh_dataset(dataset)`	Re-snapshot the environment into an existing store-backed dataset.

Deprecated since version 0.6: snapshot_as_dataset(...) and to_rdflib_dataset(...); use get_dataset() / copy_dataset().

Streaming¶

iter_triples(uri) — (s, p, o) rdflib terms for one graph.
iter_closure_triples(uri, recursion_depth=-1) — the same across a closure. Not de-duplicated across named graphs.

Merging into a caller’s graph¶

import_graph(destination_graph, uri, recursion_depth=-1) — merge the closure of uri into destination_graph in place.
import_dependencies(graph, recursion_depth=-1, fetch_missing=False) — resolve graph’s own owl:imports and merge them into it. Returns the merged IRIs.
get_dependencies(graph, graph_name=None, recursion_depth=-1, fetch_missing=False) — (Graph, closure_iris); same resolution without modifying the caller’s graph. graph_name overrides the IRI used for sh:prefixes rewriting.

With fetch_missing=True, strict mode aborts on an unavailable import while non-strict mode records and skips it. A completed best-effort call leaves no recovery marker.

Inspecting¶

Method	Returns
`get_ontology_names()`	Every ontology IRI in the environment.
`get_ontology(uri)`	An `Ontology` metadata object.
`get_importers(uri)`	IRIs that directly import uri.
`list_closure(uri, recursion_depth=-1)`	Closure IRIs. uri may be a string IRI or an `rdflib.Graph` not yet in the environment.
`missing_imports(uri=None)`	Unresolvable `owl:imports` targets. `None` covers the whole environment; a string IRI walks that ontology’s closure; a `Graph` checks its direct imports.
`get_namespaces(ontology=None, include_closure=False)`	Prefix → namespace mapping.
`store_path()`	Filesystem path of the graph store, if any.
`dump(includes=None)`	Print the environment state to stdout.

Ontology exposes id, name, imports, location, last_updated, version_properties, and namespace_map.

Aliases¶

add_alias(alias_iri, canonical_iri) — an alias may only point at a canonical IRI, never another alias.
remove_alias(alias_iri)
resolve_alias(alias_iri) → canonical IRI or None
get_aliases_for(canonical_iri) → list of aliases
is_canonical_iri(iri) → bool

Aliases resolve transparently in get_graph, get_closure, uri in env, and env[uri].

Runtime configuration¶

Each setting has a getter and a setter. These change an open, writable environment and persist the change.

Getter	Setter
`is_offline()`	`set_offline(bool)`
`is_strict()`	`set_strict(bool)`
`requires_ontology_names()`	`set_require_ontology_names(bool)`
`remote_cache_ttl_secs()`	`set_remote_cache_ttl_secs(int)`
`uses_cached_ontologies()`	`set_use_cached_ontologies(bool)`
`resolution_policy()`	`set_resolution_policy("default" \| "latest" \| "version")`

Reconfiguration never triggers an implicit scan. Runtime modes apply immediately; changed discovery paths and filters apply on the next update().

Container protocols¶

len(env)              # number of ontologies
uri in env            # True if uri resolves — canonical name, alias, or source URL
env[uri]              # shorthand for env.get_graph(uri)
for name in env: ...  # iterate ontology IRIs

with OntoEnv.connect("./env") as env:
    ...

bool(env) is always True; use env is None to test for absence.

Exceptions¶

Exception	Raised when
`UnresolvedImportError` (`LookupError`)	A known unresolved `owl:imports` target is passed to `copy_graph`. Covers direct and indirect imports declared by catalogued ontologies, and targets attempted while fetching dependencies for a transient graph.
`CatalogRecoveryError` (`RuntimeError`)	Startup found an interrupted-mutation marker. See Recover an interrupted environment.
`ExternalStoreChangedError` (`RuntimeError`)	A custom store changed in a way OntoEnv will not reconcile on its own — it reports drift it cannot localize to specific graphs, its identity does not match the saved catalog, or it changed during a scan. Retry with `sync="full"` or `refresh_from_store(full=True)`.
`StoreCapabilityError` (`RuntimeError`)	An operation needs an optional store method the object does not implement.
`ValueError`	Mutating a read-only view, or looking up an IRI that was never declared or attempted.

An unknown IRI stays a plain ValueError precisely so that catching UnresolvedImportError for expected missing imports does not also swallow genuine lookup mistakes.