ontouml_models_lib.model ======================== .. py:module:: ontouml_models_lib.model .. autoapi-nested-parse:: The `model` module provides the `Model` class, a specialized extension of the `QueryableElement` class, designed for managing and interacting with individual ontology models within the OntoUML/UFO catalog. This module facilitates the loading, querying, and management of RDF graphs and associated metadata for ontology models, ensuring compliance with the metadata schema specified in Appendix A. Overview -------- The `Model` class represents a single ontology model, encapsulating its RDF graph and metadata, and provides methods for querying and interacting with this data. The metadata attributes, such as `title`, `keyword`, `acronym`, `language`, and others, are populated based on a YAML file and follow the standards defined in the OntoUML/UFO catalog's metadata schema. The class is built to support operations on ontology models stored in RDF formats, such as Turtle, and accompanied by metadata in YAML format. Usage ----- Example 1: Loading a Model and Accessing Metadata >>> from ontouml_models_lib import Model >>> model = Model('/path/to/ontology_model_folder') >>> print(model.title) # Output: "Example Ontology Title" >>> print(model.keyword) # Output: ["ontology", "example"] Example 2: Executing a Query on the Model >>> from ontouml_models_lib import Model >>> from ontouml_models_lib import Query >>> model = Model('/path/to/ontology_model_folder') >>> query = Query('/path/to/query.sparql') >>> results = model.execute_query(query, '/path/to/results') >>> print(results) # Output: [{'subject': 'ExampleSubject', 'predicate': 'ExamplePredicate', 'object': 'ExampleObject'}] Dependencies ------------ - **rdflib**: For RDF graph operations and SPARQL query execution. - **yaml**: For parsing YAML files containing metadata. - **loguru**: For logging operations and debugging information. References ---------- For additional details on the OntoUML/UFO catalog, refer to the official OntoUML repository: https://github.com/OntoUML/ontouml-models Classes ------- .. autoapisummary:: ontouml_models_lib.model.Model Module Contents --------------- .. py:class:: Model(model_path) Bases: :py:obj:`ontouml_models_lib.utils.queryable_element.QueryableElement` Represents an individual ontology model within the OntoUML/UFO catalog. The `Model` class extends the `QueryableElement` class to manage and interact with RDF graphs representing ontology models. It provides methods for loading RDF graphs, extracting metadata from associated YAML files, and executing SPARQL queries. This class ensures that ontology data is consistently managed and that metadata attributes are easily accessible. :ivar title: The title of the ontology model, as determined by the `dct:title` property. There must be at most one title per language. :vartype title: str :ivar keyword: A list of keywords associated with the ontology model, aiding in the categorization and searchability of the model. :vartype keyword: list[str] :ivar acronym: An optional acronym for the ontology model, providing a shorthand identifier. :vartype acronym: Optional[str] :ivar source: The source or origin of the ontology model, typically a publication, organization, or project. It is recommended to use persistent and resolvable identifiers, such as DOIs or DBLP URIs, to refer to these resources. :vartype source: Optional[str] :ivar language: The language in which the lexical labels of the ontology model are written. The use of values from the IANA Language Sub Tag Registry (e.g., "en", "pt") is required. :vartype language: Optional[str] :ivar designedForTask: A list of standardized purposes for which the ontology model was designed, categorized using the OntologyPurpose enumeration. Examples include Conceptual Clarification, Data Publication, and Decision Support Systems. :vartype designedForTask: list[OntologyPurpose] :ivar context: The development context of the ontology model, classified under the OntologyDevelopmentContext enumeration. Examples include Research, Industry, and Classroom. :vartype context: list[OntologyDevelopmentContext] :ivar representationStyle: The representation style of the ontology model, categorized under the OntologyRepresentationStyle enumeration. Examples include OntoumlStyle and UfoStyle. :vartype representationStyle: Optional[OntologyRepresentationStyle] :ivar ontologyType: The type of ontology, categorized under the OntologyType enumeration. Examples include Core, Domain, and Application. :vartype ontologyType: Optional[OntologyType] :ivar theme: The central theme of the ontology model, identified according to a theme taxonomy such as the Library of Congress Classification (LCC). :vartype theme: Optional[str] :ivar contributor: An optional contributor to the ontology model, typically a person or organization that contributed to its development. :vartype contributor: Optional[str] :ivar editorialNote: An optional editorial note providing additional context or comments regarding the ontology model. :vartype editorialNote: Optional[str] :ivar issued: The year the ontology model was issued or published, represented as an integer. :vartype issued: Optional[int] :ivar landingPage: A URL representing the landing page or home page for the ontology model. :vartype landingPage: Optional[str] :ivar license: The license under which the ontology model is distributed. It is recommended to use a standard license identifier, such as those from SPDX (e.g., "CC-BY-4.0"). :vartype license: Optional[str] :ivar modified: The year the ontology model was last modified, represented as an integer. :vartype modified: Optional[int] **Example**:: >>> from ontouml_models_lib import Model >>> model = Model('/path/to/ontology_model_folder') >>> print(model.title) # Output: "Example Ontology Title" >>> print(model.keyword) # Output: ["ontology", "example"] .. py:attribute:: acronym :type: Optional[str] :value: None .. py:attribute:: context :type: list[ontouml_models_lib.enumerations.OntologyDevelopmentContext] :value: [] .. py:attribute:: contributor :type: Optional[str] :value: None .. py:attribute:: designedForTask :type: list[ontouml_models_lib.enumerations.OntologyPurpose] :value: [] .. py:attribute:: editorialNote :type: Optional[str] :value: None .. py:attribute:: issued :type: Optional[int] :value: None .. py:attribute:: keyword :type: list[str] :value: [] .. py:attribute:: landingPage :type: Optional[str] :value: None .. py:attribute:: language :type: Optional[str] :value: None .. py:attribute:: license :type: Optional[str] :value: None .. py:attribute:: modified :type: Optional[int] :value: None .. py:attribute:: ontologyType :type: Optional[ontouml_models_lib.enumerations.OntologyType] :value: None .. py:attribute:: representationStyle :type: Optional[ontouml_models_lib.enumerations.OntologyRepresentationStyle] :value: None .. py:attribute:: source :type: Optional[str] :value: None .. py:attribute:: theme :type: Optional[str] :value: None .. py:attribute:: title :type: str :value: '' .. py:attribute:: model_path :type: pathlib.Path .. py:attribute:: path_model_graph .. py:attribute:: path_metadata_graph .. py:attribute:: path_metadata_yaml .. py:method:: _compute_consistent_hash(graph) Compute a consistent hash value for an RDFLib graph. This method generates a SHA-256 hash for an RDFLib graph by first serializing it to a canonical format (N-Triples), sorting the serialized triples, and then encoding the sorted serialization to UTF-8. The resulting hash value is used to ensure consistency and integrity of the graph's content. :param graph: The RDFLib graph to be hashed. :type graph: Graph :return: The computed hash value for the RDFLib graph. :rtype: int .. py:method:: _load_graph_safely(ontology_file) Safely load an RDFLib graph from a file. This method loads an RDFLib graph from a specified ontology file, ensuring that the file exists and is correctly parsed. It determines the file format based on its extension and returns the loaded graph. :param ontology_file: The path to the ontology file to be loaded. :type ontology_file: Path :return: The loaded RDFLib graph. :rtype: Graph :raises FileNotFoundError: If the ontology file does not exist. :raises OSError: If an error occurs during the parsing of the ontology file. .. py:method:: _populate_attributes(yaml_file) Populate the model's attributes from a YAML metadata file. This method reads a YAML file containing metadata and assigns the corresponding values to the model's attrs. It handles enumerations by matching the string values in the YAML file to the appropriate enumeration members. The method supports both single-value and list-value attributes. :param yaml_file: The path to the YAML file containing the metadata. :type yaml_file: Path :raises FileNotFoundError: If the YAML metadata file does not exist. :raises ValueError: If an invalid value is encountered for an enumeration attribute.