Metadata-Version: 2.4
Name: hfortix-fortimanager
Version: 0.1.0
Summary: Modern, fully-typed Python SDK for FortiManager JSON-RPC API (2,376 endpoints, FMG 7.6.6)
Author-email: "Herman W. Jacobsen" <herman@wjacobsen.fo>
License: Proprietary
Project-URL: Homepage, https://github.com/hermanwjacobsen/hfortix-fortimanager
Project-URL: Repository, https://github.com/hermanwjacobsen/hfortix-fortimanager
Project-URL: Issues, https://github.com/hermanwjacobsen/hfortix-fortimanager/issues
Keywords: fortinet,fortimanager,fmg,jsonrpc,api,sdk,automation,security,network,orchestration,adom,policy-package,configuration,typed
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Topic :: System :: Systems Administration
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hfortix-core>=0.5.163
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Dynamic: license-file

# HFortix-FortiManager

[![PyPI version](https://badge.fury.io/py/hfortix-fortimanager.svg)](https://pypi.org/project/hfortix-fortimanager/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Proprietary-blue.svg)](LICENSE)
[![Typing: Typed](https://img.shields.io/badge/typing-typed-green.svg)](https://peps.python.org/pep-0561/)

**HFortix-FortiManager** is a modern, fully-typed Python SDK for the FortiManager
JSON-RPC API — 2,376 endpoints generated from the official FMG 7.6.6 API
specification, with full `.pyi` type stubs for IDE autocomplete on every call.

## 🚀 Quick Start

```bash
pip install hfortix-fortimanager
```

```python
from hfortix_fortimanager import FortiManager

# API key auth (FMG 7.4.7+ / 7.6.2+) — no login/logout needed
fmg = FortiManager(host="fmg.example.com", api_key="your-api-key")

# Session auth — context manager handles login/logout
with FortiManager(host="fmg.example.com", username="admin", password="pw") as fmg:
    # Device inventory
    devices = fmg.api.dvmdb.adom.device.get(adom="root")
    for dev in devices:
        print(dev.name, dev.ip, dev.os_ver)

    # Firewall address objects (ADOM-scoped)
    fmg.api.pm.config.adom.obj.firewall.address.add(
        adom="root",
        name="web-server",
        subnet=["10.0.1.100", "255.255.255.255"],
    )

    # Firewall policy in a policy package — with placement control
    fmg.api.pm.config.adom.pkg.firewall.policy.add(
        adom="root",
        pkg="default",
        name="Allow-Web",
        srcintf=["port1"], dstintf=["port2"],
        srcaddr=["all"], dstaddr=["web-server"],
        service=["HTTPS"], action="accept", schedule=["always"],
        before="42",   # insert before policyid 42 (omit to append)
    )
```

## ✨ Key Features

- **🎯 2,376 endpoints** — Device DB (`dvmdb`), Policy & Objects (`pm`: ADOM
  objects, device-level config, policy packages, policy blocks, system/WAN
  templates), and `task` monitoring
- **💪 Fully typed** — `.pyi` stubs for every endpoint; `Literal[...]` enums for
  every documented value; PEP 561 `py.typed`
- **🔑 Dual auth** — session (username/password with automatic re-login) or
  API key (Bearer, FMG 7.4.7+/7.6.2+, incl. `api_user` for 7.6.6+)
- **🧭 Navigation mirrors the API** — URL scoping segments are kept:
  `/pm/config/adom/{adom}/obj/firewall/address` →
  `fmg.api.pm.config.adom.obj.firewall.address`
- **📦 Minimal payloads** — only the parameters you pass are sent; FMG applies
  its own server-side defaults (no surprise field writes)
- **🛡️ Production plumbing from hfortix-core** — retry with backoff,
  optional rate limiting and circuit breaker, audit logging, sanitized logs
- **🔒 Workspace mode** — `dvmdb.adom.workspace` lock / commit / unlock
  endpoints for ADOMs in workspace mode

## 🧰 GET options

All JSON-RPC read options are typed parameters:

```python
fmg.api.dvmdb.adom.device.get(
    adom="root",
    fields=["name", "ip", "os_ver"],
    filter=["conf_status", "==", "insync"],
    range=[0, 50],
    loadsub=0,
)
```

## 🪄 Escape hatch — raw JSON-RPC

Anything not (yet) exposed as a typed endpoint can be called directly:

```python
result = fmg.client.execute(
    method="exec",
    params=[{"url": "/securityconsole/install/package",
             "data": {"adom": "root", "pkg": "default"}}],
)
```

## ⚠️ Known limitations (0.1.x)

- **No `securityconsole` / install-deploy endpoints yet** — configuration
  management is fully covered, but installing policy packages to devices
  currently requires the raw `fmg.client.execute()` escape hatch (see above).
  Planned for an upcoming release.
- **`model_registry` / `as_models()` / typed response models are experimental
  placeholders** — they currently return `None` / fall back to generic objects.
- **Sync only** — no async client yet (unlike hfortix-fortios).

## 🔗 Related Packages

This package is part of the HFortix SDK ecosystem:

- **[hfortix-core](https://github.com/hermanwjacobsen/hfortix-core)** — Core HTTP client and utilities
- **[hfortix-fortios](https://github.com/hermanwjacobsen/hfortix-fortios)** — FortiOS/FortiGate SDK
- **[hfortix](https://github.com/hermanwjacobsen/hfortix)** — Meta package

## 📄 License

Proprietary license. All rights reserved.

## 🤝 Support

- **Issues**: https://github.com/hermanwjacobsen/hfortix-fortimanager/issues
- **PyPI**: https://pypi.org/project/hfortix-fortimanager/

---

**Version**: 0.1.0-beta  
**FortiManager Support**: 7.6.6 (specs; 7.4.x compatible)  
**Python**: 3.10+
