ci: add maintainer baseline checks

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install package and tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[dev]'
+          python -m pip install build twine
+      - name: Ruff
+        run: ruff check .
+      - name: Tests
+        run: pytest -q
+      - name: Build package
+        run: python -m build
+      - name: Check package metadata
+        run: twine check dist/*
+
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[docs]'
+      - name: Build docs strictly
+        run: sphinx-build -E -W -b html docs docs/_build/html

.github/workflows/docs.yml

@@ -34,9 +34,7 @@ jobs:
         run: pip install -e ".[docs]"
 
       - name: Build Sphinx documentation
-        run: |
-          cd docs
-          sphinx-build -b html . _build/html
+        run: sphinx-build -E -W -b html docs docs/_build/html
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

.github/workflows/release-please.yml

@@ -0,0 +1,19 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@8b8fd2cc23b2e18957157a9d923d75aa0c6f6ad5 # v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.2"
+}

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.3.2](https://github.com/tnware/unifi-controller-api/releases/tag/v0.3.2) - 2025-12-27
+
+See the GitHub release for notes on the latest authentication fix release.
+
+## [0.3.1](https://github.com/tnware/unifi-controller-api/releases/tag/v0.3.1) - 2025-12-08
+
+See the GitHub release for notes on UniFi OS authentication fixes.
+
+## [0.3.0](https://github.com/tnware/unifi-controller-api/releases/tag/v0.3.0) - 2025-04-14
+
+See the GitHub release for notes on the 0.3.0 release.
+
+## [0.2.1](https://github.com/tnware/unifi-controller-api/releases/tag/v0.2.1) - 2025-04-06
+
+See the GitHub release for notes on the 0.2.1 patch release.
+
+## [0.2.0](https://github.com/tnware/unifi-controller-api/releases/tag/v0.2.0) - 2025-04-06
+
+See the GitHub release for notes on the 0.2.0 release.
+
+## [0.1.1](https://github.com/tnware/unifi-controller-api/releases/tag/v0.1.1) - 2025-04-04
+
+See the GitHub release for notes on the 0.1.1 patch release.
+
+## [0.1.0](https://github.com/tnware/unifi-controller-api/releases/tag/v0.1.0) - 2025-04-04
+
+Initial public release.

README.md

@@ -9,7 +9,7 @@ A Python client library for interacting with Ubiquiti UniFi Network Controllers.
 
 ## Core Features
 
-*   **Structured Data Models:** Opitionally parses API responses into typed Python objects (e.g., `UnifiDevice`, `UnifiSite`, `UnifiClient`, `LLDPEntry`, `UnifiWlanConf`).
+*   **Structured Data Models:** Optionally parses API responses into typed Python objects (e.g., `UnifiDevice`, `UnifiSite`, `UnifiClient`, `LLDPEntry`, `UnifiWlanConf`).
 *   **Automatic Model Mapping:** Translates model codes (e.g., `U7PG2`) to friendly names ("UniFi® AC Pro AP") via the `model_name` attribute.
 *   **Convenience Methods:** Includes helpers for data export (`export_csv`, `export_json`).
 *   **Minimal Dependencies:** Requires only `requests`.
@@ -32,7 +32,7 @@ from unifi_controller_api import UnifiController
 
 # 1. Initialize & Authenticate
 controller = UnifiController(
-    controller_url="https://<CONTROLLER_IP_OR_HOSTNAME>", # Use :8443 for UniFi OS, :443 for legacy
+    controller_url="https://<CONTROLLER_IP_OR_HOSTNAME>", # Use :443 for UniFi OS, :8443 for legacy
     username="<LOCAL_ADMIN_USER>",
     password="<PASSWORD>",
     is_udm_pro=True, # Set True for UniFi OS devices (UDM, Cloud Key Gen2+), False for legacy software/hardware controllers
@@ -47,7 +47,7 @@ controller = UnifiController(
 # 2. Fetch Data (Example: Devices for the 'default' site)
 site_name = "default" # Use the internal site name
 try:
-    devices = controller.get_unifi_site_device(site_name=site_name, detailed=True)
+    devices = controller.get_unifi_site_device(site_name=site_name, detailed=True, raw=False)
 
     # 3. Use the Typed Data
     for device in devices:
@@ -59,13 +59,13 @@ except Exception as e:
     print(f"Error fetching devices for site '{site_name}': {e}")
 
 # Other available methods:
-# sites = controller.get_unifi_site()
-# clients = controller.get_clients(site_name)
-# wlans = controller.get_wlan_conf(site_name)
-# alarms = controller.get_alarms(site_name)
-# events = controller.get_events(site_name)
-# rogue_aps = controller.get_rogue_aps(site_name)
-# networks = controller.get_network_conf(site_name)
+# sites = controller.get_unifi_site(include_health=False)
+# clients = controller.get_unifi_site_client(site_name)
+# wlans = controller.get_unifi_site_wlanconf(site_name)
+# alarms = controller.get_unifi_site_alarm(site_name)
+# events = controller.get_unifi_site_event(site_name)
+# rogue_aps = controller.get_unifi_site_rogueap(site_name)
+# networks = controller.get_unifi_site_networkconf(site_name)
 # report = controller.devices_report(site_names=['site1', 'site2'])
 
 # Exporting data:

docs/api/export.rst

@@ -10,7 +10,7 @@ The UniFi Controller API includes utilities for exporting data to various format
    :show-inheritance:
 
 Supported Export Formats
-=======================
+========================
 
 The API supports exporting data to the following formats:
 
@@ -19,7 +19,7 @@ The API supports exporting data to the following formats:
 * **Python Dictionaries** - Convert data to Python dictionaries for custom processing.
 
 Usage Examples
-=============
+==============
 
 The `automodule` directive above will list all available functions. Key functions include:
 
@@ -28,7 +28,7 @@ The `automodule` directive above will list all available functions. Key function
 *   `to_dict_list`: Converts a list of model objects into a list of Python dictionaries. This can be useful for custom export logic or further manipulation before exporting.
 
 Exporting to CSV
----------------
+----------------
 
 .. code-block:: python
 
@@ -57,7 +57,7 @@ Exporting to CSV
         print(f"An error occurred: {e}")
 
 Exporting to JSON
-----------------
+-----------------
 
 .. code-block:: python
 
@@ -114,4 +114,4 @@ Converting to Dictionaries
         else:
             print("No sites found to convert.")
     except Exception as e:
-        print(f"An error occurred: {e}")
+        print(f"An error occurred: {e}")

docs/api/overview.rst

@@ -12,7 +12,7 @@ The UniFi Controller API package is organized into several modules:
 * **Exceptions** - Custom exceptions for error handling
 
 Main Components
-==============
+===============
 
 .. autosummary::
    :nosignatures:
@@ -25,7 +25,7 @@ Main Components
    unifi_controller_api.utils
 
 Getting Started
-==============
+===============
 
 The main entry point is the :class:`unifi_controller_api.UnifiController` class:
 
@@ -50,5 +50,5 @@ The main entry point is the :class:`unifi_controller_api.UnifiController` class:
     devices = controller.get_unifi_site_device('default')
 
     # Export devices to CSV
-    from unifi_controller_api.export import export_to_csv
-    export_to_csv(devices, "devices.csv")
+    from unifi_controller_api.export import export_csv
+    export_csv(devices, "devices.csv")

docs/api/utilities.rst

@@ -1,38 +1,38 @@
-===================
+=====================
 Utilities and Helpers
-===================
+=====================
 
 The UniFi Controller API includes several utility modules to help with common tasks.
 
 Logging Utilities
-================
+=================
 
 .. automodule:: unifi_controller_api.logging
    :members:
    :undoc-members:
    :show-inheritance:
 
 Exception Handling
-================
+==================
 
 .. automodule:: unifi_controller_api.exceptions
    :members:
    :undoc-members:
    :show-inheritance:
 
 Utility Functions
-===============
+=================
 
 .. automodule:: unifi_controller_api.utils
    :members:
    :undoc-members:
    :show-inheritance:
 
 Common Usage Examples
-===================
+=====================
 
 Setting Up Logging
-----------------
+------------------
 
 .. code-block:: python
 
@@ -46,7 +46,7 @@ Setting Up Logging
     logger.error("Failed to connect")
 
 Handling Exceptions
------------------
+-------------------
 
 .. code-block:: python
 
@@ -58,4 +58,4 @@ Handling Exceptions
     except UnifiLoginError as e:
         print(f"Login failed: {e}")
     except UnifiError as e:
-        print(f"Other UniFi error: {e}")
+        print(f"Other UniFi error: {e}")