ontocast.onto.ontology_header¶
The version header: the one place it is written, and the one place it is read.
Every stored version of an ontology is a named graph <iri>#<key> whose
owl:Ontology subject <iri> carries, on the version itself:
| predicate | value |
|---|---|
owl:versionIRI |
the named graph (<iri>#<key>) |
owl:priorVersion |
the version IRI(s) it was derived from; none on a root |
owl:versionInfo |
a semantic version label |
vann:preferredNamespacePrefix / vann:preferredNamespaceUri |
the id and the namespace its terms live under |
dcterms:title and rdfs:label |
the title |
dcterms:description |
the description, when there is one |
dcterms:created / dcterms:modified |
when the lineage began / when this version was made |
prov:wasDerivedFrom |
the source document, for versions a run wrote |
A removed version keeps its header and gets <graph> a oc:RemovedVersion.
The key is a name, not a digest anyone recomputes: the library uses the content
hash, so identical content is never stored twice.
Attributes¶
__all__ = ['CatalogContractError', 'DivergedOntologyError', 'OntologyHeader', 'SeedOntologyLoadError', 'VersionDiff', 'adopt_ontology', 'catalog_heads', 'diff_versions', 'header_from_fields', 'heads_by_iri', 'mint_ontology', 'ontology_from_version_graph', 'read_header', 'stamp_version', 'tombstone_graph', 'without_version_header', 'write_header']
module-attribute
¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
AmbiguousOntologyRefError
¶
Bases: ValueError
A short reference (an id or a prefix) names several catalog ontologies.
Ids and prefixes may repeat across IRIs; only an IRI is unique.
Source code in ontocast/onto/ontology_header.py
CatalogContractError
¶
Bases: ValueError
A stored graph does not carry the version header this library writes.
Source code in ontocast/onto/ontology_header.py
DivergedOntologyError
¶
Bases: RuntimeError
An ontology has several heads; it cannot be extended until they are merged.
Source code in ontocast/onto/ontology_header.py
OntologyHeader
¶
Bases: OntologyPropertiesWithLineage
The header of one stored version, read without its graph.
Attributes:
| Name | Type | Description |
|---|---|---|
graph_uri |
str
|
The named graph it was read from; equals |
Source code in ontocast/onto/ontology.py
Attributes¶
graph_uri = Field(default='')
class-attribute
instance-attribute
¶
Methods:¶
from_ontology(ontology)
classmethod
¶
The header of a stamped ontology.
Raises:
| Type | Description |
|---|---|
ValueError
|
|
Source code in ontocast/onto/ontology.py
SeedOntologyLoadError
¶
Bases: ValueError
Seed ontology files that could not be loaded, by path.
A batch run raises it before any write or model call: extracting against a catalog that silently lacks a vocabulary the user supplied yields a graph that cannot be told apart from a good one.
Source code in ontocast/onto/ontology_header.py
VersionDiff
¶
Added and removed content triples between two versions.
Attributes:
| Name | Type | Description |
|---|---|---|
from_iri |
The |
|
to_iri |
The |
|
added |
Sorted N-Triples lines present only in |
|
removed |
Sorted N-Triples lines present only in |
Source code in ontocast/onto/ontology_header.py
Attributes¶
__slots__ = ('from_iri', 'to_iri', 'added', 'removed')
class-attribute
instance-attribute
¶
added = added
instance-attribute
¶
added_count
property
¶
from_iri = from_iri
instance-attribute
¶
removed = removed
instance-attribute
¶
removed_count
property
¶
to_iri = to_iri
instance-attribute
¶
Methods:¶
__init__(*, from_iri, to_iri, added, removed)
¶
Functions:¶
adopt_ontology(graph, *, ontology_id=None, now=None, current_domain=DEFAULT_DOMAIN)
¶
Adopt an author's ontology as a root version.
The graph must declare exactly one named owl:Ontology that says
anything about itself; a header that is only typed owl:Ontology is
dropped. Its IRI must have no fragment; an empty one (…/prov#) is
dropped, and the header is rewritten to that IRI. The id comes from
ontology_id, else the file's vann:preferredNamespacePrefix, else the
prefix the file binds to the ontology's namespace, else is derived from the
IRI. The id is a label: several ontologies may share one; the title from dcterms:title, else
rdfs:label, else the id; the version label from owl:versionInfo
when it parses, else 1.0.0; the namespace from
:func:~ontocast.onto.ontology_namespace.ontology_namespace.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
current_domain
|
str
|
Unused for identity (the file's IRI is kept); accepted so adopters share one signature with minting. |
DEFAULT_DOMAIN
|
Raises:
| Type | Description |
|---|---|
ValueError
|
the graph declares no, or several, ontologies, or its IRI or id is not acceptable. |
Source code in ontocast/onto/ontology_header.py
417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 | |
catalog_heads(versions)
¶
(one head per ontology, the diverged ontologies).
An ontology with several heads is diverged: it is listed, its versions can be read, and nothing extends it until a merge makes one head.
Source code in ontocast/onto/ontology_header.py
diff_versions(from_graph, to_graph, *, from_iri, to_iri)
¶
Content diff of two version graphs, header triples excluded.
Source code in ontocast/onto/ontology_header.py
header_from_fields(graph_uri, fields)
¶
Build the header of graph_uri from its predicate values.
fields maps a short name (onto, versionIri, version,
prior, prefix, namespace, title, description,
created, modified, removed) to the lexical values found, so a SPARQL row and a parsed graph
feed the same check.
Raises:
| Type | Description |
|---|---|
CatalogContractError
|
a required field is missing, or the version IRI does not name the graph it was read from. |
Source code in ontocast/onto/ontology_header.py
heads_by_iri(versions)
¶
The heads of every ontology among versions.
A head is a live version that no live version descends from. Descent walks
through tombstoned versions, so removing a head makes its nearest live
ancestors the heads; an ontology whose versions are all tombstoned has no
heads. Sorted by modified_at, newest first.
Source code in ontocast/onto/ontology_header.py
mint_identity(current_domain, ontology_id, title, description='')
¶
The identity of a new ontology ontology_id under current_domain.
Source code in ontocast/onto/ontology_header.py
mint_ontology(identity, graph)
¶
A root artifact for the terms in graph under identity.
Any owl:Ontology subject the graph carries is dropped: the header is
written when the artifact is stamped. An extension ontology imports the
ontology it extends.
Source code in ontocast/onto/ontology_header.py
ontology_from_version_graph(graph_uri, graph)
¶
The ontology stored as the version graph graph_uri.
Its bases is its own header, so an artifact derived from it is stamped
as its child.
Raises:
| Type | Description |
|---|---|
CatalogContractError
|
the graph is not a version of an ontology. |
Source code in ontocast/onto/ontology_header.py
read_header(graph, graph_uri)
¶
The version header of the stored graph graph named graph_uri.
Raises:
| Type | Description |
|---|---|
CatalogContractError
|
the graph has no single |
Source code in ontocast/onto/ontology_header.py
stamp_version(artifact, *, updates=(), now=None, source_doc=None, version_label=None, increment=None)
¶
The stored version artifact becomes, or None if it changes nothing.
A root (no bases) is version 1.0.0 unless the artifact carries a label
already; an update of one base is that base's label bumped by updates;
a merge of several bases takes the highest label bumped once. The version
IRI is <iri>#<content hash>, so stamping the same content twice yields
the same version.
version_label wins when it parses and is strictly higher than every
base's label (an upload that declares a newer owl:versionInfo).
increment overrides the bump derived from updates.
Returns:
| Type | Description |
|---|---|
Ontology | None
|
A deep copy with the lineage fields set and the header written, or |
Ontology | None
|
None when the artifact's content equals its single base's. |
Source code in ontocast/onto/ontology_header.py
339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 | |
tombstone_graph(graph, graph_uri)
¶
Header-only copy of graph, marked oc:RemovedVersion.
Content triples are dropped; the version header stays so lineage through
this version never dangles. graph_uri is the named-graph IRI that
carries the marker.
Source code in ontocast/onto/ontology_header.py
without_version_header(graph)
¶
graph without the version header of any owl:Ontology subject.
Returns the same object when there is nothing to drop; otherwise a copy
that keeps author extras (owl:imports, a licence) and prefix bindings.
Source code in ontocast/onto/ontology_header.py
write_header(graph, version, *, source_doc)
¶
Write version's header onto its subject in graph, in place.
Every contract predicate on the subject except the prefix declarations is
replaced; author extras (owl:imports, a licence, ...) are kept.