Alpha 3 release ready #40

devraj · 2024-05-05T00:10:44Z

📢 Preamble

This release solidifies the vision of this API client. Our current vision is to ship:

A Python idiomatic client with documentation and examples
A command line utility to interact with the Gallagher API and aid with automation
A Terminal Interface that provides a superb experience for power users including the use of LLMs to query using natural language (English supported for now)

This release provides a near complete version of the Python API and the related tools, creating a foundation and making is ready for release.

✨ New

Vendors in @betodealmeida/shillelagh by @betodealmeida who gracefully chimed in on Synchronisation of command centre data with a local data source (preferably a SQL backend) #9
Adds Typer based command line interface, thanks to @tiangolo for maintaining it

💅 Improvements

Adds task endpoint for debugging the Gallagher REST endpoints, for example use task debug:get -- alarms to trigger a get request. This will use httpie to execute the request and append necessary headers and parameters
Dependencies have been updated across the various deliverables to ensure we keep up security protocols and enhancements provided by upstream packages
Documentation across the entire project, getting ready for the final release, moves to using bruce-szalwinski/mkdocs-typer by @bruce-szalwinski for producing cli documentation.
Drastic improvements in testsuite performance by transforming network requests into fixtures for examples we can fetch alarms and then perform multiple validation operations on the data:

@pytest.fixture
async def alarm_summary() -> AlarmSummaryResponse:
    """ Get a list of item types and iterates through it
    these are a summary response

    """
    response = await Alarms.list()
    return response

🛠️ Fixes

Handles API endpoints errors properly and raises exceptions rather than letting the API client fail Handle feature not licensed errors #8
Renames various incorrectly named DTO classes, this is due to the rapidly evolving nature of the project and should stabilise past these initial alpha/beta releases.

adds shillelagh to attempt implementing a sql layer on top of the library and see if it helps with #9 todo items for me are: - see if pyndatic can help define sqlalchemy schema - as per #31 i want to have a sqlclahemy dialect - be able to sync two sources one being the rest endpoints using sqlalchemy

adds an endpoint for division cli endpoint in anticipation of the fact that we want start adding some mutative endpoints to the api client and the cli

there are various features on gallagher's documentaiton listed as coming soon, these should be identified by the api client as such and not unavailable or missing

for consistency i've renamed the detail response to summary and will use the detail object to represent the detail endpoints there are likely to be more details around this as the api expands, documentation should reflect this

aiming to complete the api design documentaiton as i complete the implementation hence refactoring the docs to accomodate for the tui and cli (these will be more use focused docs than developer). keeping the structure simple for now and will divide it into folders if required and the items get bigger

@bruce-szalwinski

thanks to this repository https://github.com/mkdocs/catalog i found mkdocs-typer by @bruce-szalwinski https://github.com/bruce-szalwinski/mkdocs-typer this greatly simplifies documenting the command line inteface by automatically generating the reference from the docstrings

adding a task endpoint where you can provide a partial url for the cc and it will add the appropriate headers and prepend it to the aussie rest api proxy gateway. note: this is purely for debugging purposes during development and hence the prefix of `debug`

making sure that response classes have their own parent and are treated separately than just an object recieved from the servers, responses are of two types ones with next, back and updates and ones without, there are two classes that represent that. the parent response classes will know how to follow links through, this will be outlined as part of the implementation

i noticed that at various places i have given into the lure of gpt and some of the sentences did not read well or did not convey my intent properly, this rewirtes much of the content properly

personal data fields are dynamically generated based on the definitions found on the command centre instance, this is a special case in terms of parsing responses from the server as the keys of these response are not dyanamically populated, this commit moves to using a enumeration to ensure that the values for the `type` is one of what the server should send refs #1

brings the cardholder detail model closer to completion with access groups being parsed as per the definition refs #1

just as we do with the discovery message, we cache the pdf fields available on the server onto the capabilities constant, this can be used to parse models that use the personal data fields refs #1

…rsers pdfs are dynamically populated from the data and schema that is sent for the customer detail object, this is a first attempt to see if we can parse the pdf items using mode_validate. WARNING: nothing here may work and we may end up changing the entire direction of this implementation refs #1

i've just realised that the customer detail response sends the relevant pdf fields as part of the personalDataDefinitions field, if we can parse this and make sense of it then the keys to the dynamic fields will exists in the response and we should not read this from the cache. moreover it would make sense that the personDataDefinitions is the set of keys that are part of the customer response i.e not every field is available or is in use all the time. changing tactic here, and going to try and parse the personalDatadefinitions first and then populate the keys from there refs #1

personalDataDefinition field parsing working given refactoring of the dictionary or sorts and allowing pyndatic to make sense of what the server sends back to the api client the parser fails if the value key is missing from a payload which seems to be the case in some items in the sample data for the command centre refs #1

personal_data_definitions has the validated fields accessible as pyndatic objects this makes the same values accessible as pythonic fields so the developers code can look a little more idiomatic i.e @Email Address can now be accessed as .pdf.email_address refs #1

Personal Data Fields being parsed ahead of exposing PDF aliases

the value in a cardholder personal data field is at times a href changes the validation to accept str or href and removes the optional flag leaving a comment on summary/cardholder.py:105 where the ble_facility_id is int for mobile credentials, this was tested against our test command centre instance, the docs still highlight this as a reserved field. leaving a todo to see if we should come back to this for validationm

fiod2 was missing from our list of credentials, also turns Enums to be uppercase constants in accordance with PEP8 https://docs.python.org/3/howto/enum.html

as we push to get alpha3 out, i am putting a massive effort on all the issues that have the documentation tag on them to get the project to completion

devraj added 30 commits April 15, 2024 11:34

docs: adds reference python projects

126cd3a

fix: cli endpoint for tui

b77dd79

refactor: script names

97c8f44

chore: update dependencies

fbec96c

docs: update description of the site

19a4b0e

chore: update lock file

0a9010b

chore: update packages

ded1ad8

refactor: entrypoint configuration for taskfile

7dd688e

refactor: renames cli entrypoint

b7c5db3

docs: adds manifest documents for cli and tui

72a9953

chore: adds placeholder package for sql interfaces

a52d5f2

chore: adds init for ext package

3335ae7

docs: adds philosophy behind the deliverables

66289ad

docs: placeholder for sql interface REFS #31

2a9c8d5

docs: update philosophy behind various items

af5f68f

feat: adds division list cli endpoint

9041f37

adds an endpoint for division cli endpoint in anticipation of the fact that we want start adding some mutative endpoints to the api client and the cli

refactor: adds an exception that is raised for comming soon features

9171af7

there are various features on gallagher's documentaiton listed as coming soon, these should be identified by the api client as such and not unavailable or missing

docs: adds placeholder docstrings

de1987d

refactor: renames detail summary to summary

1566d8e

for consistency i've renamed the detail response to summary and will use the detail object to represent the detail endpoints there are likely to be more details around this as the api expands, documentation should reflect this

chore: update depdenencies and add developer packages

cde6068

docs: update various design descriptions and inline docs

3154280

docs: adds philosophy to the intro sections

5ecda82

feat: adds 404 override exception

b44c516

docs: adds toolchain information

bdbdd44

refactor: responses now inherit from base response classes #24

3ef8ffe

devraj added 29 commits May 31, 2024 23:02

refactor: documentation organisation

0ef7e00

docs: reprahses introduction and intent of the project

e9638ca

i noticed that at various places i have given into the lure of gpt and some of the sentences did not read well or did not convey my intent properly, this rewirtes much of the content properly

chore: updates packages

38a3c4d

feat: adds css file to dashboard

4f102a7

docs: layout of installation manual

c3ef10a

refactor: adds access group summary to cardholders

cb96a23

brings the cardholder detail model closer to completion with access groups being parsed as per the definition refs #1

chore: update packages

da508e0

chore: update tui and cli packages

f1000af

fix: removes deprecated use of dict on pydantic models

db82a6c

refactor: load pdf fields and cache them in capabilities

0d15787

just as we do with the discovery message, we cache the pdf fields available on the server onto the capabilities constant, this can be used to parse models that use the personal data fields refs #1

refactor: moves to using enums for credential class

05dcaff

chore: update packages

37f5594

docs: hardware configuration notes

9c9c573

Merge pull request #44 from anomaly/issue-001

6f7957e

Personal Data Fields being parsed ahead of exposing PDF aliases

docs: update syntax highlight configuration

2dff00f

chore: fix syntax

9a4e542

chore: update packages

3ce8bc4

Merge remote-tracking branch 'origin/master' into alpha-3

e9eec60

docs: updates headings for sdk docs

34395c7

chore: merge conflicts

e854b23

chore: update packages

945d6a1

fix: missing card type credential

8175949

fiod2 was missing from our list of credentials, also turns Enums to be uppercase constants in accordance with PEP8 https://docs.python.org/3/howto/enum.html

docs: big push towards completing docs

9437871

as we push to get alpha3 out, i am putting a massive effort on all the issues that have the documentation tag on them to get the project to completion

devraj merged commit 9437871 into master Jun 28, 2024
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Alpha 3 release ready #40

Alpha 3 release ready #40

devraj commented May 5, 2024

Alpha 3 release ready #40

Alpha 3 release ready #40

Conversation

devraj commented May 5, 2024

📢 Preamble

✨ New

💅 Improvements

🛠️ Fixes