pyowl2.ontology

A comprehensive interface for creating, loading, and manipulating OWL ontologies by wrapping the Owlready2 library to manage entities, axioms, and annotations.

Description

The software serves as a high-level abstraction over the Owlready2 library, enabling the creation, loading, and modification of Web Ontology Language (OWL) structures. It manages the lifecycle of an ontology by initializing a specific “World” context, which can either generate a new knowledge base from a base IRI or load an existing structure from a file path. To facilitate the manipulation of logical entities, the implementation delegates the translation of high-level objects—such as classes, properties, and individuals—into RDF triples using an internal mapping component. This mapping process includes specialized logic to decompose complex entities into their constituent declarations, domains, ranges, and nested axioms, ensuring that the underlying graph accurately reflects the intended semantic relationships. Beyond logical axioms, the system supports the attachment of metadata annotations to the ontology itself, specific elements, or individual relations, thereby enriching the knowledge base with descriptive details. Finally, the interface provides mechanisms for querying specific axiom types and serializing the complete graph to various file formats, ensuring that the data can be persisted and shared.

Attributes

logger

Classes

OWLOntology

This class provides a comprehensive interface for creating, manipulating, and persisting OWL (Web Ontology Language) ontologies. It acts as a central container for knowledge representation, managing entities such as classes, properties, individuals, and the axioms that define their logical relationships. Users can initialize the instance with a base IRI to create a new ontology or provide a file path to load an existing one. The class facilitates the addition of complex logical structures through methods that handle declarations, domains, ranges, and nested axioms, while also offering robust capabilities for attaching metadata annotations to the ontology itself, specific elements, or individual relations. Internally, it utilizes mapping and retrieval components to translate high-level objects into RDF/XML and query the underlying graph, ultimately supporting the export of the ontology to various file formats.

Module Contents

UML Class Diagram for OWLOntology

class OWLOntology(

base_iri: pyowl2.base.iri.IRI | rdflib.URIRef,

ontology_path: str | None = None,

OWL1_annotations: bool = False,

)

This class provides a comprehensive interface for creating, manipulating, and persisting OWL (Web Ontology Language) ontologies. It acts as a central container for knowledge representation, managing entities such as classes, properties, individuals, and the axioms that define their logical relationships. Users can initialize the instance with a base IRI to create a new ontology or provide a file path to load an existing one. The class facilitates the addition of complex logical structures through methods that handle declarations, domains, ranges, and nested axioms, while also offering robust capabilities for attaching metadata annotations to the ontology itself, specific elements, or individual relations. Internally, it utilizes mapping and retrieval components to translate high-level objects into RDF/XML and query the underlying graph, ultimately supporting the export of the ontology to various file formats.

Parameters:

• ontology_iri (Optional[URIRef]) – The Internationalized Resource Identifier (IRI) that uniquely identifies the ontology. It serves as the base IRI for the namespace and is used to retrieve or create the ontology instance within the underlying world.

• axioms (list[OWLAxiom]) – A list of axioms that define the logical statements and relationships within the ontology.

• ontology_annotations (Optional[list[OWLAnnotation]]) – Internal storage for the list of annotations providing metadata about the ontology itself, such as creator, version, or other descriptive details.

• world (World) – The World instance that manages the ontology’s context and provides access to the underlying RDF graph.

• ontology (Ontology) – The underlying ontology instance managed by the World object, serving as the core data structure for storing, loading, and persisting the ontology’s contents.

• clear (RDFXMLClear) – An instance used to clear the ontology’s content during initialization, ensuring a clean state for newly created ontologies.

• mapper (RDFXMLMapper) – Internal component that maps OWL axioms and annotations to the underlying RDF graph, enabling the translation of high-level ontology constructs into a storable format.

• getter (RDFXMLGetter) – Responsible for retrieving axioms and annotations from the ontology, providing methods to query and extract specific elements based on various criteria.

add_annotation(annotation: pyowl2.base.annotation.OWLAnnotation) → bool

Associates a single metadata annotation with the ontology by wrapping the bulk addition method. It accepts an OWLAnnotation object representing the metadata to be attached and attempts to persist it within the ontology structure. The operation returns a boolean value indicating success; it yields True if the annotation is successfully integrated, and False if the underlying process encounters an exception or mapping error. This method modifies the ontology’s state by adding the specified annotation to its collection of annotations.

Parameters:

annotation (OWLAnnotation) – Metadata to be added to the ontology.

Returns:

True if the annotation was successfully added to the ontology, False if an error occurred.

Return type:

bool

add_annotation_to_element(

element: pyowl2.abstracts.object.OWLObject,

annotations: list[pyowl2.base.annotation.OWLAnnotation] | None,

)

This method attaches a list of metadata annotations to a specific ontology element, such as a class, property, or individual, thereby enriching the element’s documentation. The operation is performed within a managed context to ensure the integrity of the underlying ontology structure while the internal mapper applies the changes. It returns True if the annotations are successfully added; if an exception occurs during the mapping or attachment process, the error is printed to standard output and the method returns False.

Parameters:

• element (OWLObject) – The target ontology entity or axiom to which the annotations will be attached.

• annotations (Optional[list[OWLAnnotation]]) – A list of OWLAnnotation objects representing the metadata to associate with the element, or None.

add_annotations(annotations: list[pyowl2.base.annotation.OWLAnnotation] | None) → bool

Associates a collection of metadata annotations with the ontology by delegating the mapping process to an internal mapper object. The operation is performed within a context manager to ensure proper resource handling during the modification. Upon successful completion, the method returns True; conversely, if any exception is raised during the mapping process, the error is printed to standard output and the method returns False.

Parameters:

annotations (Optional[list[OWLAnnotation]]) – A list of OWLAnnotation objects representing metadata to be added to the ontology. Can be None.

Returns:

True if the annotations were successfully added to the ontology, False if an error occurred during the process.

Return type:

bool

add_annotations_to_relation(

a: Any,

property: Any,

b: Any,

annotations: list[pyowl2.base.annotation.OWLAnnotation] | None,

) → bool

This method attaches a list of OWLAnnotation objects to a specific relation defined by the subject a, predicate property, and object b within the ontology. It delegates the actual mapping to the ontology’s mapper, operating within a context manager to ensure safe modification of the ontology state. The function returns a boolean indicating success; if an exception occurs during the process, the error is printed to standard output and the method returns False.

Parameters:

• a (Any) – The subject of the relation to be annotated. Used in conjunction with the property and object to identify the specific relation within the ontology.

• property (Any) – The predicate of the relation, acting as the property that links the subject to the object to identify the specific triple for annotation.

• b (Any) – The object of the relation to which the annotations should be added, used to identify the specific relation alongside the subject and predicate.

• annotations (Optional[list[OWLAnnotation]]) – A list of OWLAnnotation objects representing the metadata to be attached to the specified relation.

Returns:

True if the annotations were successfully added to the relation, False if an error occurred during the process.

Return type:

bool

add_axiom(axiom: Any) → None

Adds a logical axiom to the ontology by delegating the mapping process to the internal mapper object. This operation is performed within a context manager to ensure the underlying ontology resource is managed correctly during the modification.

Parameters:

axiom (Any) – The logical construct or statement to be added to the ontology, such as a class or property assertion.

add_axioms(axioms: list[pyowl2.abstracts.object.OWLObject]) → None

Adds a list of axioms to the ontology by iterating through the provided collection and mapping each logical statement to the underlying structure. The method performs specialized processing for complex entity types—specifically object properties, data properties, classes, data ranges, and individuals—by decomposing them into their constituent parts, including declarations, annotations, domains, ranges, and any associated inner axioms. Axioms that do not match these specific types are mapped directly without decomposition. Each addition operation is wrapped in a context manager to ensure the ontology is properly managed during the modification process.

Parameters:

axioms (list[OWLObject]) – A list of OWLObject instances representing logical statements to be added to the ontology. The method processes specific types—including object properties, data properties, classes, data ranges, and individuals—by mapping their declarations, domains, ranges, and inner axioms, while mapping other types directly.

get_axioms(axiom: pyowl2.getter.rdf_xml_getter.AxiomsType) → list[pyowl2.abstracts.object.OWLObject]

Retrieves a list of axioms from the ontology that match the specified type, enabling targeted queries of the ontology’s logical content. The method accepts an AxiomsType enumeration value to filter the results, returning a collection of OWLObject instances representing the requested axioms. Internally, the retrieval logic is delegated to the ontology’s underlying getter, and the method returns an empty list if no matching axioms are found or if an error occurs during the operation.

Parameters:

axiom (AxiomsType) – Specifies the category of axiom to retrieve from the ontology, acting as a filter to return only OWL objects matching the selected logical construct type.

Returns:

A list of OWL objects representing the axioms of the specified type retrieved from the ontology. Returns an empty list if no matching axioms are found or if an error occurs during retrieval.

Return type:

list[OWLObject]

print_all() → None

Iterates through every axiom type defined in the AxiomsType enumeration, retrieves the corresponding axioms from the ontology, and prints them to the console. The method uses a context manager to ensure the ontology resource is properly managed while accessing the data. For each axiom category, it prints the type name followed by the specific results retrieved via the internal getter, providing a comprehensive text-based overview of the ontology’s structure and contents. This operation produces side effects by writing to standard output and depends on the successful retrieval of data for each enumerated type.

save(filepath: str, format: str = 'rdfxml') → bool

Persists the current state of the ontology to a file at the specified path, serializing the data according to the given format (defaulting to RDF/XML). This method delegates the actual file writing operation to the underlying ontology object. Upon success, it returns True; if an error occurs—such as an invalid path, insufficient write permissions, or an unsupported format—the exception is caught, the error message is printed to standard output, and the method returns False without propagating the exception.

Parameters:

• filepath (str) – The destination file system path where the ontology will be written.

• format (str) – The serialization format for the ontology file (e.g., “rdfxml”, “turtle”).

Returns:

True if the ontology was successfully saved to the specified file, False if an error occurred during the operation.

Return type:

bool

_axioms: list[pyowl2.abstracts.axiom.OWLAxiom] = []

_getter: pyowl2.getter.rdf_xml_getter.RDFXMLGetter

_mapper: pyowl2.mapper.rdf_xml_mapper.RDFXMLMapper

_ontology_annotations: list[pyowl2.base.annotation.OWLAnnotation] | None = None

_ontology_iri: rdflib.URIRef | None

_world: owlready2.World

property axioms: list[pyowl2.abstracts.axiom.OWLAxiom]

Replaces the current collection of axioms associated with this ontology with the provided list of OWLAxiom instances. This setter performs a direct assignment to the internal storage, effectively discarding any previously held axioms without performing validation or deep copying. Consequently, the ontology’s state is immediately updated to reflect the new set of axioms.

Parameters:

value (list[OWLAxiom]) – The axioms to assign to the object.

property getter: pyowl2.getter.rdf_xml_getter.RDFXMLGetter

Returns the RDFXMLGetter instance associated with this ontology. This property provides access to the internal component responsible for handling RDF/XML data retrieval or parsing. It exposes the value of the private _getter attribute without modifying the state of the ontology.

Returns:

The RDFXMLGetter instance associated with this object.

Return type:

RDFXMLGetter

property mapper: pyowl2.mapper.rdf_xml_mapper.RDFXMLMapper

Returns the RDFXMLMapper instance associated with this ontology. This mapper is responsible for handling the conversion between the ontology’s internal object representation and the RDF/XML serialization format. Accessing this property has no side effects and simply retrieves the pre-configured mapper object.

Returns:

The RDFXMLMapper instance associated with this object.

Return type:

RDFXMLMapper

property namespace: rdflib.Namespace

Retrieves the Namespace object corresponding to the ontology’s IRI. This property provides access to the namespace context by delegating to the underlying ontology handler, allowing for the generation and management of identifiers relative to the ontology’s base IRI.

Returns:

The Namespace object associated with the ontology IRI.

Return type:

Namespace

property ontology_annotations: list[pyowl2.base.annotation.OWLAnnotation] | None

Replaces the current collection of annotations associated with the ontology with the provided list. This method acts as the setter for the ontology_annotations property, allowing direct assignment of a list of OWLAnnotation objects to the underlying private attribute. Note that this operation overwrites any existing annotations rather than appending to them.

Parameters:

value (list[OWLAnnotation]) – A list of OWL annotations to assign to the ontology.

property ontology_iri: rdflib.URIRef | None

Sets the Internationalized Resource Identifier (IRI) for the ontology, effectively updating its primary identifier. This method accepts a URIRef object or None, assigning the value to the internal _ontology_iri attribute. If None is provided, the ontology IRI is cleared; otherwise, it is replaced with the specified URI reference.

Parameters:

value (Optional[URIRef]) – The Internationalized Resource Identifier (IRI) to assign to the ontology.

logger