interface

Provides the ITriplestore protocol class, that documents the interface of the triplestore backends.

ITriplestore (Protocol)

Interface for triplestore backends.

In addition to the methods specified by this interface, a backend may also implement the following optional methods:

# Whether the backend perfers SPQRQL queries instead of using the
# triples() method.
prefer_sparql = True

def parse(
        self,
        source: Union[str, Path, IO] = None,
        location: str = None,
        data: str = None,
        format: str = None,
        **kwargs
    ):
    """Parse source and add the resulting triples to triplestore.

    The source is specified using one of `source`, `location` or `data`.

    Arguments:
        source: File-like object or file name.
        location: String with relative or absolute URL to source.
        data: String containing the data to be parsed.
        format: Needed if format can not be inferred from source.
        kwargs: Additional backend-specific parameters controlling
            the parsing.
    """

def serialize(
        self,
        destination: Union[str, Path, IO] = None,
        format: str ='xml',
        **kwargs
    ):
    """Serialise to destination.

    Arguments:
        destination: File name or object to write to.  If None, the
            serialisation is returned.
        format: Format to serialise as.  Supported formats, depends on
            the backend.
        kwargs: Additional backend-specific parameters controlling
            the serialisation.

    Returns:
        Serialised string if `destination` is None.
    """

def query(self, query_object: str, **kwargs) -> List[Tuple[str, ...]]:
    """SPARQL query.

    Arguments:
        query_object: String with the SPARQL query.
        kwargs: Additional backend-specific keyword arguments.

    Returns:
        The return type depends on type of query:
          - SELECT: list of tuples of IRIs for each matching row
          - ASK: bool
          - CONSTRUCT, DESCRIBE: generator over triples
    """

def update(self, update_object: str, **kwargs):
    """Update triplestore with SPARQL.

    Arguments:
        query_object: String with the SPARQL query.
        kwargs: Additional backend-specific keyword arguments.

    Note:
        This method is intended for INSERT and DELETE queries.  Use
        the query() method for SELECT queries.
    """

def bind(self, prefix: str, namespace: str) -> Namespace:
    """Bind prefix to namespace.

    Should only be defined if the backend supports namespaces.
    """

def namespaces(self) -> dict:
    """Returns a dict mapping prefixes to namespaces.

    Should only be defined if the backend supports namespaces.
    Used by triplestore.parse() to get prefixes after reading
    triples from an external source.
    """

@classmethod
def create_database(cls, database: str, **kwargs):
    """Create a new database in backend.

    Parameters:
        database: Name of the new database.
        kwargs: Keyword arguments passed to the backend
            create_database() method.

    Note:
        This is a class method, which operates on the backend
        triplestore without connecting to it.
    """

@classmethod
def remove_database(cls, database: str, **kwargs):
    """Remove a database in backend.

    Parameters:
        database: Name of the database to be removed.
        kwargs: Keyword arguments passed to the backend
            remove_database() method.

    Note:
        This is a class method, which operates on the backend
        triplestore without connecting to it.
    """

@classmethod
def list_databases(cls, **kwargs):
    """For backends that supports multiple databases, list of all
    databases.

    Parameters:
        kwargs: Keyword arguments passed to the backend
            list_database() method.

    Note:
        This is a class method, which operates on the backend
        triplestore without connecting to it.
    """

Source code in tripper/interface.py

class ITriplestore(Protocol):
    '''Interface for triplestore backends.

    In addition to the methods specified by this interface, a backend
    may also implement the following optional methods:

    ```python

    # Whether the backend perfers SPQRQL queries instead of using the
    # triples() method.
    prefer_sparql = True

    def parse(
            self,
            source: Union[str, Path, IO] = None,
            location: str = None,
            data: str = None,
            format: str = None,
            **kwargs
        ):
        """Parse source and add the resulting triples to triplestore.

        The source is specified using one of `source`, `location` or `data`.

        Arguments:
            source: File-like object or file name.
            location: String with relative or absolute URL to source.
            data: String containing the data to be parsed.
            format: Needed if format can not be inferred from source.
            kwargs: Additional backend-specific parameters controlling
                the parsing.
        """

    def serialize(
            self,
            destination: Union[str, Path, IO] = None,
            format: str ='xml',
            **kwargs
        ):
        """Serialise to destination.

        Arguments:
            destination: File name or object to write to.  If None, the
                serialisation is returned.
            format: Format to serialise as.  Supported formats, depends on
                the backend.
            kwargs: Additional backend-specific parameters controlling
                the serialisation.

        Returns:
            Serialised string if `destination` is None.
        """

    def query(self, query_object: str, **kwargs) -> List[Tuple[str, ...]]:
        """SPARQL query.

        Arguments:
            query_object: String with the SPARQL query.
            kwargs: Additional backend-specific keyword arguments.

        Returns:
            The return type depends on type of query:
              - SELECT: list of tuples of IRIs for each matching row
              - ASK: bool
              - CONSTRUCT, DESCRIBE: generator over triples
        """

    def update(self, update_object: str, **kwargs):
        """Update triplestore with SPARQL.

        Arguments:
            query_object: String with the SPARQL query.
            kwargs: Additional backend-specific keyword arguments.

        Note:
            This method is intended for INSERT and DELETE queries.  Use
            the query() method for SELECT queries.
        """

    def bind(self, prefix: str, namespace: str) -> Namespace:
        """Bind prefix to namespace.

        Should only be defined if the backend supports namespaces.
        """

    def namespaces(self) -> dict:
        """Returns a dict mapping prefixes to namespaces.

        Should only be defined if the backend supports namespaces.
        Used by triplestore.parse() to get prefixes after reading
        triples from an external source.
        """

    @classmethod
    def create_database(cls, database: str, **kwargs):
        """Create a new database in backend.

        Parameters:
            database: Name of the new database.
            kwargs: Keyword arguments passed to the backend
                create_database() method.

        Note:
            This is a class method, which operates on the backend
            triplestore without connecting to it.
        """

    @classmethod
    def remove_database(cls, database: str, **kwargs):
        """Remove a database in backend.

        Parameters:
            database: Name of the database to be removed.
            kwargs: Keyword arguments passed to the backend
                remove_database() method.

        Note:
            This is a class method, which operates on the backend
            triplestore without connecting to it.
        """

    @classmethod
    def list_databases(cls, **kwargs):
        """For backends that supports multiple databases, list of all
        databases.

        Parameters:
            kwargs: Keyword arguments passed to the backend
                list_database() method.

        Note:
            This is a class method, which operates on the backend
            triplestore without connecting to it.
        """

    ```
    '''

    def __init__(self, base_iri: "Optional[str]" = None, **kwargs):
        """Initialise triplestore.

        Arguments:
            base_iri: Optional base IRI to initiate the triplestore from.
            kwargs: Additional keyword arguments passed to the backend.
        """

    def triples(self, triple: "Triple") -> "Generator":
        """Returns a generator over matching triples.

        Arguments:
            triple: A `(s, p, o)` tuple where `s`, `p` and `o` should
                either be None (matching anything) or an exact IRI to
                match.
        """

    def add_triples(self, triples: "Sequence[Triple]"):
        """Add a sequence of triples.

        Arguments:
            triples: A sequence of `(s, p, o)` tuples to add to the
                triplestore.
        """

    def remove(self, triple: "Triple"):
        """Remove all matching triples from the backend."""

add_triples(self, triples)

Add a sequence of triples.

Parameters:

Name	Type	Description	Default
triples	Sequence[Triple]	A sequence of (s, p, o) tuples to add to the triplestore.	required

Source code in tripper/interface.py

def add_triples(self, triples: "Sequence[Triple]"):
    """Add a sequence of triples.

    Arguments:
        triples: A sequence of `(s, p, o)` tuples to add to the
            triplestore.
    """

remove(self, triple)

Remove all matching triples from the backend.

Source code in tripper/interface.py

def remove(self, triple: "Triple"):
    """Remove all matching triples from the backend."""

triples(self, triple)

Returns a generator over matching triples.

Parameters:

Name	Type	Description	Default
triple	Triple	A (s, p, o) tuple where s, p and o should either be None (matching anything) or an exact IRI to match.	required

Source code in tripper/interface.py

def triples(self, triple: "Triple") -> "Generator":
    """Returns a generator over matching triples.

    Arguments:
        triple: A `(s, p, o)` tuple where `s`, `p` and `o` should
            either be None (matching anything) or an exact IRI to
            match.
    """