ontouml_models_lib.query
========================

.. py:module:: ontouml_models_lib.query

.. autoapi-nested-parse::

   The `query` module provides the `Query` class, designed to handle the loading, representation, and hashing of SPARQL queries for execution within the OntoUML/UFO catalog.

   This module ensures that SPARQL queries are consistently managed,
   enabling reliable query execution across RDF graphs representing ontology models.

   Overview
   --------
   The `Query` class encapsulates SPARQL queries, providing methods to load queries from files, compute persistent hashes
   to ensure the uniqueness and reusability of query results, and facilitate query execution across RDF graphs. This class
   is crucial for managing the integrity and consistency of queries used within the catalog.

   Usage
   -----
   Example 1: Loading a Query from a File

       >>> from ontouml_models_lib import Query
       >>> query = Query('/path/to/query.sparql')
       >>> print(query.query_content)
       # Output: "SELECT ?s WHERE { ?s ?p ?o }"

   Example 2: Computing the Hash of a Query

       >>> from ontouml_models_lib import Query
       >>> query = Query('/path/to/query.sparql')
       >>> print(query.hash)
       # Output: 12345678901234567890 (example hash value)

   Dependencies
   ------------
   - **hashlib**: For computing hashes of the SPARQL queries.
   - **pathlib**: For handling file paths in a platform-independent manner.

   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.query.Query


Module Contents
---------------

.. py:class:: Query(query_file)

   Represents a SPARQL query for execution within the OntoUML/UFO catalog.

   The `Query` class encapsulates a SPARQL query, providing methods for loading the query from a file, computing a
   persistent hash for the query content, and managing multiple queries through batch loading. This class ensures that
   queries are handled consistently, facilitating their reuse and reliable execution across RDF graphs representing
   ontology models.

   :ivar query_file_path: The path to the file from which the SPARQL query was loaded.
   :vartype query_file_path: Path
   :ivar query_content: The content of the SPARQL query as a string.
   :vartype query_content: str
   :ivar hash: A persistent hash value computed from the query content, used to ensure consistent result management.
   :vartype hash: int

   **Example**::

       >>> from ontouml_models_lib import Query
       >>> query = Query('/path/to/query.sparql')
       >>> print(query.query_content)
       # Output: "SELECT ?s WHERE { ?s ?p ?o }"


   .. py:attribute:: query_file


   .. py:attribute:: query_file_path
      :type:  pathlib.Path


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: query_content
      :type:  str


   .. py:attribute:: hash
      :type:  int


   .. py:method:: load_queries(queries_path)
      :staticmethod:


      Load all query_content files from the specified directory catalog_path and return a list of Query instances.

      :param queries_path: Path to the directory containing query_content files.
      :type queries_path: Path
      :return: List of Query instances.
      :rtype: list[Query]



   .. py:method:: execute_on_models(models, results_path = None)

      Execute the query on a list of models and consolidate the results into a single file.

      This method executes the query across multiple ontology models and saves all results
      into a single consolidated file.

      :param models: A list of Model instances on which the query will be executed.
      :type models: list[Model]
      :param results_path: Optional; Path to the directory where the query results should be saved.
                           If not provided, defaults to "./results".
      :type results_path: Optional[Union[str, Path]]

      :raises Exception: For any errors that occur during query execution.



   .. py:method:: _save_results(results, results_path, suffix = '')

      Save the results to a file.

      This method is responsible for saving the results of the query execution to a file.

      :param results: The results to save.
      :type results: list[dict]
      :param results_path: The path to save the results file.
      :type results_path: Path
      :param suffix: An optional suffix for the filename to distinguish different types of results.
      :type suffix: str



   .. py:method:: _read_query_file(query_file)
      :staticmethod:


      Read the content of a SPARQL query file.

      This method opens a SPARQL query file, reads its content, and returns it as a string. The file is read using
      UTF-8 encoding to ensure compatibility with a wide range of characters.

      :param query_file: The path to the SPARQL query file.
      :type query_file: Path
      :return: The content of the SPARQL query file as a string.
      :rtype: str
      :raises FileNotFoundError: If the specified query file does not exist.
      :raises OSError: If an error occurs while reading the query file.



   .. py:method:: _compute_persistent_hash(content)
      :staticmethod:


      Compute a persistent hash value for the content of a SPARQL query.

      This method generates a SHA-256 hash from the content of a SPARQL query string. The hash is computed in a way
      that ensures consistency across executions, facilitating the identification and management of query results.

      :param content: The content of the SPARQL query to be hashed.
      :type content: str
      :return: The computed hash value for the query content.
      :rtype: int