Metadata-Version: 2.4
Name: hfortix
Version: 0.5.142
Summary: Python SDK for Fortinet products (FortiOS, FortiManager, FortiAnalyzer)
Author-email: "Herman W. Jacobsen" <herman@wjacobsen.fo>
License: Proprietary
Project-URL: Homepage, https://github.com/hermanwjacobsen/hfortix
Project-URL: Repository, https://github.com/hermanwjacobsen/hfortix
Keywords: fortinet,fortigate,fortios,fortimanager,fortianalyzer,api,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: hfortix-core>=0.5.142
Requires-Dist: hfortix-fortios>=0.5.142
Provides-Extra: fortios
Requires-Dist: hfortix-fortios>=0.5.142; extra == "fortios"
Provides-Extra: all
Requires-Dist: hfortix-fortios>=0.5.142; extra == "all"

# HFortix

Complete Python SDK for Fortinet Products - Modular, type-safe, production-ready.

[![PyPI version](https://badge.fury.io/py/hfortix.svg)](https://pypi.org/project/hfortix/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

> **⚠️ BETA STATUS - Version 0.5.132 (January 21, 2026)**
>
> **Status**: Production-ready but in beta until v1.0 with comprehensive unit tests.

**Version:** 0.5.132
**Status:** Beta (100% auto-generated, production-ready)

## Overview

HFortix is a modular Python SDK that provides comprehensive, production-ready clients for Fortinet products. Starting with FortiOS/FortiGate, with future support planned for FortiManager, FortiAnalyzer, and more.

**Version 0.5.32** features major improvements to object response mode, auto-normalization for list fields, and enhanced IDE support with 15,000+ parameters having enum autocomplete.

This is a **meta-package** that provides convenient installation patterns for the HFortix ecosystem.

## Installation

### Minimal Installation (Core Only)
```bash
pip install hfortix
```
Installs only `hfortix-core` - the shared foundation (exceptions, HTTP client, type definitions).

### FortiOS/FortiGate Support
```bash
pip install hfortix[fortios]
```
Installs `hfortix-core` + `hfortix-fortios` - Everything needed for FortiGate/FortiOS.

### Complete Installation
```bash
pip install hfortix[all]
```
Installs all current and future Fortinet product packages.

### Individual Packages

You can also install product packages directly:

```bash
# Just FortiOS (includes core automatically)
pip install hfortix-fortios

# Just the core framework
pip install hfortix-core
```

## Quick Start

### FortiOS/FortiGate

```python
from hfortix_fortios import FortiOS

# Connect to FortiGate
fgt = FortiOS(
    host="192.168.1.99",
    token="your-api-token",
    verify=False
)

# Get system status (Monitor endpoint - GET)
status = fgt.api.monitor.system.status.get()
print(f"Hostname: {status.hostname}")
print(f"Version: {status.version}")

# Create a firewall address (CMDB endpoint - POST)
fgt.api.cmdb.firewall.address.post(
    name="web-server",
    subnet="192.168.1.100 255.255.255.255",
    comment="Production web server"
)

# Update an existing address (CMDB endpoint - PUT)
fgt.api.cmdb.firewall.address.put(
    name="web-server",
    subnet="192.168.1.101 255.255.255.255"
)

# Delete an address (CMDB endpoint - DELETE)
fgt.api.cmdb.firewall.address.delete(name="web-server")
```

### FortiManager Proxy

Route FortiOS API calls through FortiManager to managed devices:

```python
from hfortix_fortios import FortiManagerProxy

# Connect to FortiManager
fmg = FortiManagerProxy(
    host="fortimanager.example.com",
    username="admin",
    password="password",
    adom="root",
    verify=False
)

# Get a proxied FortiOS connection to a managed device
fgt = fmg.get_device("fw01")

# Use the same API as direct FortiOS!
addresses = fgt.api.cmdb.firewall.address.get()
fgt.api.cmdb.firewall.address.post(
    name="Server-01",
    subnet="10.0.1.10 255.255.255.255"
)

# Clean up
fmg.logout()
```

## Package Structure

HFortix uses a modular architecture:

```text
hfortix (meta-package)
├── hfortix-core          # Shared foundation
│   ├── Exception system (403+ error codes)
│   ├── HTTP client framework (sync & async)
│   ├── fmt module (13 formatting utilities)
│   ├── Type definitions (TypedDict, Protocols)
│   └── Debug utilities
│
└── hfortix-fortios       # FortiOS/FortiGate client
    ├── Complete API coverage (1,348 endpoints)
    ├── 2,129 endpoint files with type stubs
    ├── Auto-generated validators
    └── FortiObject response wrapper
```

**Future Packages:**
- `hfortix-fortimanager` - FortiManager API client
- `hfortix-fortianalyzer` - FortiAnalyzer API client
- `hfortix-fortiswitch` - FortiSwitch API client
- And more...

## Key Features

### 🎯 Modular Design

Install only what you need:
- Minimal footprint with `hfortix-core`
- Product-specific packages when needed
- Shared infrastructure across all products

### ⚡ Complete FortiOS Support

**API Coverage (FortiOS 7.6.5 - Schema v1.7.0):**
- **1,348 total endpoints** (100% auto-generated)
- 561 CMDB endpoints (configuration management)
- 490 Monitor endpoints (real-time data)
- 286 Log endpoints (disk, memory, FortiAnalyzer, FortiCloud)
- 11 Service endpoints (sniffer, security rating, system)

**Features:**
- Complete `.pyi` type stubs (2,129 files) for perfect IDE autocomplete
- Schema-based validation for all parameters
- Auto-generated tests for all endpoints
- Automatic key normalization (hyphens → underscores)

### 🏢 Enterprise Features

- **Async/Await Support**: Full async implementation with context managers
- **Error Handling**: 403+ specific error codes with comprehensive exception hierarchy
- **HTTP/2 Support**: Connection multiplexing for better performance
- **Automatic Retry**: Handles transient failures intelligently
- **Circuit Breaker**: Prevents cascade failures with automatic recovery
- **Type Safety**: Full type hints with IDE autocomplete
- **Read-Only Mode**: Safe testing without accidental changes
- **Operation Tracking**: Audit logging for all API calls
- **Performance Testing**: Built-in tools to optimize device communication
- **Formatting Utilities**: `fmt` module with 13 data conversion functions

## Import Patterns

### Recommended (New in v0.4.0-dev1)
```python
# Product packages
from hfortix_fortios import FortiOS

# Core exceptions
from hfortix_core import (
    APIError,
    ResourceNotFoundError,
    DuplicateEntryError
)
```

### Legacy (Still Supported)
```python
from hfortix import FortiOS
from hfortix.FortiOS import FortiOS
```

## Migration from v0.4.x

**Changes in v0.5.0:**
- Direct API access via `fgt.api.cmdb.*`, `fgt.api.monitor.*`, `fgt.api.log.*`

**Old (v0.4.x):**
```python
from hfortix_fortios.firewall import FirewallAddress
addr = FirewallAddress(fgt)
result = addr.create(name="test", subnet="10.0.0.1/32")
```

**New (v0.5.0+):**
```python
# Uses standard REST methods: .get(), .post(), .put(), .delete()
result = fgt.api.cmdb.firewall.address.post(
    name="test",
    subnet="10.0.0.1 255.255.255.255"
)
```

All endpoints use REST verbs (`.get()`, `.post()`, `.put()`, `.delete()`) and return FortiObject with attribute access.

## Documentation

**Getting Started:**
- [Quick Start Guide](https://github.com/hermanwjacobsen/hfortix/blob/main/QUICKSTART.md) - Installation and basic usage
- [Async Guide](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/ASYNC_GUIDE.md) - Async/await patterns
- [API Reference](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/ENDPOINT_METHODS.md) - Complete method reference

**Convenience Wrappers:**
- [Overview](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/wrappers/CONVENIENCE_WRAPPERS.md) - All wrappers
- [Service Management](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/wrappers/CONVENIENCE_WRAPPERS.md#service-management)
- [Schedules](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/wrappers/SCHEDULE_WRAPPERS.md)
- [Traffic Shaping](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/wrappers/SHAPER_WRAPPERS.md)

**Advanced Topics:**
- [Validation Guide](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/VALIDATION_GUIDE.md) - Using validators
- [Error Handling](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/ERROR_HANDLING_CONFIG.md) - Exception system
- [Performance Testing](https://github.com/hermanwjacobsen/hfortix/blob/main/docs/fortios/PERFORMANCE_TESTING.md) - Optimization

**Project Info:**
- [Changelog](https://github.com/hermanwjacobsen/hfortix/blob/main/CHANGELOG.md) - Version history
- [GitHub Repository](https://github.com/hermanwjacobsen/hfortix) - Complete docs

## Requirements

- Python 3.10+
- FortiOS 7.0+ (tested with 7.6.5)

## Development Status

**Beta** - All APIs are functional and tested against live Fortinet devices. The package remains in beta status until version 1.0.0 with comprehensive unit test coverage.

**Current Test Coverage:**
- 226 test files for FortiOS
- 75%+ pass rate
- ~50% of endpoints have dedicated tests
- All implementations validated against FortiOS 7.6.5

## Why Modular?

**Benefits of the split package architecture:**

1. **Smaller Dependencies**: Install only what you need
2. **Faster Updates**: Product packages can be updated independently
3. **Better Organization**: Clear separation of concerns
4. **Easier Maintenance**: Focused development per product
5. **Future Flexibility**: Easy to add new Fortinet products

## Version History

- **v0.4.0-dev1** (Current): Package split - modular architecture
- **v0.3.39**: Convenience wrappers (services, schedules, shaping, IP/MAC binding)
- **v0.3.38**: Firewall policy wrapper with 150+ parameters
- **v0.3.x**: Async support, error handling, performance tools
- **v0.1.x-v0.2.x**: Initial FortiOS API implementation

## License

Proprietary - See LICENSE file

## Support

- 📖 [Documentation](https://github.com/hermanwjacobsen/hfortix)
- 🐛 [Report Issues](https://github.com/hermanwjacobsen/hfortix/issues)
- 💬 [Discussions](https://github.com/hermanwjacobsen/hfortix/discussions)

## Author

**Herman W. Jacobsen**
- Email: herman@wjacobsen.fo
- LinkedIn: [linkedin.com/in/hermanwjacobsen](https://www.linkedin.com/in/hermanwjacobsen/)
- GitHub: [@hermanwjacobsen](https://github.com/hermanwjacobsen)
