ontocast.onto.ontology¶
A catalog ontology: its graph, its identity and its place in a version DAG.
Identity (ontology_id, iri, title, description) is set by code
when an ontology is minted, adopted or read from a store; nothing here guesses
it from the graph. A version of an ontology is one immutable named graph
<iri>#<key> whose header carries its lineage; the header is written and
read by :mod:ontocast.onto.ontology_header, and only there.
Attributes¶
CONTRACT_PREDICATES = frozenset({OWL.versionIRI, OWL.versionInfo, OWL.priorVersion, VANN.preferredNamespacePrefix, VANN.preferredNamespaceUri, DCTERMS.title, RDFS.label, DCTERMS.description, RDFS.comment, DCTERMS.created, DCTERMS.modified, DCTERMS.identifier, PROV.wasDerivedFrom, SH.declare})
module-attribute
¶
REMOVED_VERSION_TYPE = ONTOCAST.RemovedVersion
module-attribute
¶
SemanticVersion = Annotated[str, Field(pattern='^\\d+\\.\\d+\\.\\d+$', description='Semantic version in MAJOR.MINOR.PATCH format (e.g., 1.2.3)')]
module-attribute
¶
VANN = Namespace('http://purl.org/vocab/vann/')
module-attribute
¶
VersionIncrement = Literal['major', 'minor', 'patch']
module-attribute
¶
__all__ = ['CONTRACT_PREDICATES', 'Ontology', 'OntologyHeader', 'OntologyProperties', 'OntologyPropertiesWithLineage', 'REMOVED_VERSION_TYPE', 'SemanticVersion', 'VANN', 'VersionIncrement', 'bump_version', 'content_hash', 'increment_type_for', 'normalize_semantic_version']
module-attribute
¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
Ontology
¶
Bases: OntologyPropertiesWithLineage
An ontology's graph with its identity and lineage.
Attributes:
| Name | Type | Description |
|---|---|---|
graph |
LLMGraphWire
|
The RDF graph. Between a read from the store and the next stamp it may carry the header of the version it was derived from; the header is rewritten when the artifact is stamped. |
bases |
list[OntologyHeader]
|
Stored versions this artifact derives from: none for a root, one for an update, two for a merge. Carried unchanged through in-run derivations so the stamped version's lineage points at stored versions only. |
namespace |
str
|
Unless set, read from |
Source code in ontocast/onto/ontology.py
246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 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 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 | |
Attributes¶
base
property
¶
The single stored version this artifact updates, if exactly one.
bases = Field(default_factory=list)
class-attribute
instance-attribute
¶
graph = Field(default_factory=RDFGraph)
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)
class-attribute
instance-attribute
¶
prefix
property
¶
The prefix the graph binds to this ontology's namespace, if any.
Methods:¶
__iadd__(other)
¶
Merge other's graph in; an Ontology also hands over its identity.
Source code in ontocast/onto/ontology.py
build_lineage_graph(versions)
staticmethod
¶
The version DAG of versions: an edge from each version to each prior.
Nodes are version IRIs; a prior not in versions is still a node.
Source code in ontocast/onto/ontology.py
content_hash()
¶
Compute, set and return the content digest of graph.
The digest covers every triple except the version header on the ontology subject and its prefix declarations, so two versions with the same terms hash alike whatever their labels or dates.
Source code in ontocast/onto/ontology.py
derive_updated_version(updated_graph)
¶
A new unstamped artifact over updated_graph with the same bases.
Source code in ontocast/onto/ontology.py
describe()
¶
A short human-readable description; a long description is cut.
Source code in ontocast/onto/ontology.py
description_preview()
¶
The description on one line; a long one is cut.
Source code in ontocast/onto/ontology.py
from_file(file_path, format='turtle', *, ontology_id=None, now=None)
classmethod
¶
Adopt the ontology in a file as a root version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
Path
|
Path to the ontology file. |
required |
format
|
str
|
rdflib parser name. |
'turtle'
|
ontology_id
|
str | None
|
The id to register it under; by default the file's
|
None
|
now
|
datetime | None
|
The adoption time; defaults to the current UTC time. |
None
|
Source code in ontocast/onto/ontology.py
is_null()
¶
strip_ontology_header_triples(graph)
staticmethod
¶
Remove every owl:Ontology subject and its triples, in place.
Blank structures that only the header points at (its sh:declare
prefix declarations) go with it, so no orphaned [] is left behind.
Source code in ontocast/onto/ontology.py
union_fresh(others)
¶
One root over the union of this and others' graphs.
The fresh units of a document each render whole graphs under the document's home ontology; their union is the ontology.
Source code in ontocast/onto/ontology.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
OntologyProperties
¶
Bases: BaseModel
What names and describes an ontology.
Attributes:
| Name | Type | Description |
|---|---|---|
ontology_id |
str | None
|
Short lowercase handle; also its preferred prefix. |
title |
str | None
|
Human-readable title. |
description |
str | None
|
A few sentences on domain, purpose and applicability. |
version |
SemanticVersion | None
|
Semantic version label of this version. |
iri |
str
|
Ontology IRI, with no fragment. |
namespace |
str
|
The namespace its terms live under; |
Source code in ontocast/onto/ontology.py
Attributes¶
description = Field(default=None)
class-attribute
instance-attribute
¶
iri = Field(default=ONTOLOGY_NULL_IRI)
class-attribute
instance-attribute
¶
namespace = Field(default='')
class-attribute
instance-attribute
¶
ontology_id = Field(default=None)
class-attribute
instance-attribute
¶
title = Field(default=None)
class-attribute
instance-attribute
¶
version = Field(default=None)
class-attribute
instance-attribute
¶
OntologyPropertiesWithLineage
¶
Bases: OntologyProperties
Properties of one version of an ontology.
Attributes:
| Name | Type | Description |
|---|---|---|
hash |
str | None
|
Content digest of the graph, header excluded. Change detection only: it decides whether a derived artifact is a new version. |
version_iri |
str | None
|
The named graph this version is stored as, |
prior_version_iris |
list[str]
|
Version IRIs this version was derived from: none for a root, one for an update, several for a merge. |
created_at |
datetime | None
|
When the root of this lineage was created. |
modified_at |
datetime | None
|
When this version was created. |
removed |
bool
|
True for a tombstone, a version whose content was removed. |
Source code in ontocast/onto/ontology.py
Attributes¶
created_at = Field(default=None)
class-attribute
instance-attribute
¶
hash = Field(default=None)
class-attribute
instance-attribute
¶
modified_at = Field(default=None)
class-attribute
instance-attribute
¶
prior_version_iris = Field(default_factory=list)
class-attribute
instance-attribute
¶
removed = Field(default=False)
class-attribute
instance-attribute
¶
version_iri = Field(default=None)
class-attribute
instance-attribute
¶
version_key
property
¶
The fragment of version_iri.
Functions:¶
bump_version(version, increment)
¶
version bumped by increment.
Source code in ontocast/onto/ontology.py
content_hash(graph, iri)
¶
The content digest of graph as a version of the ontology iri.
Excludes the header predicates on the ontology subject and the prefix declaration nodes they point at; everything else, author extras on the subject included, is content.
Source code in ontocast/onto/ontology.py
increment_type_for(updates)
¶
The version increment a set of applied updates earns, with its reason.
Deletes of several classes or properties are a major change, any delete a minor one, a handful of new terms a patch.
Source code in ontocast/onto/ontology.py
normalize_semantic_version(version)
¶
MAJOR.MINOR.PATCH for a version label an author wrote, or None.
"3.5" becomes "3.5.0" and "3" becomes "3.0.0"; any other
text is not a version.