pyowl2.utils.datatype

Provides a structured builder for defining OWL 2 Full data ranges, managing their identity, logical constraints, and associated axioms.

Description

The software implements a builder pattern for constructing and managing OWL 2 Full data ranges, encapsulating a datatype identity defined by an Internationalized Resource Identifier (IRI) alongside a collection of logical axioms. It enables the programmatic definition of complex data structures—such as intersections, unions, complements, and facet-based restrictions—by automatically generating and storing the necessary OWL axioms while preventing duplicate entries. The design normalizes various input types, seamlessly handling both base data range objects and wrapper instances to establish equivalence relationships and datatype definitions. This separation of identity from logical constraints facilitates the creation of rich ontology definitions, allowing developers to incrementally build up the rules governing valid data values.

Classes

OWLFullDataRange

This class provides a structured representation of a data range in an OWL ontology, encapsulating the core datatype definition along with its associated logical axioms and metadata annotations. It functions as a builder object, allowing users to define complex data range expressions—such as intersections, unions, complements, and facet-based restrictions—through a fluent interface that generates and stores the necessary OWL axioms. By separating the identity of the data range from its logical constraints, it facilitates the programmatic construction of rich datatype definitions while automatically managing the internal list of axioms to prevent duplicates.

Module Contents

UML Class Diagram for OWLFullDataRange

class OWLFullDataRange(iri: pyowl2.base.iri.IRI)

Bases: pyowl2.abstracts.object.OWLObject

This class provides a structured representation of a data range in an OWL ontology, encapsulating the core datatype definition along with its associated logical axioms and metadata annotations. It functions as a builder object, allowing users to define complex data range expressions—such as intersections, unions, complements, and facet-based restrictions—through a fluent interface that generates and stores the necessary OWL axioms. By separating the identity of the data range from its logical constraints, it facilitates the programmatic construction of rich datatype definitions while automatically managing the internal list of axioms to prevent duplicates.

Parameters:

• data_range (OWLDataRange) – The core OWLDataRange instance holding the fundamental definition and IRI of the data range, which acts as the foundation for associated axioms and restrictions.

• axioms (list[OWLAxiom]) – Stores the axioms defining the logical structure and relationships of the data range, including intersections, unions, complements, and restrictions.

• annotations (Optional[list[OWLAnnotation]]) – Stores the optional list of annotations associated with the data range, providing metadata such as source or intended use.

Raises:

TypeError – Raised when the value argument is a list containing mixed types (e.g., both OWLDataRange and OWLFullDataRange instances) or invalid types.

define(datatype: pyowl2.base.datatype.OWLDatatype) → None

This method creates and adds an OWLDatatypeDefinition axiom to the current data range, asserting that the range is semantically defined by the specified OWLDatatype. This association links a custom data range, such as “Age”, to a concrete underlying type, such as “Integer”, thereby defining the set of valid values for the range within the ontology. The method ensures idempotency by checking the existing axioms; if the specific definition is already present, no duplicate is added. As a side effect, the new axiom is appended to the internal list of axioms associated with this data range.

Parameters:

datatype (OWLDatatype) – The datatype that defines this data range, asserting that the range consists of values belonging to the specified datatype.

is_complement_of(other: pyowl2.abstracts.data_range.OWLDataRange | Self) → None

Asserts that this data range is equivalent to the complement of the provided data range by adding an appropriate equivalence axiom to the ontology. The method accepts either an OWLDataRange instance or another OWLFullDataRange instance, extracting the underlying data range from the latter if necessary. This establishes a semantic relationship where this range encompasses all values that are not members of the specified other range. The operation is idempotent, ensuring that the axiom is not added redundantly if it already exists within the entity’s axioms.

Parameters:

other (Union[OWLDataRange, Self]) – The data range that this data range is asserted to be the complement of. Can be an OWLDataRange or an instance of the current class.

is_equivalent_to(

value: pyowl2.abstracts.data_range.OWLDataRange | Self | list[pyowl2.abstracts.data_range.OWLDataRange] | list[Self],

) → None

Asserts that the current data range is semantically equivalent to one or more other data ranges by generating an OWLEquivalentClasses axiom. The method accepts either a single data range or a list of data ranges, which may be provided as OWLDataRange objects or OWLFullDataRange instances. If a list is supplied, all elements must be of the same consistent type; otherwise, a TypeError is raised. To prevent redundancy, the method verifies whether the generated axiom already exists within the instance’s internal axiom collection and, if so, skips the addition. The primary side effect is the modification of the internal axioms list by appending the newly created equivalence relationship.

Parameters:

value (Union[OWLDataRange, Self, list[OWLDataRange], list[Self]]) – A single data range or a list of data ranges to be asserted as equivalent to this data range.

Raises:

TypeError – Raised when the provided value is a list containing elements of inconsistent types, specifically if the list is not composed entirely of OWLDataRange instances or entirely of OWLFullDataRange instances.

is_intersection_of(data_ranges: list[pyowl2.abstracts.data_range.OWLDataRange] | list[Self]) → None

Asserts that the current data range is equivalent to the intersection of itself and a provided list of other data ranges by constructing and registering an OWLDataIntersectionOf axiom. The method accepts a list of data ranges, which can be either base OWLDataRange objects or OWLFullDataRange instances, and normalizes them to extract the underlying data ranges for the intersection. It modifies the object’s internal state by appending the new axiom to its axioms list, but only if the specific axiom does not already exist, ensuring that duplicate definitions are not added.

Parameters:

data_ranges (Union[list[OWLDataRange], list[Self]]) – A list of data ranges to intersect with the current data range. Elements may be OWLDataRange instances or instances of the current class, from which the underlying data range is extracted.

is_one_of(literals: list[pyowl2.literal.literal.OWLLiteral] | list[rdflib.Literal]) → None

Restricts the data range to a specific enumeration of values by asserting equivalence to an OWLDataOneOf axiom. The method accepts a list of literals, which may be either OWLLiteral instances or RDF Literal instances. If the provided list consists entirely of RDF Literal objects, they are passed directly to the axiom constructor; otherwise, the underlying values are extracted from the OWLLiteral objects. This operation modifies the data range by adding an equivalence axiom, effectively defining a closed set of allowed values.

Parameters:

literals (Union[list[OWLLiteral], list[Literal]]) – A list of literal values to enumerate as the valid set for this data range, accepting either OWLLiteral or rdflib Literal instances.

is_union_of(data_ranges: list[pyowl2.abstracts.data_range.OWLDataRange] | list[Self]) → None

Asserts that this data range is equivalent to the union of itself and a provided list of other data ranges by constructing and registering an OWLDataUnionOf axiom. The method accepts a list containing either standard OWLDataRange instances or OWLFullDataRange instances; in the latter case, the underlying data range of each instance is extracted to form the union. This operation is idempotent, meaning that if an identical union axiom already exists within the object’s axioms, no duplicate is added. As a side effect, the newly created axiom is appended to the internal list of axioms associated with this data range.

Parameters:

data_ranges (Union[list[OWLDataRange], list[Self]]) – A list of data ranges that constitute the union together with the current instance. Elements may be OWLDataRange objects or instances of the current class.

restrict(datatype: pyowl2.base.datatype.OWLDatatype, facets: list[pyowl2.data_range.datatype_restriction.OWLFacet]) → None

Adds a datatype restriction axiom to the current data range, constraining its values to a specific datatype and a set of facet restrictions. The method constructs an OWLDatatypeRestriction using the provided datatype and facets, then appends it to the internal list of axioms. If an identical restriction already exists within the axioms, the method performs no action to prevent duplication.

Parameters:

• datatype (OWLDatatype) – The base OWL datatype being restricted, defining the underlying type of values that are further constrained by the provided facets.

• facets (list[OWLFacet]) – A list of OWLFacet instances specifying the constraints applied to the datatype to define the valid values for this data range.

to_complement() → None

Adds an OWLDataComplementOf axiom to the internal collection of axioms for this data range. The method constructs a complement object representing the logical negation of the current data range and appends it, provided that an identical axiom does not already exist. This ensures idempotency by preventing duplicate entries, and the method modifies the object’s state without returning a value.

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

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

_data_range: pyowl2.abstracts.data_range.OWLDataRange

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

Updates the collection of annotations associated with this OWL full data range by replacing the existing list with the provided value. The input should be a list of OWLAnnotation objects or None, where None effectively clears the stored annotations. This setter modifies the object’s internal state directly.

Parameters:

value (Optional[list[OWLAnnotation]]) – The list of OWL annotations to set, or None to clear existing annotations.

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

Retrieves the list of axioms associated with this OWL Full data range. This property provides direct access to the internal collection of OWLAxiom objects that define the logical constraints or characteristics of the data range. As a simple getter, it returns the stored list without performing any computation or modifying the object’s state.

Returns:

The list of axioms associated with this object.

Return type:

list[OWLAxiom]

property data_range: pyowl2.abstracts.data_range.OWLDataRange

Returns the OWLDataRange object associated with this OWLFullDataRange instance. This property provides direct access to the underlying data range definition, which specifies the set of literal values or data types represented in the ontology. Since this is a read-only property, it does not modify the internal state of the object.

Returns:

The OWL data range associated with this object.

Return type:

OWLDataRange

property intersections: list[pyowl2.data_range.data_intersection_of.OWLDataIntersectionOf]

Retrieves a list of axioms that define this data range as an intersection of other data ranges by filtering the internal collection for instances of OWLDataIntersectionOf. This property provides a way to access complex data range expressions where the current range is a component of an intersection. The operation is read-only and returns an empty list if no matching axioms are found.

Returns:

A list of axioms representing the intersection of data ranges associated with this data range.

Return type:

list[OWLDataIntersectionOf]

property is_complement: bool

Indicates whether this data range is defined as the logical complement of another data range within the ontology. This property evaluates the axioms associated with the entity to determine if it represents a negation of another range, returning True if an OWLDataComplementOf axiom is present. The check is performed by iterating over the entity’s axioms, and it returns False if no such defining complement axiom exists.

Returns:

True if this data range is defined as a complement of another data range, False otherwise.

Return type:

bool

property ones_of: list[pyowl2.data_range.data_one_of.OWLDataOneOf]

Retrieves a list of OWLDataOneOf axioms associated with this data range by filtering the internal collection of axioms for instances of that specific type. Each returned axiom represents a data enumeration, defining a range that consists exclusively of a specified set of literal values. This property performs a read-only operation and returns an empty list if no such enumeration axioms are present.

Returns:

A list of OWLDataOneOf axioms associated with this data range, representing enumerations of specific data values.

Return type:

list[OWLDataOneOf]

property restrictions: list[pyowl2.data_range.datatype_restriction.OWLDatatypeRestriction]

This property retrieves a list of datatype restrictions associated with this data range by filtering the internal collection of axioms for instances of OWLDatatypeRestriction. These restrictions represent specific constraints, such as minimum or maximum values, applied to the underlying datatype to form complex data range expressions. The returned list is a new list object; modifying it will not alter the state of the data range, and an empty list is returned if no matching restrictions are found.

Returns:

A list of OWLDatatypeRestriction axioms associated with this data range, representing constraints or facets applied to the datatype.

Return type:

list[OWLDatatypeRestriction]

property unions: list[pyowl2.data_range.data_union_of.OWLDataUnionOf]

Retrieves a list of OWLDataUnionOf axioms associated with this data range by filtering the internal collection of axioms for instances of the union type. This property provides access to complex data range expressions where the current range is defined as a union of other data ranges. The returned list is a new list object generated at call time, and modifying it will not affect the internal state of the data range; if no union axioms are associated, an empty list is returned.

Returns:

A list of axioms defining this data range as a union of other data ranges.

Return type:

list[OWLDataUnionOf]