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

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

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: controlid-sdk
-Version: 0.3.3
+Version: 0.3.5
 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
 Project-URL: Homepage, https://github.com/tulioamancio/controlid-python-sdk
+Project-URL: Source, https://github.com/tulioamancio/controlid-python-sdk
+Project-URL: Bug Tracker, https://github.com/tulioamancio/controlid-python-sdk/issues
+Keywords: controlid,access-control,biometrics,iot,async,sdk
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -12,7 +15,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

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

@@ -4,13 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "controlid-sdk"
-version = "0.3.3"
+version = "0.3.5"
 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"}
+keywords = ["controlid", "access-control", "biometrics", "iot", "async", "sdk"]
 requires-python = ">=3.9"
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -20,7 +21,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",
@@ -38,6 +38,8 @@ dev = [
 
 [project.urls]
 "Homepage" = "https://github.com/tulioamancio/controlid-python-sdk"
+"Source" = "https://github.com/tulioamancio/controlid-python-sdk"
+"Bug Tracker" = "https://github.com/tulioamancio/controlid-python-sdk/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]

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

@@ -11,7 +11,6 @@ from .models import (
     Door,
     AccessLog,
     Device,
-    TimeZone,
     TimeSpan,
     FaceTemplate,
     CatraInfo,
@@ -32,7 +31,7 @@ from .exceptions import (
 )
 from . import constants
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 
 __all__ = [
     "ControlIDClient",
@@ -44,6 +43,7 @@ __all__ = [
     "UserGroup",
     "AccessRule",
     "TimeZone",
+    "TimeSpan",
     "Area",
     "Door",
     "AccessLog",
@@ -67,3 +67,4 @@ __all__ = [
     "constants",
 ]
 
+

{controlid_sdk-0.3.3 → controlid_sdk-0.3.5}/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:
@@ -45,6 +46,7 @@ class ControlIDClient:
         timeout: float = 15.0,
         verify: bool = True,
         on_host_change: Optional[Any] = None,
+        client: Optional[httpx.AsyncClient] = None,
     ):
         self.host = _normalize_host(host)
         self.user = user
@@ -53,16 +55,21 @@ class ControlIDClient:
         self.timeout = timeout
         self.verify = verify
         self.on_host_change = on_host_change
-        self._client: Optional[httpx.AsyncClient] = None
+        self._client = client
+        self._external_client = client is not None
+        self._client_lock = asyncio.Lock()
+        self._login_lock = asyncio.Lock()
+        self._semaphore = asyncio.Semaphore(3)
 
     # ─── Context Manager ───────────────────────────────────────────────────────
 
     async def __aenter__(self) -> "ControlIDClient":
-        self._client = httpx.AsyncClient(timeout=self.timeout, verify=self.verify, trust_env=False)
+        if not self._client:
+            self._client = httpx.AsyncClient(timeout=self.timeout, verify=self.verify, trust_env=False)
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        if self._client:
+        if self._client and not self._external_client:
             await self._client.aclose()
             self._client = None
 
@@ -78,7 +85,12 @@ class ControlIDClient:
     async def _ensure_client(self):
         """Create the httpx client if it doesn't exist or was closed."""
         if self._client is None or self._client.is_closed:
-            self._client = httpx.AsyncClient(timeout=self.timeout, verify=self.verify, trust_env=False)
+            async with self._client_lock:
+                if self._client is None or self._client.is_closed:
+                    if self._external_client:
+                        raise ex.ControlIDError("External httpx client is closed or not initialized")
+                    else:
+                        self._client = httpx.AsyncClient(timeout=self.timeout, verify=self.verify, trust_env=False)
 
     # ─── Authentication ────────────────────────────────────────────────────────
 
@@ -86,54 +98,57 @@ class ControlIDClient:
         """Authenticate with the device and store the session token.
         Attempts HTTP/HTTPS fallback if connection fails.
         """
-        await self._ensure_client()
+        async with self._login_lock:
+            await self._ensure_client()
+            if self.session:
+                return self.session
         
-        protocols = ["https", "http"]
-        # Start with current if it has one, otherwise prefer https
-        current_proto = "https"
-        if "://" in self.host:
-            current_proto = self.host.split("://")[0]
-            
-        # Reorder to try current first
-        if current_proto == "http":
-            protocols = ["http", "https"]
-            
-        last_err = None
-        for proto in protocols:
-            # Build URL for this protocol attempt
-            clean_host = self.host.split("://")[-1]
-            try_host = f"{proto}://{clean_host}"
-            url = f"{try_host}{const.LOGIN}"
-            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:
-                                if asyncio.iscoroutinefunction(self.on_host_change):
-                                    asyncio.create_task(self.on_host_change(self.host))
-                                else:
-                                    self.on_host_change(self.host)
-                            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
-                last_err = f"{type(e).__name__}: {str(e)}"
-                continue
+            protocols = ["https", "http"]
+            # Start with current if it has one, otherwise prefer https
+            current_proto = "https"
+            if "://" in self.host:
+                current_proto = self.host.split("://")[0]
+                
+            # Reorder to try current first
+            if current_proto == "http":
+                protocols = ["http", "https"]
+                
+            last_err = None
+            for proto in protocols:
+                # Build URL for this protocol attempt
+                clean_host = self.host.split("://")[-1]
+                try_host = f"{proto}://{clean_host}"
+                url = f"{try_host}{const.LOGIN}"
+                payload = {"login": self.user, "password": self.password}
                 
-        raise ex.AuthenticationError(f"Connection failed after trying all protocols: {last_err}")
+                try:
+                    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:
+                            self.host = try_host # Update to working host
+                            if self.on_host_change:
+                                try:
+                                    if asyncio.iscoroutinefunction(self.on_host_change):
+                                        asyncio.create_task(self.on_host_change(self.host))
+                                    else:
+                                        self.on_host_change(self.host)
+                                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
+                    last_err = f"{type(e).__name__}: {str(e)}"
+                    continue
+                    
+            raise ex.AuthenticationError(f"Connection failed after trying all protocols: {last_err}")
 
     async def logout(self):
         """Invalidate the current session on the device."""
@@ -172,64 +187,66 @@ class ControlIDClient:
         Automatically logs in if no session is available, and re-authenticates
         once on 401 errors (session expired).
         """
-        await self._ensure_client()
-        if not self.session:
-            await self.login()
-
-        url = self._get_url(endpoint)
-        timeout = timeout_override or self.timeout
-        
-        try:
-            if method.upper() == "POST":
-                response = await self._client.post(url, json=payload or {}, timeout=timeout)
-            else:
-                response = await self._client.get(url, timeout=timeout)
-            response.raise_for_status()
-            return response.json()
-        except httpx.HTTPStatusError as e:
-            if e.response.status_code == 401:
-                # Session expired — re-login and retry once
+        async with self._semaphore:
+            await self._ensure_client()
+            if not self.session:
                 await self.login()
-                url = self._get_url(endpoint)
-                try:
+
+            url = self._get_url(endpoint)
+            timeout = timeout_override or self.timeout
+            
+            try:
+                if method.upper() == "POST":
                     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, ex.DeviceUnreachableError)): raise
-            raise ex.ControlIDError(f"Request failed: {type(e).__name__} {e}")
+                else:
+                    response = await self._client.get(url, timeout=timeout)
+                response.raise_for_status()
+                return response.json()
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code == 401:
+                    # Session expired — re-login and retry once
+                    await self.login()
+                    url = self._get_url(endpoint)
+                    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, ex.DeviceUnreachableError)):
+                    raise
+                raise ex.ControlIDError(f"Request failed: {type(e).__name__} {e}")
 
     async def get_system_information(self) -> Dict[str, Any]:
         """Fetch extensive system information (uptime, memory, network, serial, version, etc.)"""
@@ -370,8 +387,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:
@@ -767,6 +786,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.3 → controlid_sdk-0.3.5}/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.3 → controlid_sdk-0.3.5}/src/controlid_sdk.egg-info/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: controlid-sdk
-Version: 0.3.3
+Version: 0.3.5
 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
 Project-URL: Homepage, https://github.com/tulioamancio/controlid-python-sdk
+Project-URL: Source, https://github.com/tulioamancio/controlid-python-sdk
+Project-URL: Bug Tracker, https://github.com/tulioamancio/controlid-python-sdk/issues
+Keywords: controlid,access-control,biometrics,iot,async,sdk
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -12,7 +15,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

{controlid_sdk-0.3.3 → controlid_sdk-0.3.5}/tests/test_client.py

@@ -1,6 +1,7 @@
 import pytest
 from unittest.mock import MagicMock, AsyncMock, patch
 import httpx
+import asyncio
 from controlid import ControlIDClient
 from controlid.exceptions import (
     AuthenticationError,
@@ -96,3 +97,64 @@ async def test_client_request_device_unreachable():
     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"}
+
+
+@pytest.mark.asyncio
+async def test_client_reuses_shared_client():
+    shared_client = httpx.AsyncClient()
+    client = ControlIDClient(host="https://192.168.0.100", client=shared_client)
+    
+    # 1. Ensure it starts with the shared client
+    assert client._client is shared_client
+    
+    # 2. _ensure_client should not overwrite or recreate it
+    await client._ensure_client()
+    assert client._client is shared_client
+    
+    # 3. Context manager exit should not close the shared client
+    async with client:
+        pass
+    assert client._client is shared_client
+    assert not shared_client.is_closed
+    await shared_client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_client_concurrency_locks():
+    client = ControlIDClient(host="https://192.168.0.100")
+    
+    mock_response = MagicMock(spec=httpx.Response)
+    mock_response.status_code = 200
+    mock_response.json = MagicMock(return_value={"session": "test-session"})
+    mock_response.raise_for_status = MagicMock()
+    
+    login_calls = 0
+    
+    async def mock_post(*args, **kwargs):
+        nonlocal login_calls
+        login_calls += 1
+        # sleep a bit to simulate network latency and test concurrency locking
+        await asyncio.sleep(0.1)
+        return mock_response
+        
+    with patch("httpx.AsyncClient.post", new_callable=AsyncMock, side_effect=mock_post):
+        # Trigger multiple logins concurrently using asyncio.gather
+        sessions = await asyncio.gather(
+            client.login(),
+            client.login(),
+            client.login()
+        )
+        # Ensure only 1 HTTP POST login request was actually sent
+        assert login_calls == 1
+        assert all(s == "test-session" for s in sessions)