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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlid-sdk
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -12,7 +12,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Hardware
@@ -20,6 +19,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 +194,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.4}/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.4}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "controlid-sdk"
-version = "0.3.2"
+version = "0.3.4"
 authors = [
   { name="Tulio Amancio", email="root@tsuriu.com.br" },
 ]
 description = "A production-ready asynchronous Python SDK for ControlID access control devices, supporting biometrics, networking, and complex time schedules."
 readme = "README.md"
-license = { text = "MIT" }
+license = {text = "MIT"}
 requires-python = ">=3.9"
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -20,7 +20,6 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: System :: Hardware",
@@ -30,5 +29,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.4}/src/controlid/__init__.py

@@ -11,17 +11,27 @@ from .models import (
     Door,
     AccessLog,
     Device,
-    TimeZone,
     TimeSpan,
     FaceTemplate,
     CatraInfo,
     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.4"
 
 __all__ = [
     "ControlIDClient",
@@ -33,6 +43,7 @@ __all__ = [
     "UserGroup",
     "AccessRule",
     "TimeZone",
+    "TimeSpan",
     "Area",
     "Door",
     "AccessLog",
@@ -46,6 +57,14 @@ __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.4}/src/controlid/client.py

@@ -2,10 +2,11 @@ import httpx
 import asyncio
 import time as _time
 from typing import List, Dict, Any, Optional, Union
-from urllib.parse import quote, urlparse
+from urllib.parse import quote
 from . import constants as const
 from . import exceptions as ex
-from .models import User, Card, Door, AccessLog, UserRole, QRCard, CustomField, TimeZone, TimeSpan
+from .models import User, Card, AccessLog, UserRole, CustomField, TimeZone, TimeSpan
+
 
 
 def _normalize_host(host: str) -> str:
@@ -107,14 +108,12 @@ class ControlIDClient:
             payload = {"login": self.user, "password": self.password}
             
             try:
-                logger_ctx = {"host": try_host, "user": self.user}
                 response = await self._client.post(url, json=payload, timeout=5.0) # Short timeout for login attempt
                 response.raise_for_status()
                 data = response.json()
                 if "session" in data:
                     self.session = data["session"]
                     if self.host != try_host:
-                        old_host = self.host
                         self.host = try_host # Update to working host
                         if self.on_host_change:
                             try:
@@ -122,14 +121,16 @@ class ControlIDClient:
                                     asyncio.create_task(self.on_host_change(self.host))
                                 else:
                                     self.on_host_change(self.host)
-                            except Exception: pass
+                            except Exception:
+                                pass
                     return self.session
                 raise ex.AuthenticationError(f"Login failed: {data}")
             except (httpx.ConnectError, httpx.ConnectTimeout, httpx.ReadTimeout, httpx.WriteTimeout, httpx.PoolTimeout, httpx.ProtocolError, httpx.RemoteProtocolError, httpx.ProxyError) as e:
                 last_err = f"{type(e).__name__} on {proto}"
                 continue
             except Exception as e:
-                if isinstance(e, ex.AuthenticationError): raise
+                if isinstance(e, ex.AuthenticationError):
+                    raise
                 last_err = f"{type(e).__name__}: {str(e)}"
                 continue
                 
@@ -191,16 +192,45 @@ 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]:
@@ -342,8 +372,10 @@ class ControlIDClient:
     async def get_cards(self, user_id: Optional[int] = None, value: Optional[int] = None) -> List[Card]:
         """Return credentials for all users, or filtered by user_id or card value."""
         where = {}
-        if user_id: where["user_id"] = user_id
-        if value: where["value"] = value
+        if user_id:
+            where["user_id"] = user_id
+        if value:
+            where["value"] = value
         return [Card(**c) for c in await self.load_objects(const.TABLE_CARDS, where=where or None)]
 
     async def add_card(self, card: Card) -> int:
@@ -739,6 +771,8 @@ class ControlIDClient:
 
             await client.set_configuration({"face_id": {"qrcode_legacy_mode_enabled": "1"}})
         """
+        return await self.request(const.SET_CONFIGURATION, config)
+
     async def export_audit_logs(self, config: int = 1, api: int = 1, usb: int = 0, network: int = 0, time: int = 1, online: int = 0, menu: int = 1) -> List[Dict[str, Any]]:
         """
         Export device audit logs (system events, config changes, etc.).

controlid_sdk-0.3.4/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.4}/src/controlid/models.py

@@ -1,5 +1,5 @@
-from pydantic import BaseModel, Field
-from typing import Optional, List, Dict, Any
+from pydantic import BaseModel
+from typing import Optional, Dict, Any
 
 
 # ─── Core Models ───────────────────────────────────────────────────────────────

{controlid_sdk-0.3.2 → controlid_sdk-0.3.4}/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.4
 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
@@ -12,7 +12,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Hardware
@@ -20,6 +19,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 +194,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.4}/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.4/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.4/tests/test_client.py

@@ -0,0 +1,109 @@
+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")
+
+
+@pytest.mark.asyncio
+async def test_set_configuration_calls_hardware_endpoint():
+    client = ControlIDClient(host="https://192.168.0.100")
+    payload = {"snmp_agent": {"snmp_enabled": "1"}}
+    with patch.object(client, "request", new_callable=AsyncMock, return_value={"status": "ok"}) as request:
+        result = await client.set_configuration(payload)
+
+    request.assert_awaited_once_with("/set_configuration.fcgi", payload)
+    assert result == {"status": "ok"}

controlid_sdk-0.3.4/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