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
