franz.openrdf.sail package — AllegroGraph Python client 105.1.0 documentation

# franz.openrdf.sail package

## Submodules

## franz.openrdf.sail.allegrographserver module

class franz.openrdf.sail.allegrographserver.AllegroGraphServer(host=None, port=None, user=None, password=None, cainfo=None, sslcert=None, verifyhost=None, verifypeer=None, protocol=None, proxy=None, **options)

  Bases: `object`

  The AllegroGraphServer object represents a remote AllegroGraph server on the network. It is used to inventory and access the catalogs of that server.

  __init__(host=None, port=None, user=None, password=None, cainfo=None, sslcert=None, verifyhost=None, verifypeer=None, protocol=None, proxy=None, **options)

    Define the connection to the AllegroGraph HTTP server.

    Pass either `user` and `password` for Basic Authentication or `cainfo`, `sslcert` values for client X.509 certificate authentication.

    Parameters:

      - host (string) – Address of the AllegroGraph server to connect to. This can also include protocol and port (e.g. http://localhost:10035). Can also be specified in the `AGRAPH_HOST` environment variable. The default value is `'localhost'``.

      - port (int) – Port on which the server is listening. The default is 10035 if `protocol` is `'http'` and 10036 if it is `'https'`. Can also be specified in the `AGRAPH_PORT` environment variable. If passed explicitly this parameter overrides any value that might have been specified as a part of the `host` string.

      - protocol (string) – Connection protocol, either `'http'` or `'https'`. The default is `'http'` if no SSL parameters are set and ‘https’` otherwise. If passed explicitly this parameter overrides any value that might have been specified as a part of the `host` string.

      - user (string) – Username (when using Basic authentication). Can also be specified in the `AGRAPH_USER` environment variable.

      - password (string) – Password (when using Basic authentication). Can also be specified in the `AGRAPH_PASSWORD` environment variable.

      - cainfo (string) – Path to a file or directory containing CA certificates that will be used to validate the server’s certificate.

      - sslcert (string) – Client certificate path (when using SSL authentication).

      - verifyhost (int) –

        If set to `0` it will not be an error if the server’s SSL certificate does not match the server’s address. The default value is `2`, meaning that the host name will be validated against the certificate.

        ..seealso:: https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html

      - verifypeer (int) –

        If set to `1` (the default) the validity of the server’s SSL certificate will be checked. Set to `0` to disable the validation.

        ..seealso:: https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html

      - proxy (string) – Proxy specification string. The format is SCHEME://HOST:PORT. Supported schemes are ‘http’, ‘socks4’ and ‘socks5’. Note that for SOCKS proxies DNS requests are performed by the proxy server. The default value is taken from the AGRAPH_PROXY environment variable.

      - options – Ignored.

  addRole(role)

    Creates a new role.

  addRoleAccess(role, read, write, catalog='*', repository='*')

    Grant read/write access to a role. See here for the parameters that are expected.

  addRolePermission(role, _type)

    Grants a role a certain permission. type should be super, eval, or session.

  addRoleSecurityFilter(role, _type, s=None, p=None, o=None, g=None)

    Add a security filter for the user.

    role - role name _type - one of ‘allow’ or ‘disallow’ s - optional subject p - optional predicate o - optional predicate g - optional graph

  addScript(module, code)

    Create or replace a sitescript.

    Parameters:

      - module (string) – Script name.

      - code (string) – Script content.

  addUser(name, password=None)

    Create a new user. Expects a password parameter, which specifies the user’s password (can be left off when creating the anonymous user).

  addUserAccess(name, read, write, catalog='*', repository='*')

    Grant read/write access to a user.

    Parameters:

      - read (bool) – Whether to grant read access. Defaults to `False`.

      - write (bool) – Whether to grant write access. Defaults to `False`.

      - catalog (string) – Which catalog to grant the access on. Leave off or pass `"*"` to grant access on all catalogs. Use `"/"` for the root catalog.

      - repository (string) – Specifies the repository that access is granted on. Passing `"*"`, or leaving the parameter off, means all repositories in the given catalog.

  addUserPermission(name, _type)

    Assigns the given permission to this user. type should be super, eval, replication, or session.

  addUserRole(name, role)

    Add a role to a user.

  addUserSecurityFilter(name, _type, s=None, p=None, o=None, g=None)

    Add a security filter for the user.

    name - user name _type - one of ‘allow’ or ‘disallow’ s - optional subject p - optional predicate o - optional predicate g - optional graph

  changeUserPassword(name, password)

    Change the password for the given user.

  defineFedshards(definitions='', file=None, supersede=False)

    Define one or more fedshards. You can pass either a string containing the definitions or a filename of a file containing the definitions.

  deleteFedshardDefinition(repo)

    Delete a fedshard definition but not the contents of the repositories in the fedshard. repo is a string naming a defined fedshard.

  deleteRole(role)

    Deletes a role.

  deleteRoleAccess(role, read, write, catalog='*', repository='*')

    Revoke read/write access for a role. Accepts the same parameters as above.

  deleteRolePermission(role, _type)

    Revokes a permission for a role.

  deleteRoleSecurityFilter(role, _type, s=None, p=None, o=None, g=None)

    Add a security filter for the user.

    role - role name _type - one of ‘allow’ or ‘disallow’ s - optional subject p - optional predicate o - optional predicate g - optional graph

  deleteScript(module)

    Delete a sitescript. :param module: Script name. :type module: string

  deleteUser(name)

    Delete a user.

  deleteUserAccess(name, read, write, catalog='*', repository='*')

    Takes the same parameters as PUT on this URL, but revokes the access instead of granting it.

  deleteUserData(key)

    Remove user data from the server.

    This removes a value set with `setUserData()`

    Parameters:

      key (str) – Value identifier.

  deleteUserPermission(name, _type)

    Revokes the given permission for this user.

  deleteUserRole(name, role)

    Remove a role from a user.

  deleteUserSecurityFilter(name, _type, s=None, p=None, o=None, g=None)

    Add a security filter for the user.

    name - user name _type - one of ‘allow’ or ‘disallow’ s - optional subject p - optional predicate o - optional predicate g - optional graph

  getInitfile()

    Retrieve the contents of the server initialization file.

    The initialization file is a collection of Common Lisp code that is executed in every back-end as it is created. :return: Init file content. :rtype: string

  getScript(module)

    Get the body of a sitescript. :param module: Script name. :type module: string :return: Script content. :rtype: string

  getUserData(key)

    Retrieve user data value with given key.

    Users can store arbitrary strings on the server using `setUserData()`.

    Parameters:

      key (str) – Value identifier.

    Returns:

      Stored string or None if there is no data under specified key.

    Return type:

      str|None

  listCatalogs()

    Get the list of catalogs on this server.

    A value of `None` will be included in this list to represent the root catalog.

    Returns:

      A list of catalog names.

    Return type:

      list[string]

  listRoleAccess(role)

    Query the access granted to a role. Returns a result in the same format as the equivalent service for users.

  listRolePermissions(role)

    Lists the permission flags granted to a role.

  listRoleSecurityFilters(role, _type)

    List security filters for user.

    _type is one of “allow”, “disallow”

  listRoles()

    Returns the names of all defined roles.

  listScripts()

    Return the list of Sitescripts currently on the server.

    When a user creates a session, they can choose to load one or more of these scripts into the session.

    Returns:

      A list of script names.

    Return type:

      list[string]

  listUserAccess(name)

    Retrieve the read/write access for a user. This returns a result set, each element of which has a read, write, catalog, and repository component. The first two are booleans, the latter two strings. For permissions granted globally, catalog and repository will have a value of “*”, for those granted per-catalog, only repository will be “*”. catalog normally contains the catalog name, but for the rootAs above, but also includes the access granted to roles that this user has. catalog “/” is used.

  listUserData()

    Get all used keys from the user data store on the server.

    Returns:

      A list of key names.

    Return type:

      list[str]

  listUserEffectiveAccess(name)

    Like listUserAccess, but also includes the access granted to roles that this user has.

  listUserEffectivePermissions(name)

    Retrieve the permission flags assigned to the user, or any of its roles.

  listUserPermissions(name)

    List the permission flags that have been assigned to a user (any of super, eval, session, replication).

  listUserRoles(name)

    Retrieves a list of role names for this user name.

  listUserSecurityFilters(name, _type)

    List security filters for user.

    _type is one of “allow”, “disallow”

  listUsers()

    Returns a list of names of all the users that have been defined.

  openCatalog(name=None)

    Open a catalog by name. Pass None to open the root catalog.

    Parameters:

      name – One of the catalog names from `listCatalogs()` or `None` to open the root catalog.

    Returns:

      A catalog object.

    Return type:

      Catalog

  openFederated(repositories, autocommit=False, lifetime=None, loadinitfile=False)

    Open a session that federates several repositories. The repositories argument must be an array containing store designators, which can be Repository or RepositoryConnection objects, strings (naming a store in the root catalog, or the URL of a store), or (storename, catalogname) tuples.

    Parameters:

      - repositories (list[string|(string, string)|Repository|RepositoryConnection]) – List of repositories to federate.

      - autocommit (bool) – Autocommit mode (default: `False` = start a transaction).

      - lifetime – The number of seconds a session can be idle before being terminated. The default value is 300 (5 minutes). The maximum acceptable value is 21600 (6 hours).

      - loadinitfile (bool) – If `True` the init file will be loaded into the new session. The default is False.

    Returns:

      A connection to the new session.

    Return type:

      RepositoryConnection

  openSession(spec, autocommit=False, lifetime=None, loadinitfile=False)

    Open a session on a federated, reasoning, or filtered store.

    Use the helper functions in the `franz.openrdf.sail.spec` module to create the spec string.

    Parameters:

      - spec (string) – Session `specification string`.

      - autocommit (bool) – Autocommit mode (default: `False` = start a transaction).

      - lifetime – The number of seconds a session can be idle before being terminated. The default value is 300 (5 minutes). The maximum acceptable value is 21600 (6 hours).

      - loadinitfile (bool) – If `True` the init file will be loaded into the new session. The default is False.

    Returns:

      A connection to the new session.

    Return type:

      RepositoryConnection

  setInitfile(content=None, restart=True)

    Replace the current initialization file contents with the `content` string or remove if None.

    Parameters:

      - content (string) – New init file conent.

      - restart – specifies whether any running shared back-ends should be shut down, so that subsequent requests will be handled by back-ends that include the new code. Default is `True`.

  setUserData(key, data)

    Set user data with given key.

    This can be used to store arbitrary strings on the server.

    Parameters:

      - key (str) – Value identifier.

      - data (str) – Value to be stored.

  startGraphTalker(api_key=None)

    Start a GraphTalker instance on this server and return a client for it.

    Calls `GET /graphtalker` on the AllegroGraph server, which starts a new GraphTalker process and redirects to `/graphtalker/PORT/`. A `GraphTalkerClient` connected to that port is returned.

    The returned client is not yet associated with a specific repository. Call `connect()` on it (or use `startGraphTalker()` instead) to point it at a repository before issuing queries.

    Parameters:

      api_key (str | None) – API key passed to the GraphTalker client (optional).

    Returns:

      A `GraphTalkerClient` instance.

    Return type:

      franz.graphtalker.GraphTalkerClient

  property url

    Return the server’s URL.

  property version

    Return the server’s version as a string.

  property versionTuple

    Return the version number as a tuple of integers.

    All non-digit characters from the version string are ignored and act only as separators. All trailing zeros are skipped. This is compatible with the way in which the Java client parses and compares AG version strings.

class franz.openrdf.sail.allegrographserver.Catalog(name, server, client)

  Bases: `object`

  Container of multiple repositories (triple stores).

  __init__(name, server, client)
  createRepository(name, indices=None, vector_store=False, embedder='', api_key='', model='', dimensions=None, compact_embeddings=False)

    Creates a new repository with the given name.

    Parameters:

      - name (string) – Repository name.

      - indices (list[string]) – If provided, creates a store with the given indices. (e.g. `["spogi, "gspoi", ...]`)

      - vector_store (boolean) – true to create vector store

      - embedder (string) – name of the embedder if vector store

      - api_key (string) – api key if required and vector store

      - dimensions (integer) – size of embedding if vector store

      - compact_embeddings (boolean) – convert to smaller embeddings

    Returns:

      A repository object.

    Return type:

      Repository

  deleteRepository(name)

    Delete a repository. :param name: Repository name. :type name: string

  getName()

    Return the catalog name.

  getRepository(name, access_verb)

    Creates or opens a repository.

    Parameters:

      - name (string) – Repository name.

      - access_verb –

        Determines mode of operation. Possible values are:

        - Repository.RENEW clears the contents of an existing

            repository before opening. If the indicated repository does not exist, it creates one.

        - Repository.OPEN opens an existing repository, or throws an exception if the repository is not found.

        - Repository.ACCESS opens an existing repository, or creates a new one if the repository is not found.

        - Repository.CREATE creates a new repository, or throws an exception if one by that name already exists.

    Returns:

      A repository object.

    Return type:

      Repository

  listRepositories()

    Return a list of names of repositories (triple stores) managed by this catalog.

  property name

    Return the catalog name.

## franz.openrdf.sail.spec module

Helper functions for creating session specification strings. See `openSession()`

franz.openrdf.sail.spec.federate(*stores)

  Create a session spec for connecting to a federated store.

  Parameters:

    stores (tuple[string]) – List of session specs to federate.

  Returns:

    A session spec string.

  Return type:

    string

franz.openrdf.sail.spec.graphFilter(store, graphs)

  Create a graph-filtered session spec.

  Parameters:

    - store (string) – Base session spec.

    - graphs (list[string]) – List of graph names. None means the default graph.

  Returns:

    A session spec string.

  Return type:

    string

franz.openrdf.sail.spec.local(name, catalog=None)

  Create a session spec for connecting to a store on the local server.

  Parameters:

    - name (string) – Store name.

    - catalog (string) – Catalog name (None = root catalog).

  Returns:

    A session spec string.

  Return type:

    string

franz.openrdf.sail.spec.reason(store, reasoner='rdfs++')

  Create a session spec that adds reasoning support to another session.

  Parameters:

    - store (string) – Base session spec.

    - reasoner (string) – Reasoning type (e.g. “rdfs++”`or `”restriction”).

  Returns:

    A session spec string.

  Return type:

    string

franz.openrdf.sail.spec.remote(name, catalog=None, host='localhost', port=None, protocol='http')

  Create a session spec for connecting to a store on another server.

  Parameters:

    - name (string) – Store name.

    - catalog (string) – Catalog name (None = root catalog).

    - host (string) – Remote host address.

    - port (int) – Port number on the remote host (default: 10035 for http, 10036 for https).

    - protocol (string) – Protocol - “http” or “https”, the default is “http”.

  Returns:

    A session spec string.

  Return type:

    string

franz.openrdf.sail.spec.url(url)

  Create a session spec for connecting to a remote store with known URL. :param url: Remote store’s address. :type url: string :return: A session spec string. :rtype: string

## Module contents