aiofortiosapi 0.1.0__tar.gz

aiofortiosapi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint & type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff mypy aiohttp
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+      - run: mypy src
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest
+
+  build:
+    name: Package build check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

aiofortiosapi-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+# BEFORE FIRST USE: configure a PyPI Trusted Publisher for this repo.
+# Go to https://pypi.org/manage/account/publishing/ and add:
+#   owner/repo: kimfrellsen/aiofortiosapi
+#   workflow: release.yml
+#   environment: release
+# No API token needs to be stored — OIDC handles auth.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write  # required for OIDC trusted publishing
+  contents: read
+
+jobs:
+  build-and-publish:
+    name: Build & publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

aiofortiosapi-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Typing
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Packaging
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Ruff
+.ruff_cache/

aiofortiosapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-26
+
+### Added
+- Initial scaffold: `FortiOSClient` with Bearer token auth and injected `aiohttp.ClientSession`.
+- `get_system_status()`, `get_resource_usage()`, `get_detected_devices()` endpoints.
+- `async_validate()` for cheap credential validation in HA config_flow.
+- `FortiOSClient.get(path, *, params=None)` — generic raw-envelope GET for
+  endpoints without a dedicated typed method (e.g. HA coordinator polling).
+- Exception hierarchy: `FortiOSConnectionError`, `FortiOSAuthenticationError`,
+  `FortiOSNotFoundError`, `FortiOSResponseError`.
+- Typed frozen dataclasses: `SystemStatus`, `ResourceUsage`, `DetectedDevice`.
+- `verify_ssl` flag for self-signed FortiGate certificates.
+- `vdom` parameter support.
+- Full test suite using `aresponses` (no live network required).
+- Ruff + mypy strict configuration.
+- GitHub Actions CI (lint + test on Python 3.12/3.13/3.14) and OIDC-based PyPI release workflow.
+
+### Changed
+- `DetectedDevice.is_online` uses the API-reported `is_online` flag; when a
+  firmware omits the field it falls back to `last_seen` freshness (seen within
+  the new `device_online_threshold` client argument, default 300 s).
+  `DetectedDevice.list_from_api()` accepts keyword-only `now` and
+  `online_threshold` for deterministic parsing.
+- `ResourceUsage` model matches real firmware: memory under `"mem"`/`"current"`,
+  `sessions` and `session_setup_rate` sum IPv4+IPv6 buckets; `uptime` was
+  dropped (not present on `monitor/system/resource/usage`).
+
+### Fixed
+- `DetectedDevice.ip` no longer becomes the string `"None"` when the API returns
+  a null `ipv4_address`; all string fields map null to `""`.
+- Parsing no longer raises on scalar list entries (`_first`), null envelopes
+  (`"results": null`), or non-numeric stat values; safe defaults are used.
+- Error messages for failed requests surface FortiOS detail keys (`cli_error`,
+  `message`, `error`, `http_message`) instead of an often-empty `error`,
+  falling back to the truncated raw body.

aiofortiosapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kim <kim@frellsen.se>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiofortiosapi-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: aiofortiosapi
+Version: 0.1.0
+Summary: Async FortiOS REST API client for Home Assistant
+Project-URL: Homepage, https://github.com/kimfrellsen/aiofortiosapi
+Project-URL: Repository, https://github.com/kimfrellsen/aiofortiosapi
+Project-URL: Changelog, https://github.com/kimfrellsen/aiofortiosapi/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/kimfrellsen/aiofortiosapi/issues
+Author-email: Kim <kim@frellsen.se>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,asyncio,fortigate,fortinet,fortios,home-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: test
+Requires-Dist: aresponses>=3; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# aiofortiosapi
+
+Async Python client for the FortiOS REST API, built for the [Home Assistant](https://www.home-assistant.io/) `fortios` integration.
+
+> **Community project** — not affiliated with or supported by Fortinet TAC.
+
+## Install
+
+```bash
+pip install aiofortiosapi
+```
+
+## Usage
+
+The library requires an injected `aiohttp.ClientSession` — Home Assistant provides one via
+`async_get_clientsession(hass)`. You own the session lifecycle; this library never creates or closes it.
+
+```python
+import asyncio
+import aiohttp
+from aiofortiosapi import FortiOSClient, FortiOSAuthenticationError, FortiOSConnectionError
+
+async def main() -> None:
+    session = aiohttp.ClientSession()
+    try:
+        client = FortiOSClient(
+            host="192.168.1.1",
+            token="your-rest-api-token",
+            session=session,
+            verify_ssl=False,   # set True in production with a valid cert
+        )
+        status = await client.get_system_status()
+        print(status.hostname, status.version)
+
+        usage = await client.get_resource_usage()
+        print(f"CPU {usage.cpu_percent}%  MEM {usage.memory_percent}%")
+
+        devices = await client.get_detected_devices()
+        for d in devices:
+            print(d.mac, d.hostname, d.ip, "online" if d.is_online else "offline")
+    except FortiOSAuthenticationError:
+        print("Bad token — re-enter credentials")
+    except FortiOSConnectionError:
+        print("Cannot reach the FortiGate — check host/port")
+    finally:
+        await session.close()
+
+asyncio.run(main())
+```
+
+## Generating a FortiOS REST API token
+
+1. In the FortiGate GUI go to **System → Administrators → Create New → REST API Admin**.
+2. Set a **Trusted Host** (the IP of your Home Assistant instance) to restrict token use.
+3. Assign a read-only profile (`prof_admin` or custom).
+4. Copy the generated token — it is shown only once.
+
+The library uses `Authorization: Bearer <token>` (not the legacy `?access_token=` query string).
+
+### Device online state
+
+`DetectedDevice.is_online` uses the flag reported by FortiOS. On firmware that
+omits the field, it falls back to deriving online state from `last_seen`
+freshness: a device counts as online when seen within
+`DEFAULT_ONLINE_THRESHOLD` seconds (300). Tune the fallback per client:
+
+```python
+client = FortiOSClient(..., device_online_threshold=600)
+```
+
+## Scope
+
+`aiofortiosapi` is intentionally minimal:
+
+- **Three typed monitor endpoints** (`get_system_status`, `get_resource_usage`,
+  `get_detected_devices`) used by the Home Assistant integration.
+- A generic `get(path)` for any other endpoint that returns the raw JSON envelope.
+- **No** config-write, CMDB, file upload, SSH fallback, or CLI helpers.
+- **No** session/cookie login flow — Bearer token only.
+
+This keeps the dependency tree small (runtime dep: `aiohttp` only) and passes HA integration
+quality review requirements.
+
+## Exception hierarchy
+
+| Exception | When raised | HA mapping |
+|---|---|---|
+| `FortiOSConnectionError` | Transport/timeout failure | `ConfigEntryNotReady` |
+| `FortiOSAuthenticationError` | HTTP 401 / 403 | `ConfigEntryAuthFailed` |
+| `FortiOSNotFoundError` | HTTP 404 | log / inspect |
+| `FortiOSResponseError` | Bad JSON, 5xx, other 4xx | log / raise |
+
+## License
+
+MIT

aiofortiosapi-0.1.0/README.md

@@ -0,0 +1,95 @@
+# aiofortiosapi
+
+Async Python client for the FortiOS REST API, built for the [Home Assistant](https://www.home-assistant.io/) `fortios` integration.
+
+> **Community project** — not affiliated with or supported by Fortinet TAC.
+
+## Install
+
+```bash
+pip install aiofortiosapi
+```
+
+## Usage
+
+The library requires an injected `aiohttp.ClientSession` — Home Assistant provides one via
+`async_get_clientsession(hass)`. You own the session lifecycle; this library never creates or closes it.
+
+```python
+import asyncio
+import aiohttp
+from aiofortiosapi import FortiOSClient, FortiOSAuthenticationError, FortiOSConnectionError
+
+async def main() -> None:
+    session = aiohttp.ClientSession()
+    try:
+        client = FortiOSClient(
+            host="192.168.1.1",
+            token="your-rest-api-token",
+            session=session,
+            verify_ssl=False,   # set True in production with a valid cert
+        )
+        status = await client.get_system_status()
+        print(status.hostname, status.version)
+
+        usage = await client.get_resource_usage()
+        print(f"CPU {usage.cpu_percent}%  MEM {usage.memory_percent}%")
+
+        devices = await client.get_detected_devices()
+        for d in devices:
+            print(d.mac, d.hostname, d.ip, "online" if d.is_online else "offline")
+    except FortiOSAuthenticationError:
+        print("Bad token — re-enter credentials")
+    except FortiOSConnectionError:
+        print("Cannot reach the FortiGate — check host/port")
+    finally:
+        await session.close()
+
+asyncio.run(main())
+```
+
+## Generating a FortiOS REST API token
+
+1. In the FortiGate GUI go to **System → Administrators → Create New → REST API Admin**.
+2. Set a **Trusted Host** (the IP of your Home Assistant instance) to restrict token use.
+3. Assign a read-only profile (`prof_admin` or custom).
+4. Copy the generated token — it is shown only once.
+
+The library uses `Authorization: Bearer <token>` (not the legacy `?access_token=` query string).
+
+### Device online state
+
+`DetectedDevice.is_online` uses the flag reported by FortiOS. On firmware that
+omits the field, it falls back to deriving online state from `last_seen`
+freshness: a device counts as online when seen within
+`DEFAULT_ONLINE_THRESHOLD` seconds (300). Tune the fallback per client:
+
+```python
+client = FortiOSClient(..., device_online_threshold=600)
+```
+
+## Scope
+
+`aiofortiosapi` is intentionally minimal:
+
+- **Three typed monitor endpoints** (`get_system_status`, `get_resource_usage`,
+  `get_detected_devices`) used by the Home Assistant integration.
+- A generic `get(path)` for any other endpoint that returns the raw JSON envelope.
+- **No** config-write, CMDB, file upload, SSH fallback, or CLI helpers.
+- **No** session/cookie login flow — Bearer token only.
+
+This keeps the dependency tree small (runtime dep: `aiohttp` only) and passes HA integration
+quality review requirements.
+
+## Exception hierarchy
+
+| Exception | When raised | HA mapping |
+|---|---|---|
+| `FortiOSConnectionError` | Transport/timeout failure | `ConfigEntryNotReady` |
+| `FortiOSAuthenticationError` | HTTP 401 / 403 | `ConfigEntryAuthFailed` |
+| `FortiOSNotFoundError` | HTTP 404 | log / inspect |
+| `FortiOSResponseError` | Bad JSON, 5xx, other 4xx | log / raise |
+
+## License
+
+MIT

aiofortiosapi-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aiofortiosapi"
+dynamic = ["version"]
+description = "Async FortiOS REST API client for Home Assistant"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kim", email = "kim@frellsen.se" }]
+requires-python = ">=3.12"
+dependencies = ["aiohttp>=3.9"]
+keywords = ["fortios", "fortigate", "fortinet", "home-assistant", "asyncio", "api-client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Networking :: Monitoring",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/kimfrellsen/aiofortiosapi"
+Repository = "https://github.com/kimfrellsen/aiofortiosapi"
+Changelog = "https://github.com/kimfrellsen/aiofortiosapi/blob/main/CHANGELOG.md"
+Issues = "https://github.com/kimfrellsen/aiofortiosapi/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "aresponses>=3",
+    "pytest-cov>=5",
+]
+
+[tool.hatch.version]
+path = "src/aiofortiosapi/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aiofortiosapi"]
+
+# ---------------------------------------------------------------------------
+# pytest
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "--cov=src/aiofortiosapi --cov-report=term-missing"
+
+# ---------------------------------------------------------------------------
+# ruff
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 99
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "SIM"]
+ignore = ["SIM102"]  # nested if acceptable in parse code
+
+[tool.ruff.lint.isort]
+known-first-party = ["aiofortiosapi"]
+
+# ---------------------------------------------------------------------------
+# mypy
+# ---------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]

aiofortiosapi-0.1.0/src/aiofortiosapi/__init__.py

@@ -0,0 +1,31 @@
+"""aiofortiosapi — async FortiOS REST API client for Home Assistant."""
+
+from .client import FortiOSClient
+from .const import DEFAULT_ONLINE_THRESHOLD
+from .exceptions import (
+    FortiOSAuthenticationError,
+    FortiOSConnectionError,
+    FortiOSError,
+    FortiOSNotFoundError,
+    FortiOSResponseError,
+)
+from .models import DetectedDevice, ResourceUsage, SystemStatus
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FortiOSClient",
+    # exceptions
+    "FortiOSError",
+    "FortiOSConnectionError",
+    "FortiOSAuthenticationError",
+    "FortiOSNotFoundError",
+    "FortiOSResponseError",
+    # models
+    "SystemStatus",
+    "ResourceUsage",
+    "DetectedDevice",
+    # constants
+    "DEFAULT_ONLINE_THRESHOLD",
+    "__version__",
+]