### Install Dependencies and Start Auto Build

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

Install necessary dependencies for documentation building and start the live HTML build process. This makes docs available locally.

```shell
pip install -e ".[docs]"
cd docs
make livehtml
```

--------------------------------

### MappingFile Examples

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/content.html

Examples of initializing MappingFile with different file extensions.

```python
MappingFile('data.sms')
MappingFile('data.sms2')
MappingFile('data.rq')
MappingFile('data.r2rml')
```

--------------------------------

### Start a single-node Stardog instance

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

Use Docker Compose to bring up a single-node Stardog instance with virtual graphs for testing. This is the recommended setup for most pystardog features.

```shell
# Bring a single node instance plus a bunch of Virtual Graphs for testing (Recommended).
docker-compose -f docker-compose.single-node.yml up -d
```

--------------------------------

### Start a cluster Stardog instance

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

Use Docker Compose to bring up a Stardog cluster setup. This is useful if you are implementing or testing cluster-specific features.

```shell
# A cluster setup is also provided, if cluster only features are to be implemented and tested.
docker-compose -f docker-compose.cluster.yml up -d
```

--------------------------------

### Install pystardog

Source: https://pystardog.readthedocs.io/en/latest/getting-started.html

Install the pystardog library using pip. For Stardog Cloud functionality, install with the 'cloud' extra.

```bash
pip install pystardog
```

```bash
pip install pystardog[cloud]
```

--------------------------------

### Example Output of 'make livehtml'

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

This is an example of the console output when running the 'make livehtml' command, showing the Sphinx build process and server startup.

```text
❯ make livehtml
sphinx-autobuild "." "_build"   --watch ../stardog/
[sphinx-autobuild] > sphinx-build /Users/frodo/projects/pystardog/docs /Users/frodo/projects/pystardog/docs/_build
Running Sphinx v6.2.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources...
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in _build.
[I 230710 15:26:18 server:335] Serving on http://127.0.0.1:8000
[I 230710 15:26:18 handlers:62] Start watching changes
[I 230710 15:26:18 handlers:64] Start detecting changes
```

--------------------------------

### GraphQL Query Examples

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Examples demonstrating how to execute GraphQL queries with Stardog, including options for schema and reasoning, and named variables.

```APIDOC
## Query with Schema and Reasoning

### Description
Executes a GraphQL query specifying a schema and enabling reasoning.

### Method
`gql.query`

### Parameters
- `query` (str): The GraphQL query string.
- `variables` (dict): A dictionary of variables, including `@reasoning` and `@schema`.

### Request Example
```python
gql.query('{ Person {name} }',
            variables={'@reasoning': True, '@schema': 'people'})
```

## Query with Named Variables

### Description
Executes a GraphQL query using named variables for parameterization.

### Method
`gql.query`

### Parameters
- `query` (str): The GraphQL query string with named variables.
- `variables` (dict): A dictionary mapping variable names to their values.

### Request Example
```python
gql.query(
      'query getPerson($id: Int) { Person(id: $id) {name} }',
      variables={'id': 1000})
```
```

--------------------------------

### Install pystardog with Cloud Dependencies

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.cloud.html

Install pystardog with the cloud optional dependencies to enable Stardog Cloud functionality.

```bash
pip install pystardog[cloud]
```

--------------------------------

### Install pystardog in development mode

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

Install the package in development mode with all necessary dependencies, including development-specific ones, after creating and activating a virtual environment.

```shell
# Create a virtual environment and activate it
python -m venv venv
source venv/bin/activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"
```

--------------------------------

### Install pystardog

Source: https://pystardog.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Install the base pystardog package using pip.

```shell
pip install pystardog
```

--------------------------------

### Install pystardog with Cloud Support

Source: https://pystardog.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Install pystardog with the extra dependencies for Stardog Cloud functionality.

```shell
pip install pystardog[cloud]
```

--------------------------------

### Get All Database Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves all metadata options for a database. Use to get a complete overview of a database's configuration.

```python
r = self.client.get(self.path + "/options")
        return r.json()
```

--------------------------------

### Get All Metadata Properties

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves information about all database metadata properties, including their descriptions and example values.

```python
admin.get_all_metadata_properties()
```

--------------------------------

### Get DataSource Details

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Lists all DataSources with their detailed information.

```python
admin.datasources_info()
```

--------------------------------

### Get All Metadata Properties

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves information on all database metadata properties, including their descriptions and example values.

```APIDOC
## get_all_metadata_properties

### Description
Get information on all database metadata properties, including description and example values.

### Method
GET

### Endpoint
/admin/config_properties

### Response
#### Success Response (200)
- **metadata_properties** (dict) - A dictionary containing metadata properties and their details.
```

--------------------------------

### Build and Publish Pystardog Package

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

Commands to install build dependencies, build the package, and upload it to PyPI. Requires authentication for uploading.

```shell
# Install build dependencies
pip install -e ".[build]"

# Build the package
python -m build

# Upload to PyPI (requires authentication)
twine upload dist/*
```

--------------------------------

### Get All Database Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves all metadata options for a specific database.

```APIDOC
## GET /admin/databases/{name}/options

### Description
Get the value of every metadata option for a database.

### Method
GET

### Endpoint
/admin/databases/{name}/options

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the database

### Response
#### Success Response (200)
- Returns a dictionary containing all database metadata.
```

--------------------------------

### get

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/connection.html

Gets a document from the store by its name. Supports streaming the document content.

```APIDOC
## get

### Description
Gets a document from the store.

### Method
GET

### Endpoint
/docs/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Name of the document.
#### Query Parameters
- **stream** (boolean) - Optional - If document should be streamed back as chunks of bytes or as one string. Defaults to False.
- **chunk_size** (integer) - Optional - Number of bytes to read per chunk when streaming. Defaults to 10240.

### Response
#### Success Response (200)
- **response** (string or Iterator[bytes]) - Contents of the document. Returns as a string if stream=False, or an iterable yielding bytes chunks if stream=True.

### Examples
No streaming:
```python
contents = docs.get('example')
```

Streaming:
(Example not provided in source)
```

--------------------------------

### Build documentation locally with Sphinx

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

Build the project's documentation locally using Sphinx. This requires installing the documentation dependencies and navigating to the docs directory.

```shell
pip install -e ".[docs]"
cd docs
make html
```

--------------------------------

### Import a MySQL Virtual Graph into Stardog

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

This example demonstrates importing a MySQL virtual graph into a Stardog database. It specifies the database name, mapping file, target named graph, and options for the virtual graph. The target named graph's contents will be cleared before import.

```python
admin.import_virtual_graph(
      'db-name',
      mappings=File('mappings.ttl'),
      named_graph='my-graph',
      remove_all=True,
      options={'jdbc.driver': 'com.mysql.jdbc.Driver'}
)
```

--------------------------------

### Get Data Source Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the current configuration options for a Stardog data source. The options are returned as a list of dictionaries.

```python
r = self.client.get(self.path + "/options")
return r.json()["options"]
```

--------------------------------

### Get Virtual Graph Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the configuration options for a specific virtual graph.

```python
vg.options()

```

--------------------------------

### Start Read-Only Mode

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Enables read-only mode for the Stardog cluster.

```python
admin.cluster_start_readonly()
```

--------------------------------

### AsyncClient Initialization and Usage

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/cloud/client.html

Demonstrates how to initialize and use the asynchronous Stardog Cloud client, either with a context manager or explicit closing.

```APIDOC
## AsyncClient

An asynchronous client for interacting with the Stardog Cloud API.

### Usage with Context Manager

```python
async with stardog.cloud.AsyncClient() as client:
    voicebox = client.voicebox_app(app_api_token="my-secret-token", client_id="some-id")
    answer = await voicebox.async_ask(question="Who produced the most cars in 2023?")
```

### Usage with Explicit Closing

**Note:** This is needed to avoid resource leaks. There is no need to call `aclose()` if you are using a context-managed client.

```python
client = stardog.cloud.AsyncClient()
# ... do stuff ...
await client.aclose()
```

### Initialization Parameters

- `base_url` (str): The base URL of the Stardog Cloud API. Defaults to `StardogCloudAPIEndpoints.US.value`.
- `timeout` (Optional[float]): Request timeout in seconds. Defaults to 30s if not provided.
```

--------------------------------

### Get Voicebox Application Settings (Async)

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/cloud/voicebox.html

Asynchronously retrieves the current Voicebox application settings. This is the async version of the `settings` method and requires similar authentication parameters.

```python
async def async_settings(self) -> VoiceboxAppSettings:
        """
        .. note::
            Async version of :obj:`stardog.cloud.voicebox.VoiceboxApp.settings`

        Returns the Voicebox application information registered with the ``app_api_token``

        """

        # API requires a client id in header but doesn't actually do anything
        headers = self._create_headers(
            self.app_api_token, self.client_id or "pystardog"
        )

        response = await self._ensure_response(
            self.client._get(
                path="/v1/app",
                headers=headers,
            )
        )
        data = response.json()
        return VoiceboxAppSettings(
            name=data.get("name", ""),
            database=data.get("database", ""),
            model=data.get("model", ""),
            named_graphs=data.get("named_graphs", []),
            reasoning=data.get("reasoning", False),
        )
```

--------------------------------

### Synchronous Client Initialization and Usage

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/cloud/client.html

Demonstrates how to initialize and use the synchronous Stardog Cloud client, either as a context manager or by explicitly closing it.

```APIDOC
## Client Initialization

### Description
Initializes a synchronous client for interacting with the Stardog Cloud API.

### Parameters
- **base_url** (str) - Optional - The base URL of the Stardog Cloud API. Defaults to `https://cloud.stardog.com/api`.
- **timeout** (Optional[float]) - Optional - Request timeout in seconds. Defaults to 30.0 seconds.

### Usage with Context Manager
```python
import stardog.cloud

with stardog.cloud.Client() as client:
    voicebox = client.voicebox_app(app_api_token="my-secret-token", client_id="some-id")
    answer = voicebox.ask(question="Who produced the most cars in 2023?")
```

### Usage with Explicit Close
```python
import stardog.cloud

client = stardog.cloud.Client()
try:
    # ... do stuff with the client ...
    voicebox = client.voicebox_app(app_api_token="my-secret-token", client_id="some-id")
    answer = voicebox.ask(question="Who produced the most cars in 2023?")
finally:
    client.close() # Important to avoid resource leaks
```

### Closing the Client

#### Description
Closes the underlying HTTP transport and proxies. This method should be called if the client instance is not being used as a context manager to prevent resource leaks.

#### Method
`close()`

#### Parameters
None
```

--------------------------------

### Connect to Stardog Server and Manage Database

Source: https://pystardog.readthedocs.io/en/latest/_sources/getting-started.rst.txt

Connect to a Stardog server instance, create a new database, add data from a file, execute a SPARQL query, and then drop the database. Ensure you have a Stardog server running locally on the default port.

```python
import stardog

conn_details = {
  'endpoint': 'http://localhost:5820',
  'username': 'admin',
  'password': 'admin'
}

with stardog.Admin(**conn_details) as admin:
  db = admin.new_database('db')

  with stardog.Connection('db', **conn_details) as conn:
    conn.begin()
    conn.add(stardog.content.File('./test/data/example.ttl'))
    conn.commit()
    results = conn.select('select * { ?a ?p ?o }')

  db.drop()
```

--------------------------------

### Get Document from Store (No Streaming)

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/connection.html

Retrieves a document from the store by its name. The document content is returned as a single string.

```python
def get(
        self, name: str, stream: bool = False, chunk_size: int = 10240
    ) -> Union[str, Iterator[bytes]]:
        """Gets a document from the store.

        :param name: Name of the document
        :param stream: If document should be streamed back as chunks of bytes or as one string .
        :param chunk_size: Number of bytes to read per chunk when streaming.

        .. note::
            If ``stream=False``, the contents of the document will be returned as a ``str``. If ``stream=True``, an iterable that yields chunks of content as ``bytes`` will be returned.

        Examples:
          No streaming

          >>> contents = docs.get('example')

          Streaming

          
```

--------------------------------

### Synchronous Client Usage (Context Manager)

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/cloud/client.html

Demonstrates how to use the synchronous Stardog Cloud client within a context manager for automatic resource management. This is the recommended approach.

```python
with stardog.cloud.Client() as client:
    voicebox = client.voicebox_app(app_api_token="my-secret-token", client_id="some-id")
    answer = voicebox.ask(question="Who produced the most cars in 2023?")
```

--------------------------------

### Voicebox App - Synchronous Ask

Source: https://pystardog.readthedocs.io/en/latest/_sources/source/stardog.cloud.rst.txt

Demonstrates how to use the synchronous 'ask' method of the VoiceboxApp to get a response from Stardog Voicebox.

```APIDOC
## Voicebox App - Synchronous Ask

### Description
This method allows for synchronous interaction with Stardog Voicebox to ask questions and receive answers.

### Method
`ask`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **question** (string) - Required - The question to ask Stardog Voicebox.

### Request Example
```python
from stardog.cloud.client import Client

with Client() as client:
    app = client.voicebox_app(app_api_token="your-token", client_id="your-client-id")
    response = app.ask(question="Your question here")
```

### Response
#### Success Response (200)
- **content** (string) - The answer content from Voicebox.
- **pending** (boolean) - Indicates if more answers are coming.

#### Response Example
```json
{
  "content": "The answer to your question.",
  "pending": false
}
```
```

--------------------------------

### begin

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Begins a transaction in the Stardog database.

```APIDOC
## begin

### Description
Begins a transaction.

### Parameters
#### Query Parameters
- **reasoning** (bool) - Optional - Enable reasoning for all queries inside the transaction. If the transaction does not have reasoning enabled, queries within will not be able to use reasoning.
```

--------------------------------

### Get Specific Database Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the values of specified metadata options for a database. Use to query specific database settings.

```python
# transform into {'option': None} dict
        meta = dict([(x, None) for x in options])

        r = self.client.put(self.path + "/options", json=meta)
        return r.json()
```

--------------------------------

### Create New Database with Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Creates a new database with specified options. Use this to configure database settings like search enablement during creation.

```python
admin.new_database('db', {'search.enabled': True})
```

--------------------------------

### Get Virtual Graph Mappings by Syntax

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Retrieve the mappings for a virtual graph in a specified syntax (STARDOG, R2RML, or SMS2). This is the preferred method over `mappings()`.

```python
>>> mappings = virtual_graph.mappings_string(syntax='SMS')
```

--------------------------------

### Get Namespaces

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the namespaces stored in the database. Returns a list of dictionaries, each containing a namespace prefix and its corresponding IRI. Performed via HTTP GET to /{database_name}/namespaces.

```APIDOC
## GET /{database_name}/namespaces

### Description
Retrieve the namespaces stored in the database.

### Method
GET

### Endpoint
/{database_name}/namespaces

### Return
- **list[dict]**: A list of dictionaries, each containing a namespace prefix and its corresponding IRI.

### Response
#### Success Response (200)
- **namespaces** (list[dict]) - A list of namespace mappings.
```

--------------------------------

### get()

Source: https://pystardog.readthedocs.io/en/latest/genindex.html

Retrieves data from the Docs connection.

```APIDOC
## get()

### Description
Retrieves data from the Docs connection.

### Method
(Method details not specified in source)

### Endpoint
(Endpoint details not specified in source)

### Parameters
(Parameter details not specified in source)

### Request Example
(Request example not specified in source)

### Response
(Response details not specified in source)

### Response Example
(Response example not specified in source)
```

--------------------------------

### get_server_properties

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Get the value of any set server-level properties.

```APIDOC
## get_server_properties

### Description
Get the value of any set server-level properties.

### Method
GET

### Endpoint
/admin/properties
```

--------------------------------

### Instantiate SelectQueryResult and Print

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/results.html

Demonstrates how to create a SelectQueryResult object from a connection's select query and print its summary, including variables and a preview of results.

```python
>>> results = SelectQueryResult(conn.select('select * {?s ?p ?o} limit 10'))
>>> print(results)
SelectQueryResult with 10 results
Variables: s, p, o
Preview of the first 3 results:
?s = http://stardog.com/tutorial/%22Heroes%22_(David_Bowie_album), ?p = http://www.w3.org/1999/02/22-rdf-syntax-ns#type, ?o = http://stardog.com/tutorial/Album
?s = http://stardog.com/tutorial/artist, ?p = http://www.w3.org/2000/01/rdf-schema#domain, ?o = http://stardog.com/tutorial/Album
?s = http://stardog.com/tutorial/date, ?p = http://www.w3.org/2000/01/rdf-schema#domain, ?o = http://stardog.com/tutorial/Album
...and 7 more rows.
```

--------------------------------

### Get Role

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves a specific role by its name.

```APIDOC
## GET /admin/roles/{name}

### Description
Retrieves a specific role by its name.

### Method
GET

### Endpoint
/admin/roles/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the role to retrieve.

### Response
#### Success Response (200)
- **Role object** - The requested Role object.

### Response Example
```json
{
  "rolename": "admin"
}
```
```

--------------------------------

### Get User Permissions

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves all permissions granted to a user.

```APIDOC
## GET /admin/permissions/user/{username}

### Description
Gets the permissions for the specified user.

### Method
GET

### Endpoint
/admin/permissions/user/{username}

### Response
#### Success Response (200)
- **permissions** (object) - An object detailing the user's permissions.
```

--------------------------------

### Client Initialization

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/cloud/client.html

Initializes a synchronous Stardog Cloud client. Allows specifying a custom base URL and request timeout.

```python
def __init__(
    self,
    base_url: str = StardogCloudAPIEndpoints.US.value,
    timeout: Optional[float] = None,
):
    """
    :param base_url: The base URL of the Stardog Cloud API.
    :param timeout: Request timeout in seconds.
    """
    self._base_url = base_url
    self._timeout = timeout
    self._client = httpx.Client(
        base_url=base_url,
        timeout=timeout if timeout is not None else self._DEFAULT_TIMEOUT,
    )
```

--------------------------------

### Get User Roles

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves all roles assigned to a user.

```APIDOC
## GET /admin/users/{username}/roles

### Description
Gets all the roles assigned to the specified user.

### Method
GET

### Endpoint
/admin/users/{username}/roles

### Response
#### Success Response (200)
- **roles** (array of strings) - A list of role names assigned to the user.
```

--------------------------------

### Admin Initialization

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Initializes an admin connection to a Stardog server with specified credentials and endpoint.

```APIDOC
## Admin

### Description
Initializes an admin connection to a Stardog server.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
`__init__(_endpoint ='http://localhost:5820'_, _username ='admin'_, _password ='admin'_, _auth =None_, _run_as =None_)

### Parameters
- **endpoint** (`Optional[str]`) - URL of the Stardog server endpoint.
- **username** (`Optional[str]`) - Username to use in the connection.
- **password** (`Optional[str]`) - Password to use in the connection.
- **auth** (`Optional[AuthBase]`) - `requests.auth.AuthBase` object. Used as an alternative authentication scheme. If not provided, HTTP Basic auth will be attempted with the `username` and `password`.
- **run_as** (`Optional[str]`) - the user to impersonate

### Notes
`auth` and `username`/`password` should not be used together. If they are, the value of `auth` will take precedent.

### Example
```python
admin = Admin(endpoint='http://localhost:9999',
              username='admin', password='admin')
```
```

--------------------------------

### Get User Roles

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves all roles assigned to a user.

```python
def roles(self) -> list["Role"]:
        """Gets all the User's roles."""
        r = self.client.get(self.path + "/roles")
        roles = r.json()["roles"]
        return list(map(lambda name: Role(name, self.client), roles))
```

--------------------------------

### Get All Cached Graphs

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves a list of all cached graphs.

```APIDOC
## Get All Cached Graphs

### Description
Retrieves a list of all cached graphs currently stored in Stardog.

### Method
GET

### Endpoint
/admin/cache/graphs

### Response
#### Success Response (200)
- **graphs** (list[Cache]) - A list of Cache objects representing the cached graphs.

```

--------------------------------

### settings()

Source: https://pystardog.readthedocs.io/en/latest/genindex.html

Retrieves settings for a Voicebox application in Stardog Cloud.

```APIDOC
## settings()

### Description
Retrieves the current settings for a specific Voicebox application within Stardog Cloud.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)

### Parameters
None

### Request Example
```python
app_settings = voicebox_app.settings()
```

### Response
Returns a dictionary or object containing the Voicebox application settings.
```

--------------------------------

### Get User Permissions

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves all explicit permissions granted to a user.

```python
def permissions(self) -> dict:
        """Gets the user permissions.

        See Also:
            `Stardog Docs - Permissions <https://docs.stardog.com/operating-stardog/security/security-model#permissions>`_

        :return: user permissions
        """
        r = self.client.get("/admin/permissions/user/{}".format(self.name))
        return r.json()["permissions"]
```

--------------------------------

### Create New Database

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Creates a new database with optional configurations and initial content.

```APIDOC
## New Database

### Description
Creates a new database.

### Method
`new_database`

### Parameters
- **name** (str) - the database name
- **options** (Optional[dict]) - Dictionary with database options
- **contents** (Union[Content, Tuple[Content, str], None]) - Datasets to perform bulk-load with. Named graphs are made with tuples of Content and the name.
- **copy_to_server** (bool) - If ``True``, sends the files to the Stardog server; if running as a cluster, data will be replicated to all nodes in the cluster.

### Examples

Options

    >>> admin.new_database('db', {'search.enabled': True})

bulk-load

    >>> admin.new_database('db', {},
                           File('example.ttl'), File('test.rdf'))

bulk-load to named graph

    >>> admin.new_database('db', {},
                           (File('example.ttl'), 'my_named_graph'))
```

--------------------------------

### new_user

Source: https://pystardog.readthedocs.io/en/latest/genindex.html

Creates a new user.

```APIDOC
## new_user()

### Description
Creates a new user.

### Method
(Implicitly a method call on an Admin object)

### Endpoint
(Not applicable for SDK method)

### Parameters
(No parameters explicitly documented)

### Request Example
```python
from stardog.admin import Admin

admin = Admin()
admin.new_user()
```

### Response
(No response details explicitly documented)
```

--------------------------------

### Get Cache Status

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the status of one or more cached graphs.

```APIDOC
## Get Cache Status

### Description
Retrieves the status of one or more specified cached graphs.

### Method
POST

### Endpoint
/admin/cache/status

### Parameters
#### Request Body
- **names** (list[string]) - Required - Names of the cached graphs to retrieve status for.

### Response
#### Success Response (200)
- **statuses** (list[dict]) - A list of statuses for the requested cached graphs.

```

--------------------------------

### Initialize File Content

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/content.html

Use File to load content from a file. The content type, encoding, and name are automatically detected from the filename.

```python
File('data.ttl')
File('data.doc', 'application/msword')
```

--------------------------------

### Get Cluster Info

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves information about the nodes in the Stardog cluster.

```APIDOC
## Get Cluster Info

### Description
Retrieves information about the nodes in the Stardog cluster.

### Method
GET

### Endpoint
/admin/cluster

### Response
#### Success Response (200)
- **info** (dict) - Information about nodes in the cluster.

```

--------------------------------

### Initialize Stardog Connection

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/connection.html

Establishes a connection to a Stardog database. Requires database name and optionally accepts endpoint, username, and password. Can also use custom authentication or a pre-existing session.

```python
conn = Connection('db', endpoint='http://localhost:9999',
                                username='admin', password='admin')
```

--------------------------------

### Get Cluster Status

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the status information for each node in the cluster.

```APIDOC
## Get Cluster Status

### Description
Retrieves status information for each node in the Stardog cluster.

### Method
GET

### Endpoint
/admin/cluster/status

### Response
#### Success Response (200)
- **status** (dict) - Status information about each node in the cluster.

```

--------------------------------

### Create New Database with Bulk Load

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Use this to create a new database and bulk-load data from multiple files.

```python
>>> admin.new_database('db', {},
                       File('example.ttl'), File('test.rdf'))
```

--------------------------------

### Connect to Stardog Server and Manage Databases

Source: https://pystardog.readthedocs.io/en/latest/getting-started.html

Connect to a local or remote Stardog server instance to create, manage, and query databases. Requires connection details like endpoint, username, and password.

```python
import stardog

conn_details = {
  'endpoint': 'http://localhost:5820',
  'username': 'admin',
  'password': 'admin'
}

with stardog.Admin(**conn_details) as admin:
  db = admin.new_database('db')

  with stardog.Connection('db', **conn_details) as conn:
    conn.begin()
    conn.add(stardog.content.File('./test/data/example.ttl'))
    conn.commit()
    results = conn.select('select * { ?a ?p ?o }')

  db.drop()
```

--------------------------------

### Get Server Properties

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the values of any set server-level properties.

```APIDOC
## GET /admin/properties

### Description
Get the value of any set server-level properties.

### Method
GET

### Endpoint
/admin/properties

### Response
#### Success Response (200)
- **server_properties** (dict) - Server properties.
```

--------------------------------

### Initialize Admin Connection

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Initializes an admin connection to a Stardog server. Use this to establish a connection for administrative tasks.

```python
admin = Admin(endpoint='http://localhost:9999',
                    username='admin', password='admin')
```

--------------------------------

### Get Virtual Graph

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves a specific virtual graph by its name.

```APIDOC
## GET /admin/virtual_graphs/{name}

### Description
Retrieves a specific virtual graph by its name.

### Method
GET

### Endpoint
/admin/virtual_graphs/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the virtual graph to retrieve.

### Response
#### Success Response (200)
- **VirtualGraph object** - The requested VirtualGraph object.

### Response Example
```json
{
  "name": "my_virtual_graph"
}
```
```

--------------------------------

### Create New Database with Bulk Load

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Creates a new database and performs a bulk load with specified content files. Use this for initial data loading.

```python
admin.new_database('db', {},
                                   File('example.ttl'), File('test.rdf'))
```

--------------------------------

### Get User

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves a User object based on the provided username.

```APIDOC
## GET /admin/users/{name}

### Description
Retrieves a User object.

### Method
GET

### Endpoint
/admin/users/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the user
```

--------------------------------

### new_database

Source: https://pystardog.readthedocs.io/en/latest/genindex.html

Creates a new database.

```APIDOC
## new_database()

### Description
Creates a new database.

### Method
(Implicitly a method call on an Admin object)

### Endpoint
(Not applicable for SDK method)

### Parameters
(No parameters explicitly documented)

### Request Example
```python
from stardog.admin import Admin

admin = Admin()
admin.new_database()
```

### Response
(No response details explicitly documented)
```

--------------------------------

### Get Stored Query

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves a specific stored query by its name.

```APIDOC
## GET /admin/queries/stored/{name}

### Description
Retrieves a Stored Query.

### Method
GET

### Endpoint
/admin/queries/stored/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the stored query to retrieve
```

--------------------------------

### Synchronous Client Usage (Explicit Close)

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/cloud/client.html

Shows how to instantiate and use the synchronous Stardog Cloud client explicitly, requiring manual closing to prevent resource leaks. Use this if not employing a context manager.

```python
client = stardog.cloud.Client()
...do stuff
client.close()
```

--------------------------------

### Get Database Object

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves an object representing a specific database.

```APIDOC
## Get Database

### Description
Retrieves an object representing a database.

### Method
`database`

### Parameters
- **name** (str) - The database name

### Response
- **database** (Database) - The database object.
```

--------------------------------

### Create MappingFile Object

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Instantiate a MappingFile object by providing the file path. The syntax can be inferred from the file extension or explicitly set.

```python
>>> MappingFile('data.sms')
>>> MappingFile('data.sms2')
>>> MappingFile('data.rq')
>>> MappingFile('data.r2rml')
```

--------------------------------

### Get Prometheus Metrics

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves Prometheus metrics from the Stardog server.

```APIDOC
## Get Prometheus Metrics

### Description
Returns Prometheus metrics from the registry.

### Method
`get_prometheus_metrics`

### Endpoint
`/admin/status/prometheus`

### Method
GET

### Parameters
None

### Response
#### Success Response (200)
- **metrics** (str) - Prometheus metrics in text format.
```

--------------------------------

### Get Schema

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/connection.html

Retrieves the content of a specific GraphQL schema from the database.

```APIDOC
## GET /graphql/schemas/{name}

### Description
Retrieves the content of a specific GraphQL schema.

### Method
GET

### Endpoint
/graphql/schemas/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the schema to retrieve.

### Response
#### Success Response (200)
- **text** (string) - The GraphQL schema content.
```

--------------------------------

### get_all_options()

Source: https://pystardog.readthedocs.io/en/latest/genindex.html

Retrieves all options for a database.

```APIDOC
## get_all_options()

### Description
Retrieves all options for a database.

### Method
(Method details not specified in source)

### Endpoint
(Endpoint details not specified in source)

### Parameters
(Parameter details not specified in source)

### Request Example
(Request example not specified in source)

### Response
(Response details not specified in source)

### Response Example
(Response example not specified in source)
```

--------------------------------

### new_user

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Creates a new user with a username, password, and optional superuser status.

```APIDOC
## new_user

### Description
Creates a new user.

### Parameters
#### Path Parameters
* **username** (str) - Required - The username
* **password** (str) - Required - The password
* **superuser** (bool) - Optional - Create the user as a superuser. Only superusers can make other superusers.

### Return type
`User`

### Returns
The new User object
```

--------------------------------

### Start Read Only Mode

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Enables read-only mode for the Stardog cluster.

```APIDOC
## Start Read Only Mode

### Description
Starts read-only mode for the entire Stardog cluster.

### Method
PUT

### Endpoint
/admin/cluster/readonly

```

--------------------------------

### BindingSet.__init__

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/results.html

Initializes a BindingSet object with raw bindings from a SPARQL query result.

```APIDOC
## BindingSet.__init__ 

### Description
Initializes a BindingSet object. It takes a dictionary of raw bindings and converts them to rdflib equivalents.

### Parameters
#### Request Body
- **bindings** (Dict[str, RDFTerm]) - Required - A dictionary mapping variable names to their RDFTerm values.
```

--------------------------------

### Get Cache Status

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Retrieves the status of one or more specified cached graphs.

```python
admin.cache_status('graph1', 'graph2')
```

--------------------------------

### Get All Cached Graphs Status

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the status of all cached graphs in the system.

```APIDOC
## Get All Cached Graphs Status

### Description
Retrieves the status for all cached graphs currently in the Stardog system.

### Method
GET

### Endpoint
/admin/cache/status

### Response
#### Success Response (200)
- **caches** (list[Cache]) - A list of Cache objects representing all cached graphs.

```

--------------------------------

### Retrieve Cache Object

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Gets an object representing a specific cached dataset.

```APIDOC
## Retrieve Cache Object

### Description
Retrieves an object representing a cached dataset by its name.

### Method
GET

### Endpoint
/admin/cache/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the cache to retrieve.

```

--------------------------------

### Async Client Context Manager Usage

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/cloud/client.html

Demonstrates how to use the AsyncClient as an asynchronous context manager for automatic resource management. This is the recommended approach to avoid resource leaks.

```python
>>> async with stardog.cloud.AsyncClient() as client:
>>>     voicebox = client.voicebox_app(app_api_token="my-secret-token", client_id="some-id")
>>>     answer = await voicebox.async_ask(question="Who produced the most cars in 2023?")
```

--------------------------------

### Get Server Metrics

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Returns metric information from the registry in JSON format.

```APIDOC
## Get Server Metrics

### Description
Returns metric information from the registry in JSON format.

### Method
`get_server_metrics`

### Endpoint
`/admin/status`

### Method
GET

### Parameters
None

### Response
#### Success Response (200)
- **metrics** (dict) - Server metrics in JSON format.

See Also:
    `HTTP API - Server metrics <https://stardog-union.github.io/http-docs/#operation/status>`_
```

--------------------------------

### Run the basic test suite

Source: https://pystardog.readthedocs.io/en/latest/_sources/contributing.rst.txt

Execute the core test suite using pytest, which covers most of pystardog's functionalities. The '-s' flag allows print statements to be shown.

```shell
# Run the basic test suite (covers most of the pystardog functionalities)
pytest test/test_admin_basic.py test/test_connection.py test/test_utils.py -s
```

--------------------------------

### Get Cluster Status

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Retrieves and prints status information for each node in the Stardog cluster.

```python
admin.cluster_status()
```

--------------------------------

### Create a New User - Stardog Admin

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Creates a new user account on the Stardog server with a specified username, password, and optional superuser status. Superusers have elevated privileges.

```python
def new_user(self, username: str, password: str, superuser: bool = False) -> "User":
    """Creates a new user.

    :param username: The username
    :param password: The password
    :param superuser: Create the user as a superuser. Only superusers can make other superusers.

```

--------------------------------

### Get Cluster Information

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Retrieves and prints information about all nodes within the Stardog cluster.

```python
admin.cluster_info()
```

--------------------------------

### Get Virtual Graph Database

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the name of the database associated with the virtual graph.

```python
vg.get_database()

```

--------------------------------

### Create New Database with Named Graph Bulk Load

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Use this to create a new database and bulk-load data into a specific named graph.

```python
>>> admin.new_database('db', {}, (File('test.rdf'), 'urn:context'))
```

--------------------------------

### Backup All Databases

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Creates a backup of all databases on the Stardog server. Optionally specify a location on the server's file system to store the backup.

```python
admin.backup_all()
```

```python
admin.backup_all(location="/path/to/backup/location")
```

--------------------------------

### Get Database Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the values of specific metadata options for a given database.

```APIDOC
## PUT /admin/databases/{name}/options

### Description
Get the value of specific metadata options for a database.

### Method
PUT

### Endpoint
/admin/databases/{name}/options

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the database

#### Request Body
- **options** (dict) - Required - A dictionary where keys are option names and values are typically null for retrieval.
```

--------------------------------

### List All DataSources

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Retrieves a list of all DataSources configured on the Stardog server.

```python
admin.datasources()
```

--------------------------------

### Connection Initialization

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/connection.html

Initializes a connection to a Stardog database. This is the primary entry point for all user-related operations.

```APIDOC
## Connection.__init__

### Description
Initializes a connection to a Stardog database.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **database** (str) - Required - Name of the database
- **endpoint** (Optional[str]) - Optional - URL of the Stardog server endpoint. Defaults to client.Client.DEFAULT_ENDPOINT.
- **username** (Optional[str]) - Optional - Username to use in the connection. Defaults to client.Client.DEFAULT_USERNAME.
- **password** (Optional[str]) - Optional - Password to use in the connection. Defaults to client.Client.DEFAULT_PASSWORD.
- **auth** (Optional[AuthBase]) - Optional - :class:`requests.auth.AuthBase` object. Used as an alternative authentication scheme. If not provided, HTTP Basic auth will be attempted with the ``username`` and ``password``.
- **session** (Optional[Session]) - Optional - :class:`requests.session.Session` object
- **run_as** (Optional[str]) - Optional - The user to impersonate.

### Request Example
```python
conn = Connection(
    'db',
    endpoint='http://localhost:9999',
    username='admin',
    password='admin'
)
```

### Response
None

### Response Example
None
```

--------------------------------

### Get All Cached Queries

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves a list of all cached queries. Deprecated in Stardog 8+.

```APIDOC
## Get All Cached Queries

### Description
Retrieves a list of all currently cached queries. This method is deprecated starting from Stardog version 8.

### Method
GET

### Endpoint
/admin/cache/queries

### Response
#### Success Response (200)
- **queries** (list[Cache]) - A list of Cache objects representing the cached queries.

```

--------------------------------

### Get All Running Queries

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves information about all currently running queries on the Stardog server.

```python
admin.queries()
```

--------------------------------

### Backup All Databases (Server Backup)

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Creates a backup of all databases on the Stardog server. The backup can be written to a specified location on the server's file system.

```APIDOC
## backup_all

### Description
Create a backup of all databases on the server. This is also known as a **server backup**.

### Method
PUT

### Endpoint
/admin/databases/backup_all

### Parameters
#### Query Parameters
- **location** (str) - Optional - Where to write the server backup to on the Stardog server's file system. Defaults to the directory specified by ``backup.dir`` in ``stardog.properties``.

### Request Example
```python
admin.backup_all()
admin.backup_all(location="/path/to/backup/location")
```
```

--------------------------------

### VirtualGraph.mappings

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Gets the Virtual Graph mappings in a specified content type. Deprecated in favor of mappings_string.

```APIDOC
## VirtualGraph.mappings

### Description
Gets the Virtual Graph mappings in the given content type. This method is deprecated.

### Method
GET

### Endpoint
/admin/virtual_graphs/{name}/mappings

### Parameters
#### Headers
- **Accept** (string) - Optional - Content type for mappings (e.g., `TURTLE`). Defaults to `TURTLE`.

### Response
#### Success Response (200)
- **mappings** (bytes) - The virtual graph mappings in the specified content type.

#### Response Example
```
# Mappings content in the specified content type
```
```

--------------------------------

### Create Server Backup

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Generates a backup of all databases on the Stardog server. By default, backups are stored in the `.backup` directory within `$STARDOG_HOME`. The backup location can be specified using the `location` parameter or the `backup.dir` property in `stardog.properties`.

```python
admin.backup_all(location='/path/to/backup')
```

--------------------------------

### set_options()

Source: https://pystardog.readthedocs.io/en/latest/genindex.html

Sets options for a Stardog database.

```APIDOC
## set_options()

### Description
Sets various options for a Stardog database.

### Method
N/A (Method call)

### Endpoint
N/A (Method call)

### Parameters
- **options** (dict) - A dictionary of options to set for the database.

### Request Example
```python
database.set_options({"reasoning.enabled": "true"})
```

### Response
None. Updates the database configuration.
```

--------------------------------

### Get Standby Node Pause Status

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves the current pause status of a standby node.

```APIDOC
## GET /admin/cluster/standby/pause

### Description
Get the pause status of a standby node.

### Method
GET

### Endpoint
/admin/cluster/standby/pause

### Response
#### Success Response (200)
- **pause_status** (string) - Pause status of a standby node, possible values are: ``WAITING``, ``SYNCING``, ``PAUSING``, ``PAUSED``.
```

--------------------------------

### Get Process Information

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves detailed information about a specific process running on the Stardog server.

```APIDOC
## GET /admin/processes/{id}

### Description
Gets information about a process.

### Method
GET

### Endpoint
/admin/processes/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Process ID

### Response
#### Success Response (200)
- **ProcessInfo** (object) - Process information
```

--------------------------------

### Get All Running Queries Information

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves information about all currently running queries on the Stardog server.

```APIDOC
## queries

### Description
Gets information about all running queries.

### Method
GET

### Endpoint
/admin/queries

### Response
#### Success Response (200)
- **queries** (list) - A list of dictionaries, where each dictionary contains information about a running query.
```

--------------------------------

### Get Running Query Information

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves information about a specific running query identified by its ID.

```APIDOC
## query

### Description
Gets information about a running query.

### Method
GET

### Endpoint
/admin/queries/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The ID of the query to retrieve information for.

### Response
#### Success Response (200)
- **query_info** (dict) - Information about the specified running query.
```

--------------------------------

### stardog.connection.explain

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Explains the evaluation of a SPARQL query.

```APIDOC
## explain

### Description
Explains the evaluation of a SPARQL query.

### Parameters
#### Path Parameters
- **query** (str) - Required - the SPARQL query to explain
- **base_uri** (Optional[str]) - Optional - base URI for the parsing of the `query`

### Returns
Query explanation (str)
```

--------------------------------

### Get Running Query Information

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves information about a specific running query using its ID.

```python
admin.query("query-id-123")
```

--------------------------------

### Begin Stardog Transaction

Source: https://pystardog.readthedocs.io/en/latest/source/stardog.html

Begins a transaction. Reasoning can be enabled for all queries within the transaction by setting the `reasoning` parameter to `True`.

```python
conn.begin()
```

--------------------------------

### Get Prometheus Metrics

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Retrieves Stardog server metrics in Prometheus format. This is useful for monitoring.

```python
admin.get_prometheus_metrics()
```

--------------------------------

### Run Tox Single-Node Tests

Source: https://pystardog.readthedocs.io/en/latest/contributing.html

Executes tests specifically for a single-node Stardog setup using Tox.

```bash
# Run single-node-specific tests
tox -e single_node
```

--------------------------------

### Set Database Options

Source: https://pystardog.readthedocs.io/en/latest/_modules/stardog/admin.html

Sets database options. Note that some options require the database to be offline.

```python
self.client.put(self.path + "/options", json=options)
```