Merge pull request #76 from anomaly/alpha-10

Alpha 10

Author: devraj

docs/docs/installation.md

@@ -41,7 +41,7 @@ following this you can call any of the SDK methods and the client will performan
 - `NoAPIKeyProvidedError` - If the API key is not set.
 - `ValueError` - If the API key does not conform to the expected format (which looks like eight tokens separated by `-`).
 
-#### Using TLS Certificates
+#### Using TLS certificates
 
 Command Centre optionally allows you to use self signed client side TLS certificates for authentication. You can use this along side your API key as an additional layer of security.
 
@@ -74,7 +74,7 @@ The rest of the requests and operations remain the same, the library will use an
 
 > Our testsuites are configured to run with and without TLS certificates to ensure that we support both modes of operation.
 
-In instances (such as Github actions, where we store the certificate and key in the Github secrets manager) where you can't store the certficiate and key in the filesystem, you can use Python's `tempfile` module to create temporary files and clean up once you are done using them.
+In instances (such as Github actions, where we store the certificate and key in the Github secrets manager) where you can't store the certificate and key in the filesystem, you can use Python's `tempfile` module to create temporary files and clean up once you are done using them.
 
 ```python
 import tempfile
@@ -112,13 +112,13 @@ cc.file_tls_certificate = temp_file_certificate.name
 cc.file_private_key = temp_file_private_key.name
 ```
 
-### Command Line Interface
+### Command line interface
 
-### Terminal User Interface
+### Terminal user interface
 
-### SQL Support
+### SQL support
 
-## Developer Notes
+## Developer notes
 
 This library uses [httpx](https://www.python-httpx.org) as the HTTP transport and [pydantic](https://pydantic.dev) to construct and ingest payloads. We use [taskfile](https://taskfile.dev) to run tasks. Our test suite is setup using `pytest`.
 
@@ -140,7 +140,7 @@ Some of the `task` targets take parameters e.g.
 
 `task test` will run the entire test suite, while `task test -- test_cardholder.py` will run only the tests in `test_cardholder.py`.
 
-### Building the Docs
+### Building the docs
 
 The documentation is build using [mkdocs](https://www.mkdocs.org) and hosted on [Github pages](https://anomaly.github.io/gallagher/). The project repository is configured to build and publish the documentation on every commit to the `master` branch.
 

docs/docs/python-sdk.md

@@ -26,7 +26,7 @@ poetry add gallagher
 
 For production application please make sure you target a particular version of the API client to avoid breaking changes.
 
-## Data Transfer Objects (DTO) Premiere
+## Data Transfer Objects (DTO) premiere
 
 The Data Transfer Objects or DTOs are the centre piece of the Python SDK. These are built using the much loved [pyndatic](https://pydantic.dev) library. The aim is strict validation of responses and request payloads to ensure that the SDK never falls out of line with Gallagher' REST API.
 
@@ -47,7 +47,7 @@ In addition to DTOs, you will see a number of :
 
 If you are fetching a `detail` then they are returned on their own as part of the response. They typically contain `href` to related objects.
 
-## API Endpoint Lifecycle
+## API endpoint lifecycle
 
 You do not need to look under the hood to work with the API client. This section was written for you to understand how we implement Gallagher's requirements for standard based development. Each endpoint inherits from a base class called `APIEndpoint` defined in `gallagher/cc/core.py` and provides a configuration that describes the behaviour of the endpoint (in accordance with the Command Centre API).
 
@@ -115,7 +115,7 @@ cc.api_base = URL.CLOUD_GATEWAY_US
 
 In cases where you are targeting a local Command Centre, you can set the `api_base` to the FQDN or IP address of the Command Centre that's locally accessible on the network.
 
-### Proxy Support
+### Proxy support
 
 Thanks to `httpx` we have proxy support built in out of the box. By default the `proxy` is set to `None` indicating that one isn't in use. If you wish to use a proxy for your use case, then simply set the `proxy` attribute on the `cc` object like you would the `api_base` or `api_key`.
 
@@ -270,7 +270,7 @@ while items_summary.next:
     determined from the response object. This ensures that we can update the SDK as the API changes
     leaving your code intact.
 
-# Updates and Changes
+## Follow for changes
 
 Entities like `Cardholders`, `Alarms`, `Items`, and `Event` provide `updates` or `changes`, that can be monitored for updates. Essentially these are long poll endpoints that:
 
@@ -340,6 +340,10 @@ async def get_config(cls) -> EndpointConfig:
     )
 ```
 
+!!! warning
+
+    As a breaking change in `8.90` the operator must have the 'Create Events and Alarms' privilege in the division of the source item, if your request specifies a source item. Current versions only require that the operator has that privilege on at least one division.
+
 ## Error Handling
 
 ### Exceptions
@@ -363,6 +367,7 @@ Personal Data Definitions are fields associated to a cardholder and are defined
 - children of the `personalDataFields` key in the cardholder detail
 - accessible via key name prefixed with the `@` symbol i.e the personal data field `Email` is accessible via the key `@Email`
 
+
 !!! tip
 
     Note that the `personDataFields` has a `list` of objects, and each object has a single key which is the nae of the personal data field and the value is the related data.
@@ -395,10 +400,33 @@ and we had used the API client to fetch the cardholder detail (partial example):
 cardholder = await Cardholder.retrieve(340)
 ```
 
-you could access the `Email` field either via iterating over `cardholder.personal_data_definitions` and looking to match the `key` attribute of the object to `@Email` or using the parsed shortcut `cardholder.pdf.email`.
+`cardholder` would have two fields:
+- `personal_data_definitions` which is a list of `CardholderPersonalDataDefinition` objects
+- `pdf` which is a parsed object of the personal data fields
 
-The above is achieved by dynamically populating a placeholder object with dynamically generated keys. These are parsed and populate _once_ when the object has successfully parsed the `JSON` payload.
+`cardholder.personal_data_definitions` is iterable, each instance exposing a `name` and `contents` fields. Use the `value` attribute of `contents` to access the PDF value:
+
+```python
+for pdf in cardholder.personal_data_definitions:
+    if pdf.name == '@Email':
+        print(pdf.name, pdf.contents.value)
+```
 
 !!! tip
 
     See pyndatic's [Model validator](https://docs.pydantic.dev/latest/concepts/validators/#model-validators) feature in v2, in particular the `@model_validator(mode='after')` constructor.
+
+The `cardholder` object will also expose a special attribute called `pdf`. Each instance available in the `personal_data_definitions` field will be mapped to a Pythonic `snake_cased` key, that lets you access the same  `CardholderPersonalDataDefinition` object via the `@` prefixed key name. So the above example of accessing the `@Email` field can be done as follows:
+
+```python
+cardholder.pdf.email.value
+```
+
+The `pdf` attribute is dynamically populated object with dynamically generated keys. Here are some examples of how `PDF` field names are mapped to `snake_case` keys:
+
+- `@Cardholder UID` would become `pdf.cardholder_uid`
+- `@City` would become `pdf.city`
+- `@Company Name` would become `pdf.company_name`
+- `@PINNumber` would become `pdf.pin_number`
+
+Both approaches have their merits and you should use the one that suits your use case.

gallagher/cc/core.py

@@ -526,7 +526,7 @@ async def follow(
                         f"{url}",  # required to turn pydantic object to str
                         headers=_get_authorization_headers(),
                         params=params,
-                        timeout=TRANSPORT.TIMEOUT_POLL, # Next Gallagher CC wait
+                        timeout=TRANSPORT.TIMEOUT_POLL,
                     )
 
                     if response.status_code == HTTPStatus.OK:

gallagher/dto/detail/cardholder.py

@@ -2,12 +2,14 @@
 from typing import Optional, Any
 from typing_extensions import Self
 
-from pydantic import model_validator, Field
+from pydantic import model_validator
 
 from ..utils import (
     AppBaseModel,
     IdentityMixin,
     HrefMixin,
+    OptionalHrefMixin,
+    _to_snake_case_key,
 )
 
 from ..ref import (
@@ -111,8 +113,8 @@ class CardholderDetail(
     # operator_groups
     # competencies
 
-    edit: HrefMixin
-    update_location: HrefMixin
+    edit: OptionalHrefMixin = None
+    update_location: OptionalHrefMixin = None
     notes: Optional[str] = None
 
     # notifications
@@ -164,9 +166,9 @@ def populate_pdf_accessor(self) -> Self:
             # if you compare these in the tests, they should be the same
             setattr(
                 self.pdf, 
-                # replace spaces with underscores and make it lowercase
+                # turn the key into a snake case key
                 # ignore the prefixed @ symbol
-                pdf_field.name[1:].replace(' ', '_').lower(),
+                _to_snake_case_key(pdf_field.name),
                 pdf_field.contents
             )
 

gallagher/dto/summary/pdf.py

@@ -4,13 +4,13 @@
 
 from ..utils import (
     AppBaseModel,
-    HrefMixin,
+    OptionalHrefMixin,
     IdentityMixin,
 )
 
 class PdfSummary(
     AppBaseModel,
-    HrefMixin,
+    OptionalHrefMixin,
     IdentityMixin,
 ):
     """ Personal Data Field Summary

gallagher/dto/utils.py

@@ -18,7 +18,9 @@
 from typing import (
     Optional,
 )
-from functools import cached_property
+
+import re
+
 from typing_extensions import Annotated
 
 from datetime import datetime
@@ -52,10 +54,36 @@ def _to_lower_camel(name: str) -> str:
     return upper[:1].lower() + upper[1:]
 
 
+def _to_snake_case_key(key: str) -> str:
+    """ Changes keys to snake_case
+
+    This is used to convert keys from the Gallagher API to
+    snake_case. Primarily used to change PDF field names to
+    snake_case fields that are dynamically created.
+
+    1. Strip leading '@'
+    2. Replace spaces or dashes with underscores
+    3. Split acronym/word boundary: e.g. PINNumber → PIN_Number
+    4. Split camelCase boundary: e.g. fooBar → foo_Bar
+    5. Collapse multiple underscores
+    6. Lowercase
+    """
+    # 1) remove leading '@'
+    key = key.lstrip('@')
+    # 2) normalize spaces/dashes to underscore
+    key = re.sub(r'[\s\-]+', '_', key)
+    # 3) acronym boundary: uppercase-seq → uppercase + lowercase
+    key = re.sub(r'(?<=[A-Z])(?=[A-Z][a-z])', '_', key)
+    # 4) camelCase boundary: lowercase/digit → uppercase
+    key = re.sub(r'(?<=[a-z0-9])(?=[A-Z])', '_', key)
+    # 5) collapse multiple underscores
+    key = re.sub(r'__+', '_', key)
+    # 6) lowercase
+    return key.lower()
+
 # Ensure that the primitive wrappers such as Mixins appear
 # before the generic classes for parsing utilities
 
-
 class IdentityMixin(BaseModel):
     """Identifier