controlid-sdk 0.3.2__tar.gz → 0.3.3__tar.gz

{controlid_sdk-0.3.2 → controlid_sdk-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlid-sdk
-Version: 0.3.2
+Version: 0.3.3
 Summary: A production-ready asynchronous Python SDK for ControlID access control devices, supporting biometrics, networking, and complex time schedules.
 Author-email: Tulio Amancio <root@tsuriu.com.br>
 License: MIT
@@ -20,6 +20,9 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 
 # ControlID Python SDK (Async)
 
@@ -192,6 +195,16 @@ await client.add_time_spans([
 
 ### 🧩 Generic Object API
 
+## Firmware Compatibility Matrix
+
+Since ControlID access control terminals run varying firmware versions, some API fields and tables may not be supported on all devices:
+
+| Feature / Model | iDFace | iDAccess / iDFlex | iDBlock / Turnstiles | Notes |
+| --- | --- | --- | --- | --- |
+| **Card.type** | ⚠️ Supported only on newer firmware | ⚠️ Supported only on newer firmware | N/A | Older firmwares lack the `type` column in the `cards` table. Exclude it by leaving `Card.type = None`. |
+| **Custom Database Fields** | ✅ Fully Supported | ⚠️ Depends on firmware version | N/A | Add custom fields (e.g. `cpf` to `c_users`) via `client.add_custom_field()`. |
+| **Facial Templates** | ✅ Fully Supported | N/A | N/A | Enrollment and image upload functions require a device camera sensor. |
+
 ## Directory Structure
 - `src/controlid/client.py`: Core asynchronous logic and endpoints.
 - `src/controlid/models.py`: Pydantic V2 definitions.

{controlid_sdk-0.3.2 → controlid_sdk-0.3.3}/README.md

@@ -169,6 +169,16 @@ await client.add_time_spans([
 
 ### 🧩 Generic Object API
 
+## Firmware Compatibility Matrix
+
+Since ControlID access control terminals run varying firmware versions, some API fields and tables may not be supported on all devices:
+
+| Feature / Model | iDFace | iDAccess / iDFlex | iDBlock / Turnstiles | Notes |
+| --- | --- | --- | --- | --- |
+| **Card.type** | ⚠️ Supported only on newer firmware | ⚠️ Supported only on newer firmware | N/A | Older firmwares lack the `type` column in the `cards` table. Exclude it by leaving `Card.type = None`. |
+| **Custom Database Fields** | ✅ Fully Supported | ⚠️ Depends on firmware version | N/A | Add custom fields (e.g. `cpf` to `c_users`) via `client.add_custom_field()`. |
+| **Facial Templates** | ✅ Fully Supported | N/A | N/A | Enrollment and image upload functions require a device camera sensor. |
+
 ## Directory Structure
 - `src/controlid/client.py`: Core asynchronous logic and endpoints.
 - `src/controlid/models.py`: Pydantic V2 definitions.

{controlid_sdk-0.3.2 → controlid_sdk-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "controlid-sdk"
-version = "0.3.2"
+version = "0.3.3"
 authors = [
   { name="Tulio Amancio", email="root@tsuriu.com.br" },
 ]
@@ -30,5 +30,15 @@ dependencies = [
     "pydantic>=2.0.0",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
 [project.urls]
 "Homepage" = "https://github.com/tulioamancio/controlid-python-sdk"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

{controlid_sdk-0.3.2 → controlid_sdk-0.3.3}/src/controlid/__init__.py

@@ -18,10 +18,21 @@ from .models import (
     GPIOStatus,
     CustomField,
 )
-from .exceptions import ControlIDError, AuthenticationError, SessionError, APIError
+from .exceptions import (
+    ControlIDError,
+    AuthenticationError,
+    SessionError,
+    APIError,
+    BadRequestError,
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    DeviceUnreachableError,
+)
 from . import constants
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = [
     "ControlIDClient",
@@ -46,6 +57,13 @@ __all__ = [
     "AuthenticationError",
     "SessionError",
     "APIError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "DeviceUnreachableError",
     # Constants module (handy for card type enums, table names, etc.)
     "constants",
 ]
+

{controlid_sdk-0.3.2 → controlid_sdk-0.3.3}/src/controlid/client.py

@@ -191,16 +191,44 @@ class ControlIDClient:
                 # Session expired — re-login and retry once
                 await self.login()
                 url = self._get_url(endpoint)
-                response = await self._client.post(url, json=payload or {}, timeout=timeout)
-                response.raise_for_status()
-                return response.json()
-            raise ex.APIError(
-                f"API Error: {e.response.text}",
-                status_code=e.response.status_code,
-                response=e.response.text,
-            )
+                try:
+                    response = await self._client.post(url, json=payload or {}, timeout=timeout)
+                    response.raise_for_status()
+                    return response.json()
+                except httpx.HTTPStatusError as retry_e:
+                    status_code = retry_e.response.status_code
+                    msg = f"API Error: {retry_e.response.text}"
+                    if status_code == 400:
+                        raise ex.BadRequestError(msg, status_code=status_code, response=retry_e.response.text)
+                    elif status_code == 401:
+                        raise ex.UnauthorizedError(msg, status_code=status_code, response=retry_e.response.text)
+                    elif status_code == 403:
+                        raise ex.ForbiddenError(msg, status_code=status_code, response=retry_e.response.text)
+                    elif status_code == 404:
+                        raise ex.NotFoundError(msg, status_code=status_code, response=retry_e.response.text)
+                    elif status_code == 429:
+                        raise ex.RateLimitError(msg, status_code=status_code, response=retry_e.response.text)
+                    else:
+                        raise ex.APIError(msg, status_code=status_code, response=retry_e.response.text)
+
+            status_code = e.response.status_code
+            msg = f"API Error: {e.response.text}"
+            if status_code == 400:
+                raise ex.BadRequestError(msg, status_code=status_code, response=e.response.text)
+            elif status_code == 401:
+                raise ex.UnauthorizedError(msg, status_code=status_code, response=e.response.text)
+            elif status_code == 403:
+                raise ex.ForbiddenError(msg, status_code=status_code, response=e.response.text)
+            elif status_code == 404:
+                raise ex.NotFoundError(msg, status_code=status_code, response=e.response.text)
+            elif status_code == 429:
+                raise ex.RateLimitError(msg, status_code=status_code, response=e.response.text)
+            else:
+                raise ex.APIError(msg, status_code=status_code, response=e.response.text)
+        except (httpx.ConnectError, httpx.ConnectTimeout, httpx.ReadTimeout, httpx.WriteTimeout, httpx.PoolTimeout) as e:
+            raise ex.DeviceUnreachableError(f"Device unreachable: {type(e).__name__} {e}")
         except Exception as e:
-            if isinstance(e, (ex.APIError, ex.AuthenticationError)): raise
+            if isinstance(e, (ex.APIError, ex.AuthenticationError, ex.DeviceUnreachableError)): raise
             raise ex.ControlIDError(f"Request failed: {type(e).__name__} {e}")
 
     async def get_system_information(self) -> Dict[str, Any]:

controlid_sdk-0.3.3/src/controlid/exceptions.py

@@ -0,0 +1,47 @@
+class ControlIDError(Exception):
+    """Base exception for ControlID SDK."""
+    pass
+
+class AuthenticationError(ControlIDError):
+    """Raised when authentication fails."""
+    pass
+
+class SessionError(ControlIDError):
+    """Raised when there is an issue with the session."""
+    pass
+
+class APIError(ControlIDError):
+    """Raised when the API returns an error response."""
+    def __init__(self, message, status_code=None, response=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+class BadRequestError(APIError):
+    """Raised when the API returns a 400 Bad Request error."""
+    pass
+
+class UnauthorizedError(APIError):
+    """Raised when the API returns a 401 Unauthorized error."""
+    pass
+
+class ForbiddenError(APIError):
+    """Raised when the API returns a 403 Forbidden error."""
+    pass
+
+class NotFoundError(APIError):
+    """Raised when the API returns a 404 Not Found error."""
+    pass
+
+class RateLimitError(APIError):
+    """Raised when the API returns a 429 Too Many Requests error."""
+    pass
+
+class DeviceUnreachableError(ControlIDError):
+    """Raised when the device is unreachable (e.g. connection timeout or dns failure)."""
+    pass
+
+class ObjectError(ControlIDError):
+    """Raised when an object operation fails."""
+    pass
+

{controlid_sdk-0.3.2 → controlid_sdk-0.3.3}/src/controlid_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlid-sdk
-Version: 0.3.2
+Version: 0.3.3
 Summary: A production-ready asynchronous Python SDK for ControlID access control devices, supporting biometrics, networking, and complex time schedules.
 Author-email: Tulio Amancio <root@tsuriu.com.br>
 License: MIT
@@ -20,6 +20,9 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 
 # ControlID Python SDK (Async)
 
@@ -192,6 +195,16 @@ await client.add_time_spans([
 
 ### 🧩 Generic Object API
 
+## Firmware Compatibility Matrix
+
+Since ControlID access control terminals run varying firmware versions, some API fields and tables may not be supported on all devices:
+
+| Feature / Model | iDFace | iDAccess / iDFlex | iDBlock / Turnstiles | Notes |
+| --- | --- | --- | --- | --- |
+| **Card.type** | ⚠️ Supported only on newer firmware | ⚠️ Supported only on newer firmware | N/A | Older firmwares lack the `type` column in the `cards` table. Exclude it by leaving `Card.type = None`. |
+| **Custom Database Fields** | ✅ Fully Supported | ⚠️ Depends on firmware version | N/A | Add custom fields (e.g. `cpf` to `c_users`) via `client.add_custom_field()`. |
+| **Facial Templates** | ✅ Fully Supported | N/A | N/A | Enrollment and image upload functions require a device camera sensor. |
+
 ## Directory Structure
 - `src/controlid/client.py`: Core asynchronous logic and endpoints.
 - `src/controlid/models.py`: Pydantic V2 definitions.

{controlid_sdk-0.3.2 → controlid_sdk-0.3.3}/src/controlid_sdk.egg-info/SOURCES.txt

@@ -9,4 +9,6 @@ src/controlid_sdk.egg-info/PKG-INFO
 src/controlid_sdk.egg-info/SOURCES.txt
 src/controlid_sdk.egg-info/dependency_links.txt
 src/controlid_sdk.egg-info/requires.txt
-src/controlid_sdk.egg-info/top_level.txt
+src/controlid_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_models.py

controlid_sdk-0.3.3/src/controlid_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.24.0
+pydantic>=2.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0

controlid_sdk-0.3.3/tests/test_client.py

@@ -0,0 +1,98 @@
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+import httpx
+from controlid import ControlIDClient
+from controlid.exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    DeviceUnreachableError,
+    APIError,
+)
+
+@pytest.mark.asyncio
+async def test_client_login_success():
+    client = ControlIDClient(host="https://192.168.0.100", user="admin", password="password")
+    
+    mock_response = MagicMock(spec=httpx.Response)
+    mock_response.status_code = 200
+    mock_response.json = MagicMock(return_value={"session": "test-session-token"})
+    mock_response.raise_for_status = MagicMock()
+    
+    with patch("httpx.AsyncClient.post", new_callable=AsyncMock, return_value=mock_response) as mock_post:
+        session = await client.login()
+        assert session == "test-session-token"
+        assert client.session == "test-session-token"
+        mock_post.assert_called_once()
+
+@pytest.mark.asyncio
+async def test_client_login_failure():
+    client = ControlIDClient(host="https://192.168.0.100", user="admin", password="password")
+    
+    mock_response = MagicMock(spec=httpx.Response)
+    mock_response.status_code = 401
+    mock_response.json = MagicMock(return_value={"error": "Invalid credentials"})
+    mock_response.raise_for_status = MagicMock()
+    
+    with patch("httpx.AsyncClient.post", new_callable=AsyncMock, return_value=mock_response):
+        with pytest.raises(AuthenticationError):
+            await client.login()
+
+@pytest.mark.asyncio
+async def test_client_request_injects_session():
+    client = ControlIDClient(host="https://192.168.0.100", user="admin", password="password")
+    client.session = "active-session"
+    
+    mock_response = MagicMock(spec=httpx.Response)
+    mock_response.status_code = 200
+    mock_response.json = MagicMock(return_value={"status": "success"})
+    mock_response.raise_for_status = MagicMock()
+    
+    await client._ensure_client()
+    
+    with patch.object(client._client, "post", new_callable=AsyncMock, return_value=mock_response) as mock_post:
+        res = await client.request("/some-endpoint", {"param": "val"})
+        assert res == {"status": "success"}
+        called_url = mock_post.call_args[0][0]
+        assert "session=active-session" in called_url
+
+@pytest.mark.asyncio
+async def test_client_request_handles_status_errors():
+    client = ControlIDClient(host="https://192.168.0.100")
+    client.session = "active-session"
+    await client._ensure_client()
+    
+    error_cases = [
+        (400, BadRequestError),
+        (401, UnauthorizedError),
+        (403, ForbiddenError),
+        (404, NotFoundError),
+        (429, RateLimitError),
+        (500, APIError),
+    ]
+    
+    for code, exc_class in error_cases:
+        mock_response = httpx.Response(status_code=code, text=f"Error {code}")
+        
+        if code == 401:
+            with patch.object(client, "login", new_callable=AsyncMock, return_value="new-token"):
+                with patch.object(client._client, "post", new_callable=AsyncMock, side_effect=httpx.HTTPStatusError("Err", request=None, response=mock_response)):
+                    with pytest.raises(exc_class):
+                        await client.request("/some-endpoint")
+        else:
+            with patch.object(client._client, "post", new_callable=AsyncMock, side_effect=httpx.HTTPStatusError("Err", request=None, response=mock_response)):
+                with pytest.raises(exc_class):
+                    await client.request("/some-endpoint")
+
+@pytest.mark.asyncio
+async def test_client_request_device_unreachable():
+    client = ControlIDClient(host="https://192.168.0.100")
+    client.session = "active-session"
+    await client._ensure_client()
+    
+    with patch.object(client._client, "post", new_callable=AsyncMock, side_effect=httpx.ConnectError("Connection refused")):
+        with pytest.raises(DeviceUnreachableError):
+            await client.request("/some-endpoint")

controlid_sdk-0.3.3/tests/test_models.py

@@ -0,0 +1,30 @@
+from controlid.models import User, Card, TimeZone, TimeSpan
+
+def test_user_model():
+    user = User(id=1, name="John Doe", registration="12345")
+    assert user.id == 1
+    assert user.name == "John Doe"
+    assert user.registration == "12345"
+    assert user.password == ""
+    
+def test_card_model():
+    card1 = Card(id=10, value=123456, user_id=1, type=0)
+    assert card1.id == 10
+    assert card1.value == 123456
+    assert card1.user_id == 1
+    assert card1.type == 0
+    
+    # Exclude_none test
+    card2 = Card(value=654321, user_id=2)
+    assert card2.type is None
+    dumped = card2.model_dump(exclude_none=True)
+    assert "type" not in dumped
+
+def test_timezone_and_timespan():
+    tz = TimeZone(id=1, name="Standard")
+    assert tz.name == "Standard"
+    
+    span = TimeSpan(time_zone_id=1, start=28800, end=64800, mon=1, tue=1)
+    assert span.start == 28800
+    assert span.mon == 1
+    assert span.sun == 0

controlid_sdk-0.3.2/src/controlid/exceptions.py

@@ -1,22 +0,0 @@
-class ControlIDError(Exception):
-    """Base exception for ControlID SDK."""
-    pass
-
-class AuthenticationError(ControlIDError):
-    """Raised when authentication fails."""
-    pass
-
-class SessionError(ControlIDError):
-    """Raised when there is an issue with the session."""
-    pass
-
-class APIError(ControlIDError):
-    """Raised when the API returns an error response."""
-    def __init__(self, message, status_code=None, response=None):
-        super().__init__(message)
-        self.status_code = status_code
-        self.response = response
-        
-class ObjectError(ControlIDError):
-    """Raised when an object operation fails."""
-    pass

controlid_sdk-0.3.2/src/controlid_sdk.egg-info/requires.txt

@@ -1,2 +0,0 @@
-httpx>=0.24.0
-pydantic>=2.0.0