python-arango 7.7.0__tar.gz → 7.8.1__tar.gz

{python-arango-7.7.0 → python-arango-7.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-arango
-Version: 7.7.0
+Version: 7.8.1
 Summary: Python Driver for ArangoDB
 Home-page: https://github.com/ArangoDB-Community/python-arango
 Author: Joohwan Oh

{python-arango-7.7.0 → python-arango-7.8.1}/arango/client.py

@@ -171,6 +171,7 @@ class ArangoClient:
         password: str = "",
         verify: bool = False,
         auth_method: str = "basic",
+        user_token: Optional[str] = None,
         superuser_token: Optional[str] = None,
         verify_certificate: bool = True,
     ) -> StandardDatabase:
@@ -189,9 +190,17 @@ class ArangoClient:
             refreshed automatically using ArangoDB username and password. This
             assumes that the clocks of the server and client are synchronized.
         :type auth_method: str
+        :param user_token: User generated token for user access.
+            If set, parameters **username**, **password** and **auth_method**
+            are ignored. This token is not refreshed automatically. If automatic
+            token refresh is required, consider setting **auth_method** to "jwt"
+            and using the **username** and **password** parameters instead. Token
+            expiry will be checked.
+        :type user_token: str
         :param superuser_token: User generated token for superuser access.
             If set, parameters **username**, **password** and **auth_method**
-            are ignored. This token is not refreshed automatically.
+            are ignored. This token is not refreshed automatically. Token
+            expiry will not be checked.
         :type superuser_token: str
         :param verify_certificate: Verify TLS certificates.
         :type verify_certificate: bool
@@ -213,6 +222,17 @@ class ArangoClient:
                 deserializer=self._deserializer,
                 superuser_token=superuser_token,
             )
+        elif user_token is not None:
+            connection = JwtConnection(
+                hosts=self._hosts,
+                host_resolver=self._host_resolver,
+                sessions=self._sessions,
+                db_name=name,
+                http_client=self._http,
+                serializer=self._serializer,
+                deserializer=self._deserializer,
+                user_token=user_token,
+            )
         elif auth_method.lower() == "basic":
             connection = BasicConnection(
                 hosts=self._hosts,

{python-arango-7.7.0 → python-arango-7.8.1}/arango/connection.py

@@ -13,10 +13,16 @@ from abc import abstractmethod
 from typing import Any, Callable, Optional, Sequence, Set, Tuple, Union
 
 import jwt
+from jwt.exceptions import ExpiredSignatureError
 from requests import ConnectionError, Session
 from requests_toolbelt import MultipartEncoder
 
-from arango.exceptions import JWTAuthError, ServerConnectionError
+from arango.exceptions import (
+    JWTAuthError,
+    JWTExpiredError,
+    JWTRefreshError,
+    ServerConnectionError,
+)
 from arango.http import HTTPClient
 from arango.request import Request
 from arango.resolver import HostResolver
@@ -203,7 +209,7 @@ class BaseConnection:
         request = Request(method="get", endpoint="/_api/collection")
         resp = self.send_request(request)
         if resp.status_code in {401, 403}:
-            raise ServerConnectionError("bad username and/or password")
+            raise ServerConnectionError("bad username/password or token is expired")
         if not resp.is_success:  # pragma: no cover
             raise ServerConnectionError(resp.error_message or "bad server response")
         return resp.status_code
@@ -300,11 +306,12 @@ class JwtConnection(BaseConnection):
         host_resolver: HostResolver,
         sessions: Sequence[Session],
         db_name: str,
-        username: str,
-        password: str,
         http_client: HTTPClient,
         serializer: Callable[..., str],
         deserializer: Callable[[str], Any],
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        user_token: Optional[str] = None,
     ) -> None:
         super().__init__(
             hosts,
@@ -323,7 +330,13 @@ class JwtConnection(BaseConnection):
         self._token: Optional[str] = None
         self._token_exp: int = sys.maxsize
 
-        self.refresh_token()
+        if user_token is not None:
+            self.set_token(user_token)
+        elif username is not None and password is not None:
+            self.refresh_token()
+        else:
+            m = "Either **user_token** or **username** & **password** must be set"
+            raise ValueError(m)
 
     def send_request(self, request: Request) -> Response:
         """Send an HTTP request to ArangoDB server.
@@ -360,7 +373,12 @@ class JwtConnection(BaseConnection):
 
         :return: JWT token.
         :rtype: str
+        :raise arango.exceptions.JWTRefreshError: If missing username & password.
+        :raise arango.exceptions.JWTAuthError: If token retrieval fails.
         """
+        if self._username is None or self._password is None:
+            raise JWTRefreshError("username and password must be set")
+
         request = Request(
             method="post",
             endpoint="/_open/auth",
@@ -374,21 +392,34 @@ class JwtConnection(BaseConnection):
         if not resp.is_success:
             raise JWTAuthError(resp, request)
 
-        self._token = resp.body["jwt"]
-        assert self._token is not None
-
-        jwt_payload = jwt.decode(
-            self._token,
-            issuer="arangodb",
-            algorithms=["HS256"],
-            options={
-                "require_exp": True,
-                "require_iat": True,
-                "verify_iat": True,
-                "verify_exp": True,
-                "verify_signature": False,
-            },
-        )
+        self.set_token(resp.body["jwt"])
+
+    def set_token(self, token: str) -> None:
+        """Set the JWT token.
+
+        :param token: JWT token.
+        :type token: str
+        :raise arango.exceptions.JWTExpiredError: If the token is expired.
+        """
+        assert token is not None
+
+        try:
+            jwt_payload = jwt.decode(
+                token,
+                issuer="arangodb",
+                algorithms=["HS256"],
+                options={
+                    "require_exp": True,
+                    "require_iat": True,
+                    "verify_iat": True,
+                    "verify_exp": True,
+                    "verify_signature": False,
+                },
+            )
+        except ExpiredSignatureError:
+            raise JWTExpiredError("JWT token is expired")
+
+        self._token = token
         self._token_exp = jwt_payload["exp"]
         self._auth_header = f"bearer {self._token}"
 
@@ -444,3 +475,30 @@ class JwtSuperuserConnection(BaseConnection):
         request.headers["Authorization"] = self._auth_header
 
         return self.process_request(host_index, request)
+
+    def set_token(self, token: str) -> None:
+        """Set the JWT token.
+
+        :param token: JWT token.
+        :type token: str
+        :raise arango.exceptions.JWTExpiredError: If the token is expired.
+        """
+        assert token is not None
+
+        try:
+            jwt.decode(
+                token,
+                issuer="arangodb",
+                algorithms=["HS256"],
+                options={
+                    "require_exp": True,
+                    "require_iat": True,
+                    "verify_iat": True,
+                    "verify_exp": True,
+                    "verify_signature": False,
+                },
+            )
+        except ExpiredSignatureError:
+            raise JWTExpiredError("JWT token is expired")
+
+        self._auth_header = f"bearer {token}"

{python-arango-7.7.0 → python-arango-7.8.1}/arango/exceptions.py

@@ -1014,3 +1014,11 @@ class JWTSecretListError(ArangoServerError):
 
 class JWTSecretReloadError(ArangoServerError):
     """Failed to reload JWT secrets."""
+
+
+class JWTRefreshError(ArangoClientError):
+    """Failed to refresh JWT token."""
+
+
+class JWTExpiredError(ArangoClientError):
+    """JWT token has expired."""

{python-arango-7.7.0 → python-arango-7.8.1}/arango/graph.py

@@ -107,9 +107,9 @@ class Graph(ApiGroup):
         return self._execute(request, response_handler)
 
     def vertex_collections(self) -> Result[List[str]]:
-        """Return vertex collections in the graph that are not orphaned.
+        """Return vertex collections in the graph.
 
-        :return: Names of vertex collections that are not orphaned.
+        :return: Names of vertex collections in Edge Definitions and Orphan Collections.
         :rtype: [str]
         :raise arango.exceptions.VertexCollectionListError: If retrieval fails.
         """

{python-arango-7.7.0 → python-arango-7.8.1}/arango/utils.py

@@ -120,5 +120,5 @@ def build_filter_conditions(filters: Json) -> str:
     if not filters:
         return ""
 
-    conditions = [f"doc.{k} == {json.dumps(v)}" for k, v in filters.items()]
+    conditions = [f"doc.`{k}` == {json.dumps(v)}" for k, v in filters.items()]
     return "FILTER " + " AND ".join(conditions)

python-arango-7.8.1/arango/version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '7.8.1'
+__version_tuple__ = version_tuple = (7, 8, 1)

{python-arango-7.7.0 → python-arango-7.8.1}/docs/auth.rst

@@ -59,7 +59,7 @@ to work correctly.
     # compensate for out-of-sync clocks between the client and server.
     db.conn.ext_leeway = 2
 
-User generated JWT token can be used for superuser access.
+User generated JWT token can be used for user and superuser access.
 
 **Example:**
 
@@ -89,3 +89,29 @@ User generated JWT token can be used for superuser access.
 
     # Connect to "test" database as superuser using the token.
     db = client.db('test', superuser_token=token)
+
+    # Connect to "test" database as user using the token.
+    db = client.db('test', user_token=token)
+
+User and superuser tokens can be set on the connection object as well.
+
+**Example:**
+
+.. code-block:: python
+
+    from arango import ArangoClient
+
+    # Initialize the ArangoDB client.
+    client = ArangoClient()
+
+    # Connect to "test" database as superuser using the token.
+    db = client.db('test', user_token='token')
+
+    # Set the user token on the connection object.
+    db.conn.set_token('new token')
+
+    # Connect to "test" database as superuser using the token.
+    db = client.db('test', superuser_token='superuser token')
+
+    # Set the user token on the connection object.
+    db.conn.set_token('new superuser token')

{python-arango-7.7.0 → python-arango-7.8.1}/python_arango.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-arango
-Version: 7.7.0
+Version: 7.8.1
 Summary: Python Driver for ArangoDB
 Home-page: https://github.com/ArangoDB-Community/python-arango
 Author: Joohwan Oh

python-arango-7.7.0/arango/version.py

@@ -1,8 +0,0 @@
-# file generated by setuptools_scm
-# don't change, don't track in version control
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple
-
-__version__ = version = '7.7.0'  # type: str
-__version_tuple__ = version_tuple = (7, 7, 0)  # type: Tuple[int | str, ...]