prepare for release

Author: bodrovis

docs/additional_info/changelog.rst

@@ -3,6 +3,14 @@
 Changelog
 =========
 
+4.0.0 (28-Sep-2025)
+-------------------
+
+* Require Python 3.10+
+* Fully rework typing system
+* Make code more solid, enhance error handling
+* Switch to uv, black, ruff
+
 3.5.1 (14-May-2025)
 -------------------
 

docs/additional_info/exception_handling.rst

@@ -30,7 +30,7 @@ To handle an exception you would do the following:
       client.project('invalid_id')
   except lokalise.errors.NotFound as err:
       print(err.message)
-      print(err.code)
+      print(err.status_code)
 
 Rate limits
 -----------

lokalise/_version.py

@@ -4,4 +4,4 @@
 This module contains plugin metadata.
 """
 
-__version__: str = "3.5.1"
+__version__: str = "4.0.0"

lokalise/base_client.py

@@ -1,7 +1,7 @@
 """
 lokalise.base_client
 ~~~~~~~~~~~~~~~~~~~~
-This module contains base API client definition.
+This module contains the base Lokalise API client definition.
 """
 
 from .types import FullClientProto
@@ -10,87 +10,93 @@
 
 
 class BaseClient(FullClientProto):
-    """Base client used to send API requests."""
+    """Base client used to configure and send Lokalise API requests."""
 
     def __init__(
         self,
         token: str,
-        connect_timeout: int | float | None = None,
-        read_timeout: int | float | None = None,
-        enable_compression: bool | None = False,
+        connect_timeout: Number | None = None,
+        read_timeout: Number | None = None,
+        enable_compression: bool = False,
         api_host: str | None = None,
     ) -> None:
-        """Instantiate a new Lokalise API client.
-
-        :param str token: Your Lokalise API token.
-        :param connect_timeout: (optional) Server connection timeout
-        (the value is in seconds). By default, the client will wait indefinitely.
-        :type connect_timeout: int or float
-        :param read_timeout: (optional) Server read timeout
-        (the value is in seconds). By default, the client will wait indefinitely.
-        :type read_timeout: int or float
-        :param enable_compression: (optional) Whether to enable gzip compression.
-        :param api_host: (optional) Custom API host to send requests to.
-        By default it's off.
-        :type enable_compression: bool
+        """Create a new Lokalise API client instance.
+
+        Args:
+            token: Your Lokalise API token (non-empty string).
+            connect_timeout: Optional connection timeout in seconds. ``None`` means
+                wait indefinitely.
+            read_timeout: Optional read timeout in seconds. ``None`` means
+                wait indefinitely.
+            enable_compression: Whether to enable gzip compression (default: False).
+            api_host: Optional custom API host. Defaults to the official Lokalise API.
         """
-        self._token = token
-        self._connect_timeout = connect_timeout
-        self._read_timeout = read_timeout
-        self._enable_compression = enable_compression
-        self._api_host = api_host
-        self._token_header = "X-Api-Token"
+        if not token:
+            raise ValueError("token must be a non-empty string")
+
+        self._token: str | None = token
+        self._connect_timeout: Number | None = connect_timeout
+        self._read_timeout: Number | None = read_timeout
+        self._enable_compression: bool = bool(enable_compression)
+        self._api_host: str | None = api_host.strip() if api_host and api_host.strip() else None
+        self._token_header: str = "X-Api-Token"
+
+    # ---------------------------------------------------------------------
+    # Properties
+    # ---------------------------------------------------------------------
 
     @property
-    def token(self) -> str:
+    def token(self) -> str | None:
+        """Return the current API token, or None if not set."""
         return self._token
 
     @token.setter
-    def token(self, value: str) -> None:
+    def token(self, value: str | None) -> None:
         if not value:
             raise ValueError("token must be a non-empty string")
         self._token = value
 
     @property
     def connect_timeout(self) -> Number | None:
+        """Connection timeout in seconds, or ``None`` for no limit."""
         return self._connect_timeout
 
     @connect_timeout.setter
     def connect_timeout(self, value: Number | None) -> None:
         if value is not None and value < 0:
-            raise ValueError("connect_timeout must be a non-negative number or None")
+            raise ValueError("connect_timeout must be non-negative or None")
         self._connect_timeout = value
 
     @property
     def read_timeout(self) -> Number | None:
+        """Read timeout in seconds, or ``None`` for no limit."""
         return self._read_timeout
 
     @read_timeout.setter
     def read_timeout(self, value: Number | None) -> None:
         if value is not None and value < 0:
-            raise ValueError("read_timeout must be a non-negative number or None")
+            raise ValueError("read_timeout must be non-negative or None")
         self._read_timeout = value
 
     @property
-    def enable_compression(self) -> bool | None:
+    def enable_compression(self) -> bool:
+        """Whether gzip compression is enabled."""
         return self._enable_compression
 
     @enable_compression.setter
     def enable_compression(self, value: bool | None) -> None:
-        self._enable_compression = bool(value) if value is not None else False
+        self._enable_compression = bool(value)
 
     @property
     def api_host(self) -> str | None:
+        """Custom API host, or ``None`` to use the default Lokalise API."""
         return self._api_host
 
     @api_host.setter
     def api_host(self, value: str | None) -> None:
-        if value is not None:
-            v = value.strip()
-            if not v:
-                value = None
-        self._api_host = value
+        self._api_host = value.strip() if value and value.strip() else None
 
     @property
     def token_header(self) -> str:
+        """HTTP header key used for the API token."""
         return self._token_header

lokalise/client.py

@@ -79,46 +79,53 @@ class Client(
     """
 
     def reset_client(self) -> None:
-        """Resets the API client by clearing all attributes."""
-        self._token = ""
+        """Resets the API client by clearing all attributes.
+        After reset, token is None and client is unusable until you set a new token.
+        """
+        self._token = None
         self._connect_timeout = None
         self._read_timeout = None
         self._enable_compression = False
-        self.__clear_endpoint_attrs()
+        self._clear_endpoint_attrs()
 
     # === Endpoint helpers
     def get_endpoint(self, name: str) -> BaseEndpoint:
         """Lazily loads an endpoint with a given name and stores it
         under a specific instance attribute. For example, if the `name`
         is "projects", then it will load .endpoints.projects_endpoint module
         and then set attribute like this:
-            self.__projects_endpoint = ProjectsEndpoint(self)
+            self._projects_endpoint = ProjectsEndpoint(self)
+        
+        This is internal; prefer calling mixin methods like client.projects().
 
         :param str name: Endpoint name to load
         """
         endpoint_name = name + "_endpoint"
         camelized_name = snake_to_camel(endpoint_name)
+
         # Dynamically load the necessary endpoint module
-        module = importlib.import_module(f".endpoints.{endpoint_name}", package="lokalise")
+        try:
+            module = importlib.import_module(f".endpoints.{endpoint_name}", package="lokalise")
+            endpoint_klass = getattr(module, camelized_name)
+        except (ModuleNotFoundError, AttributeError) as e:
+            raise ValueError(f"Unknown endpoint: {name}") from e
+        
         # Find endpoint class in the module
-        endpoint_klass = cast("type[BaseEndpoint]", getattr(module, camelized_name))
-        return self.__fetch_attr(f"__{endpoint_name}", lambda: endpoint_klass(self))
+        endpoint_klass: type[BaseEndpoint] = getattr(module, camelized_name)
+        return self._fetch_attr(f"_{endpoint_name}", lambda: endpoint_klass(self))
 
-    def __fetch_attr(self, attr_name: str, populator: Callable[[], T]) -> T:
+    def _fetch_attr(self, attr_name: str, populator: Callable[[], T]) -> T:
         """Searches for the given attribute.
         Uses populator to set the attribute if it cannot be found.
         Used to lazy-load endpoints.
         """
-        if not hasattr(self, attr_name):
-            setattr(self, attr_name, populator())
-        else:
-            val = getattr(self, attr_name)
-            if val is None:
-                val = populator()
-                setattr(self, attr_name, val)
-        return cast(T, getattr(self, attr_name))
+        val = getattr(self, attr_name, None)
+        if val is None:
+            val = populator()
+            setattr(self, attr_name, val)
+        return cast(T, val)
 
-    def __clear_endpoint_attrs(self) -> None:
+    def _clear_endpoint_attrs(self) -> None:
         """Clears all lazily-loaded endpoint attributes"""
         for attr in [a for a in vars(self) if a.endswith("_endpoint")]:
             delattr(self, attr)

lokalise/collections/base_collection.py

@@ -4,19 +4,20 @@
 Collection parent class inherited by specific collections.
 """
 
-from typing import Any, ClassVar, Generic, TypeVar, cast
+from collections.abc import Sequence
+from typing import Any, ClassVar, Generic, TypeVar, cast, overload
 
 from ..models.base_model import BaseModel
 
 TModel = TypeVar("TModel", bound=BaseModel)
 
 
-class BaseCollection(Generic[TModel]):
+class BaseCollection(Sequence[TModel], Generic[TModel]):
     """Abstract base class for resources collections.
 
     :attribute DATA_KEY: contains the key name that should be used to fetch
     collection data. Response usually arrives in the following format:
-    {"project_id": "abc", contributors: [{"user_id": 1}, {"user_id": 2}]}
+    {"project_id": "abc", "contributors": [{"user_id": 1}, {"user_id": 2}]}
     In this case, the DATA_KEY would be "contributors"
 
     :attribute MODEL_KLASS: tells which class to use to produce models for each
@@ -74,6 +75,27 @@ def __init__(self, raw_data: dict[str, Any]) -> None:
             self.limit = int(pagination.get("x-pagination-limit", 0) or 0)
             self.current_page = int(pagination.get("x-pagination-page", 0) or 0)
             self.next_cursor = cast(str | None, pagination.get("x-pagination-next-cursor", None))
+        else:
+            self.total_count = 0
+            self.page_count = 0
+            self.limit = 0
+            self.current_page = 0
+            self.next_cursor = None
+
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    @overload
+    def __getitem__(self, index: int) -> TModel: ...
+    @overload
+    def __getitem__(self, index: slice) -> list[TModel]: ...
+
+    def __getitem__(self, index: int | slice) -> TModel | list[TModel]:
+        return self.items[index]
 
     def is_last_page(self) -> bool:
         """Checks whether the current collection set is the last page.

lokalise/endpoints/base_endpoint.py

@@ -127,4 +127,7 @@ def path_with_params(self, **ids: str | int | None) -> str:
         on the actual endpoint.
         """
         defaults = {"parent_id": "", "resource_id": "", "subresource_id": ""}
-        return Template(self.PATH).substitute(defaults, **ids)
+        try:
+            return Template(self.PATH).substitute(defaults, **ids)
+        except KeyError as e:
+            raise ValueError(f"Missing required path parameter: {e}") from None

lokalise/oauth2/request.py

@@ -9,7 +9,7 @@
 import requests
 
 from lokalise._version import __version__
-from lokalise.request_utils import format_params, raise_on_error
+from lokalise.request_utils import format_params, raise_on_error, join_url
 
 BASE_URL = "https://app.lokalise.com/oauth2/"
 
@@ -19,7 +19,7 @@ def post(path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
     Perform an OAuth2 POST request (token exchange/revoke/etc).
     Returns parsed JSON or raises a structured error.
     """
-    url = __join_url(BASE_URL, path)
+    url = join_url(BASE_URL, path)
     resp = requests.post(url, data=format_params(params), **options())
     return respond_with(resp)
 
@@ -28,7 +28,10 @@ def respond_with(response: requests.Response) -> dict[str, Any]:
     """
     Parse JSON body and raise on HTTP error or on payload containing 'error'.
     """
-    data: dict[str, Any] = response.json()
+    try:
+        data: dict[str, Any] = response.json()
+    except ValueError:
+        data = {"_raw_body": response.text}
     raise_on_error(response, data)
     return data
 
@@ -40,13 +43,6 @@ def options() -> dict[str, Any]:
     headers: dict[str, Any] = {
         "Accept": "application/json",
         "User-Agent": f"python-lokalise-api plugin/{__version__}",
+        "Content-Type": "application/json",
     }
-    return {"headers": headers}
-
-
-def __join_url(base: str, path: str) -> str:
-    """
-    Safe join for base URL and path
-    """
-    url = base.rstrip("/") + "/" + path.lstrip("/")
-    return url.rstrip("/")
+    return {"headers": headers}

lokalise/oauth_client.py

@@ -22,7 +22,7 @@ def __init__(
         token: str,
         connect_timeout: int | float | None = None,
         read_timeout: int | float | None = None,
-        enable_compression: bool | None = False,
+        enable_compression: bool = False,
         api_host: str | None = None,
     ) -> None:
         """Instantiate a new Lokalise API client with OAuth 2 token.
@@ -39,7 +39,10 @@ def __init__(
         By default it's off.
         :type enable_compression: bool
         """
+        if not token:
+            raise ValueError("token must be a non-empty string")
         super().__init__(token, connect_timeout, read_timeout, enable_compression, api_host)
 
+        # Override token representation for OAuth
         self._token = f"Bearer {token}"
         self._token_header = "Authorization"