.venv/lib/python3.12/site-packages/surrealdb/http.py

"""
Copyright © SurrealDB Ltd.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.

You may obtain a copy of the License at
    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
"""
from __future__ import annotations

import json
from dataclasses import dataclass
from types import TracebackType
from typing import Any, Dict, List, Optional, Type

import httpx

__all__ = ("SurrealHTTP",)


class SurrealException(Exception):
    """Base exception for SurrealDB client library."""


@dataclass(frozen=True)
class SurrealResponse:
    """Represents a http response from a SurrealDB server.

    Attributes:
        time: The time the request was processed.
        status: The status of the request.
        result: The result of the request.
    """

    time: str
    status: str
    result: List[Dict[str, Any]]


# ------------------------------------------------------------------------
# Surreal library methods - exposed to user


class SurrealHTTP:
    """Represents a http connection to a SurrealDB server.

    Args:
        url: The URL of the SurrealDB server.
        namespace: The namespace to use for the connection.
        database: The database to use for the connection.
        username: The username to use for the connection.
        password: The password to use for the connection.
    """

    def __init__(
        self,
        url: str,
        namespace: str,
        database: str,
        username: str,
        password: str,
    ) -> None:
        self._url = url
        self._namespace = namespace
        self._database = database
        self._username = username
        self._password = password

        self._http = httpx.AsyncClient(
            base_url=self._url,
            auth=httpx.BasicAuth(
                username=self._username,
                password=self._password,
            ),
            headers={
                "NS": self._namespace,
                "DB": self._database,
                "Accept": "application/json",
                "Content-Type": "application/json",
            },
        )

    async def __aenter__(self) -> SurrealHTTP:
        """Connect to the http client when entering the context manager."""
        await self.connect()
        return self

    async def __aexit__(
        self,
        exc_type: Optional[Type[BaseException]] = None,
        exc_value: Optional[BaseException] = None,
        traceback: Optional[TracebackType] = None,
    ) -> None:
        """Disconnect from the http client when exiting the context manager."""
        await self.close()

    async def connect(self) -> None:
        """Connect to a local or remote database endpoint."""
        await self._http.__aenter__()

    async def close(self) -> None:
        """Close the persistent connection to the database."""
        await self._http.aclose()

    async def _request(
        self,
        method: str,
        uri: str,
        data: Optional[str] = None,
        params: Optional[Any] = None,
    ) -> SurrealResponse:
        surreal_response = await self._http.request(
            method=method,
            url=uri,
            content=data,
            params=params,
        )
        surreal_data = await surreal_response.aread()
        return json.loads(surreal_data)

    # TODO add missing methods - currently undocumented
    # Missing method - wait
    # Missing method - use
    # Missing method - invalidate
    # Missing method - authenticate
    # Missing method - let
    # Missing method - merge
    # TODO fix signup and signin methods
    # TODO: Review type: ignore comments.

    async def signup(self, vars: Dict[str, Any]) -> str:
        """Sign this connection up to a specific authentication scope.

        Args:
            vars: Variables used in a signup query.

        Examples:
            await db.signup({"user": "bob", "pass": "123456"})
        """
        response = await self._request(
            method="POST", uri="/signup", data=json.dumps(vars)
        )
        return response  # type: ignore

    async def signin(self, vars: Dict[str, Any]) -> str:
        """Sign this connection in to a specific authentication scope.

        Args:
            vars: Variables used in a signin query.

        Examples:
            await db.signin({"user": "root", "pass": "root"})
        """
        response = await self._request(
            method="POST", uri="/signin", data=json.dumps(vars)
        )
        return response  # type: ignore

    async def query(
        self, sql: str, vars: Optional[Dict[str, Any]] = None
    ) -> List[Dict[str, Any]]:
        """Run a set of SurrealQL statements against the database.

        Args:
            sql: Specifies the SurrealQL statements.
            vars: Assigns variables which can be used in the query.

        Returns:
            The records.

        Examples:
            Assign the variable on the connection
                result = await db.query('create person; select * from type::table($tb)', {'tb': 'person'})

            Get the first result from the first query
                result[0]['result'][0]

            Get all of the results from the second query
                result[1]['result']
        """
        response = await self._request(method="POST", uri="/sql", data=sql, params=vars)
        return response  # type: ignore

    async def select(self, thing: str) -> List[Dict[str, Any]]:
        """Select all records in a table (or other entity),
        or a specific record, in the database.

        This function will run the following query in the database:
        select * from $thing

        Args:
            thing: The table or record ID to select.

        Returns:
            The records.

        Examples:
            Select all records from a table (or other entity)
                people = await db.select('person')

            Select a specific record from a table (or other entity)
                person = await db.select('person:h5wxrf2ewk8xjxosxtyc')
        """
        table, record_id = thing.split(":") if ":" in thing else (thing, None)
        response = await self._request(
            method="GET",
            uri=f"/key/{table}/{record_id}" if record_id else f"/key/{table}",
        )
        if not response and record_id is not None:
            raise SurrealException(f"Key {record_id} not found in table {table}")
        return response[0]["result"]  # type: ignore

    async def create(self, thing: str, data: Optional[Dict[str, Any]] = None) -> str:
        """Create a record in the database.

        This function will run the following query in the database:
        create $thing content $data

        Args:
            thing: The table or record ID.
            data: The document / record data to insert.

        Examples:
            Create a record with a random ID
                person = await db.create('person')

            Create a record with a specific ID
                record = await db.create('person:tobie', {
                    'name': 'Tobie',
                    'settings': {
                        'active': true,
                        'marketing': true,
                        },
                })
        """
        table, record_id = thing.split(":") if ":" in thing else (thing, None)
        response = await self._request(
            method="POST",
            uri=f"/key/{table}/{record_id}" if record_id else f"/key/{table}",
            data=json.dumps(data, ensure_ascii=False),
        )
        if not response and record_id is not None:
            raise SurrealException(f"Key {record_id} not found in table {table}")
        return response[0]["result"]  # type: ignore

    async def update(self, thing: str, data: Any) -> Dict[str, Any]:
        """Update all records in a table, or a specific record, in the database.

        This function replaces the current document / record data with the
        specified data.

        This function will run the following query in the database:
        update $thing content $data

        Args:
            thing: The table or record ID.
            data: The document / record data to insert.

        Examples:
            Update all records in a table
                person = await db.update('person')

            Update a record with a specific ID
                record = await db.update('person:tobie', {
                    'name': 'Tobie',
                    'settings': {
                        'active': true,
                        'marketing': true,
                        },
                })
        """
        table, record_id = thing.split(":") if ":" in thing else (thing, None)
        response = await self._request(
            method="PUT",
            uri=f"/key/{table}/{record_id}" if record_id else f"/key/{table}",
            data=json.dumps(data, ensure_ascii=False),
        )
        return response[0]["result"]  # type: ignore

    async def patch(self, thing: str, data: Any) -> Dict[str, Any]:
        """Apply JSON Patch changes to all records, or a specific record, in the database.

        This function patches the current document / record data with
        the specified JSON Patch data.

        This function will run the following query in the database:
        update $thing patch $data

        Args:
            thing: The table or record ID.
            data: The data to modify the record with.

        Examples:
            Update all records in a table
                people = await db.patch('person', [
                    { 'op': "replace", 'path': "/created_at", 'value': str(datetime.datetime.utcnow()) }])

            Update a record with a specific ID
            person = await db.patch('person:tobie', [
                { 'op': "replace", 'path': "/settings/active", 'value': False },
                { 'op': "add", "path": "/tags", "value": ["developer", "engineer"] },
                { 'op': "remove", "path": "/temp" },
            ])
        """
        table, record_id = thing.split(":") if ":" in thing else (thing, None)
        response = await self._request(
            method="PATCH",
            uri=f"/key/{table}/{record_id}" if record_id else f"/key/{table}",
            data=json.dumps(data, ensure_ascii=False),
        )
        return response[0]["result"]  # type: ignore

    async def delete(self, thing: str) -> List[Dict[str, Any]]:
        """Delete all records in a table, or a specific record, from the database.

        This function will run the following query in the database:
        delete * from $thing

        Args:
            thing: The table name or a record ID to delete.

        Examples:
            Delete all records from a table
                await db.delete('person')
            Delete a specific record from a table
                await db.delete('person:h5wxrf2ewk8xjxosxtyc')
        """
        table, record_id = thing.split(":") if ":" in thing else (thing, None)
        response = await self._request(
            method="DELETE",
            uri=f"/key/{table}/{record_id}" if record_id else f"/key/{table}",
        )
        return response  # type: ignore