pyGuardPoint 1.4.2__tar.gz → 1.4.4__tar.gz

{pyguardpoint-1.4.2 → pyguardpoint-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyGuardPoint
-Version: 1.4.2
+Version: 1.4.4
 Summary: Python wrapper for GuardPoint 10 Access Control System
 Author: John Owen
 Maintainer-email: sales@sensoraccess.co.uk

{pyguardpoint-1.4.2 → pyguardpoint-1.4.4}/pyGuardPoint/_guardpoint_controllers.py

@@ -5,7 +5,42 @@ from .guardpoint_error import GuardPointError, GuardPointUnauthorized
 
 
 class ControllersAPI:
+    """
+    API for interacting with controller resources.
+
+    This class provides methods to retrieve information about controllers
+    from a remote API.
+
+    Methods
+    -------
+    get_controllers()
+        Retrieves a list of all controllers.
+
+    get_controller(controller_uid: str)
+        Retrieves a specific controller by its unique identifier.
+    """
     def get_controllers(self, ):
+        """
+        Retrieve a list of controllers from the GuardPoint API.
+
+        This method sends a GET request to the GuardPoint API to fetch a list of controllers.
+        It processes the response and returns a list of `Controller` objects.
+
+        :raises GuardPointUnauthorized: If the API response status code is 401 (Unauthorized).
+        :raises GuardPointError: If the API response status code is 404 (Not Found) or if the response is badly formatted.
+
+        :return: A list of `Controller` objects.
+        :rtype: list
+
+        Example usage:
+
+        .. code-block:: python
+
+            controllers = guardpoint_instance.get_controllers()
+            for controller in controllers:
+                print(controller)
+
+        """
         url = "/odata/API_Controllers"
         headers = {
             'Content-Type': 'application/json',
@@ -37,6 +72,21 @@ class ControllersAPI:
         return controllers
 
     def get_controller(self, controller_uid: str):
+        """
+        Retrieve a controller object by its unique identifier (UID).
+
+        This method sends a GET request to the GuardPoint API to fetch details
+        of a controller specified by the `controller_uid`. If the UID is not
+        a valid UUID, a `ValueError` is raised. If the API response indicates
+        an error or is not properly formatted, a `GuardPointError` is raised.
+
+        :param controller_uid: The unique identifier of the controller to retrieve.
+        :type controller_uid: str
+        :raises ValueError: If the `controller_uid` is not a valid UUID.
+        :raises GuardPointError: If the API response indicates an error or is not properly formatted.
+        :return: A `Controller` object if the controller is found, otherwise `None`.
+        :rtype: Controller or None
+        """
         if not validators.uuid(controller_uid):
             raise ValueError(f"Malformed controller_uid: {controller_uid}")
 

{pyguardpoint-1.4.2 → pyguardpoint-1.4.4}/pyGuardPoint/_guardpoint_customizedfields.py

@@ -5,8 +5,34 @@ from .guardpoint_dataclasses import CardholderCustomizedField
 
 
 class CustomizedFieldsAPI:
+    """
+    API class for updating customized fields of a cardholder.
+
+    Methods
+    -------
+    update_custom_fields(cardholder_uid: str, customFields: CardholderCustomizedField)
+        Updates the custom fields for a specified cardholder.
+    """
 
     def update_custom_fields(self, cardholder_uid: str, customFields: CardholderCustomizedField):
+        """
+        Update custom fields for a specific cardholder.
+
+        This method updates the custom fields of a cardholder identified by the given UID.
+        It sends a PATCH request to the GuardPoint API with the updated custom fields.
+
+        :param cardholder_uid: The unique identifier of the cardholder.
+        :type cardholder_uid: str
+        :param customFields: An instance of `CardholderCustomizedField` containing the custom fields to be updated.
+        :type customFields: CardholderCustomizedField
+
+        :raises ValueError: If the provided `cardholder_uid` is not a valid UUID.
+        :raises GuardPointUnauthorized: If the request is unauthorized (HTTP 401).
+        :raises GuardPointError: If the cardholder is not found (HTTP 404) or any other error occurs.
+
+        :return: True if the update is successful.
+        :rtype: bool
+        """
         if not validators.uuid(cardholder_uid):
             raise ValueError(f'Malformed Cardholder UID {cardholder_uid}')
 

{pyguardpoint-1.4.2 → pyguardpoint-1.4.4}/pyGuardPoint/_guardpoint_diagnostic.py

@@ -5,15 +5,34 @@ from .guardpoint_error import GuardPointError, GuardPointUnauthorized
 
 
 class DiagnosticAPI:
-    '''
-    {
-        "controllersUIDs" :[
-            "B3C0976A-3F8C-4B52-AE65-CB6F88FFD813"
-        ],
-        "command": "7901000000000A28"
-    }
-    '''
+    """
+    A class to interact with the diagnostic API for simulating access events.
+
+    Methods
+    -------
+    simulate_access_event(controller_uid: str, reader_num: int, card_code: str) -> bool
+        Simulates an access event for a given controller, reader, and card code.
+    """
     def simulate_access_event(self, controller_uid: str, reader_num: int, card_code: str):
+        """
+        Simulates an access event by sending a command to the specified controller.
+
+        This method sends a command to the controller identified by `controller_uid` to simulate an access event
+        using the specified `reader_num` and `card_code`. It performs validation on the inputs and handles
+        the response from the server.
+
+        :param controller_uid: The unique identifier of the controller.
+        :type controller_uid: str
+        :param reader_num: The reader number (must be between 0 and 255).
+        :type reader_num: int
+        :param card_code: The card code (must be at least 8 characters long).
+        :type card_code: str
+        :raises ValueError: If `controller_uid` is not a valid UUID, `card_code` is too short, or `reader_num` is greater than 255.
+        :raises GuardPointUnauthorized: If the server responds with a 401 Unauthorized status.
+        :raises GuardPointError: If the server responds with an error or the response is badly formatted.
+        :return: True if the access event simulation was successful, False otherwise.
+        :rtype: bool
+        """
         if not validators.uuid(controller_uid):
             raise ValueError(f"Malformed controller_uid: {controller_uid}")
         if len(card_code) < 8:

{pyguardpoint-1.4.2 → pyguardpoint-1.4.4}/pyGuardPoint/guardpoint.py

@@ -31,17 +31,9 @@ def stop_listening(client: SignalRClient):
         await client._transport.close()
 
     asyncio.run(stop_signal_client())
-    '''if not self.task:
-        return
 
-    self.task.cancel()
-    while not self.task.cancelled():
-        sleep(1)'''
 
-
-class GuardPoint(GuardPointConnection, CardsAPI, CardholdersAPI, AreasAPI, SecurityGroupsAPI,
-                 CustomizedFieldsAPI, PersonalDetailsAPI, ScheduledMagsAPI, CardholderTypesAPI,
-                 OutputsAPI, DiagnosticAPI, ReadersAPI, ControllersAPI, AlarmsAPI, EventsAPI):
+class GuardPoint(GuardPointConnection, CardsAPI, CardholdersAPI, AreasAPI, SecurityGroupsAPI, CustomizedFieldsAPI, PersonalDetailsAPI, ScheduledMagsAPI, CardholderTypesAPI, OutputsAPI, DiagnosticAPI, ReadersAPI, ControllersAPI, AlarmsAPI, EventsAPI):
     """
     A class to interface with the GuardPoint system, providing various APIs for managing cards, cardholders, areas,
     security groups, customized fields, personal details, scheduled mags, cardholder types, outputs, diagnostics,
@@ -52,7 +44,7 @@ class GuardPoint(GuardPointConnection, CardsAPI, CardholdersAPI, AreasAPI, Secur
 
     Methods
     -------
-    __init__(**kwargs)
+    __init__(\**kwargs)
         Initializes the GuardPoint instance with the provided configuration.
     get_cardholder_count()
         Retrieves the total number of cardholders.
@@ -65,6 +57,26 @@ class GuardPoint(GuardPointConnection, CardsAPI, CardholdersAPI, AreasAPI, Secur
     task = None
 
     def __init__(self, **kwargs):
+        """
+        Initialize the connection with the given parameters.
+
+        :param kwargs: Keyword arguments for configuration.
+            - host (str): The hostname or IP address of the server. Defaults to "localhost".
+            - port (int): The port number to connect to. Defaults to None.
+            - auth (GuardPointAuthType): The authentication type. Defaults to GuardPointAuthType.BEARER_TOKEN.
+            - username (str): The username for authentication. Defaults to "admin".
+            - pwd (str): The password for authentication. Defaults to "admin".
+            - key (str): The key for authentication. Defaults to "00000000-0000-0000-0000-000000000000".
+            - token (str): The token for authentication. Defaults to None.
+            - cert_file (str): Path to the certificate file. Defaults to None.
+            - key_file (str): Path to the key file. Defaults to None.
+            - ca_file (str): Path to the CA file. Defaults to None.
+            - timeout (int): The timeout duration in seconds. Defaults to 5.
+            - p12_file (str): Path to the PKCS#12 file. Defaults to None.
+            - p12_pwd (str): Password for the PKCS#12 file. Defaults to an empty string.
+
+        :raises ValueError: If the host is not provided or is invalid.
+        """
         # Set default values if not present
         host = kwargs.get('host', "localhost")
         port = kwargs.get('port', None)
@@ -90,6 +102,18 @@ class GuardPoint(GuardPointConnection, CardsAPI, CardholdersAPI, AreasAPI, Secur
                          p12_file=p12_file, p12_pwd=p12_pwd)
 
     def get_cardholder_count(self):
+        """
+        Retrieve the total count of cardholders from the GuardPoint system.
+
+        This method sends a GET request to the GuardPoint API to fetch the total number of cardholders.
+        It handles various error scenarios, including unauthorized access and improperly formatted responses.
+
+        :raises GuardPointUnauthorized: If the API response indicates unauthorized access (HTTP 401).
+        :raises GuardPointError: If the API response is not properly formatted or if there is no response body.
+
+        :return: The total number of cardholders.
+        :rtype: int
+        """
         url = self.baseurl + "/odata/GetCardholdersCount"
         code, json_body = self.gp_json_query("GET", url=url)
 
@@ -113,6 +137,24 @@ class GuardPoint(GuardPointConnection, CardsAPI, CardholdersAPI, AreasAPI, Secur
         return int(json_body['totalItems'])
 
     def get_signal_client(self):
+        """
+        Creates and configures a SignalR client for connecting to the EventsHub.
+
+        This method initializes a `SignalRClient` instance with the appropriate URL and sets up
+        the necessary headers for authentication based on the specified authentication type.
+        It also configures a custom WebSocket transport for the client with various parameters.
+
+        :returns: Configured `SignalRClient` instance ready for use.
+        :rtype: SignalRClient
+
+        :raises ValueError: If the authentication type is not supported.
+
+        Example usage::
+
+            client = self.get_signal_client()
+            client.start()
+
+        """
         client = SignalRClient(self.baseurl + "/Hub/EventsHub")
         headers = {}
         if self.authType == GuardPointAuthType.BASIC:
@@ -134,11 +176,19 @@ class GuardPoint(GuardPointConnection, CardsAPI, CardholdersAPI, AreasAPI, Secur
         return client
 
     def start_listening(self, client: SignalRClient):
+        """
+        Start listening to the SignalR client by running it in an asynchronous task.
+
+        This method creates and runs an asynchronous task to execute the `run` method of the provided
+        `SignalRClient` instance. The task is named "sigR_task" for identification purposes. If the task
+        is cancelled, a message indicating the cancellation is printed.
+
+        :param client: An instance of `SignalRClient` that will be run in an asynchronous task.
+        :type client: SignalRClient
+
+        :raises asyncio.CancelledError: If the asynchronous task is cancelled.
+        """
         async def run_signal_client() -> None:
-            '''group = gp_asyncio.gather(
-                client.run(),
-            )
-            await group'''
             self.task = asyncio.create_task(client.run(), name = "sigR_task")
             await self.task
 

{pyguardpoint-1.4.2 → pyguardpoint-1.4.4}/pyGuardPoint.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyGuardPoint
-Version: 1.4.2
+Version: 1.4.4
 Summary: Python wrapper for GuardPoint 10 Access Control System
 Author: John Owen
 Maintainer-email: sales@sensoraccess.co.uk

{pyguardpoint-1.4.2 → pyguardpoint-1.4.4}/setup.py

@@ -4,7 +4,7 @@ long_description = open('README.rst').read()
 
 setup(name="pyGuardPoint",
       packages=find_packages(),
-      version="1.4.2",
+      version="1.4.4",
       author="John Owen",
       description="Python wrapper for GuardPoint 10 Access Control System",
       long_description_content_type='text/markdown',