| Name | netbird JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Python client for the NetBird API |
| upload_time | 2025-08-01 01:36:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
api
client
mesh
netbird
networking
vpn
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# NetBird Python Client (Unofficial)
[](https://badge.fury.io/py/netbird)
[](https://pypi.org/project/netbird/)
[](https://opensource.org/licenses/MIT)
**Unofficial** Python client library for the [NetBird](https://netbird.io) API. Provides complete access to all NetBird API resources with a simple, intuitive interface.
> **⚠️ Disclaimer**: This is an **unofficial**, community-maintained client library. It is **not affiliated with, endorsed by, or officially supported** by NetBird or the NetBird team. For official NetBird tools and support, please visit [netbird.io](https://netbird.io).
This client follows the same upstream schemas as the official NetBird REST APIs, ensuring full compatibility and consistency with the NetBird ecosystem.
## Features
- ✅ **Complete API Coverage** - All 11 NetBird API resources supported
- ✅ **Upstream Schema Compliance** - Follows official NetBird REST API schemas exactly
- ✅ **Dictionary Responses** - Clean dictionary responses for easy data access
- ✅ **Type Safety** - Pydantic models for input validation, dictionaries for responses
- ✅ **Network Visualization** - Generate network topology diagrams in multiple formats
- ✅ **Modern Python** - Built for Python 3.8+ with async support ready
- ✅ **Comprehensive Error Handling** - Detailed exception classes for different error types
- ✅ **Exceptional Test Coverage** - 98.01% total coverage with comprehensive unit and integration tests
- ✅ **Extensive Documentation** - Complete API reference and examples
- ✅ **PyPI Ready** - Easy installation and distribution
## Supported Resources
| Resource | Description | Endpoints |
|----------|-------------|-----------|
| **Accounts** | Account management and settings | List, Update, Delete |
| **Users** | User lifecycle management | CRUD + Invite, Current user |
| **Tokens** | API token management | CRUD operations |
| **Peers** | Network peer management | CRUD + Accessible peers |
| **Setup Keys** | Peer setup key management | CRUD operations |
| **Groups** | Peer group management | CRUD operations |
| **Networks** | Network and resource management | CRUD + Resources/Routers |
| **Policies** | Access control policies | CRUD operations |
| **Routes** | Network routing configuration | CRUD operations |
| **DNS** | DNS settings and nameservers | Nameserver groups + Settings |
| **Events** | Audit and traffic events | Audit logs, Network traffic |
## Installation
```bash
pip install netbird
```
## Quick Start
```python
from netbird import APIClient
# Initialize the client
client = APIClient(
host="your-netbird-host.com", # e.g., "api.netbird.io" for cloud
api_token="your-api-token-here"
)
# List all peers
peers = client.peers.list()
print(f"Found {len(peers)} peers")
# Get current user
user = client.users.get_current()
print(f"Logged in as: {user['name']}")
# Create a new group
from netbird.models import GroupCreate
group_data = GroupCreate(
name="My Team",
peers=["peer-1", "peer-2"]
)
group = client.groups.create(group_data)
print(f"Created group: {group['name']}")
```
## Authentication
NetBird uses token-based authentication. You can use either a personal access token or a service user token:
### Personal Access Token (Recommended)
```python
client = APIClient(
host="your-netbird-host.com", # e.g., "api.netbird.io" for cloud
api_token="your-personal-access-token"
)
```
### Service User Token
```python
client = APIClient(
host="your-netbird-host.com", # e.g., "api.netbird.io" for cloud
api_token="your-service-user-token"
)
```
### Self-Hosted NetBird
```python
client = APIClient(
host="netbird.yourcompany.com:33073",
api_token="your-token",
use_ssl=True # or False for HTTP
)
```
## Examples
### User Management
```python
from netbird.models import UserCreate, UserRole
# Create a new user
user_data = UserCreate(
email="user@company.com",
name="New User",
role=UserRole.USER,
auto_groups=["group-default"]
)
user = client.users.create(user_data)
print(f"Created user: {user['name']} ({user['email']})")
# Update user role
from netbird.models import UserUpdate
update_data = UserUpdate(role=UserRole.ADMIN)
updated_user = client.users.update(user['id'], update_data)
print(f"Updated user role to: {updated_user['role']}")
```
### Network Management
```python
from netbird.models import NetworkCreate, PolicyCreate, PolicyRule
# Create a network
network_data = NetworkCreate(
name="My Network",
description="Network environment"
)
network = client.networks.create(network_data)
print(f"Created network: {network['name']}")
# Create access policy
rule = PolicyRule(
name="Allow Access",
action="accept",
protocol="tcp",
ports=["22"],
sources=["source-group"],
destinations=["destination-group"]
)
policy_data = PolicyCreate(
name="Access Policy",
rules=[rule]
)
policy = client.policies.create(policy_data)
print(f"Created policy: {policy['name']}")
```
### Setup Key Management
```python
from netbird.models import SetupKeyCreate
# Create a reusable setup key
key_data = SetupKeyCreate(
name="Environment Setup",
type="reusable",
expires_in=86400, # 24 hours
usage_limit=10,
auto_groups=["default-group"]
)
setup_key = client.setup_keys.create(key_data)
print(f"Setup key: {setup_key['key']}")
print(f"Key valid: {setup_key['valid']}")
```
### Event Monitoring
```python
# Get audit events
audit_events = client.events.get_audit_events()
for event in audit_events[-10:]: # Last 10 events
print(f"{event['timestamp']}: {event['activity']}")
if event.get('initiator_name'):
print(f" Initiated by: {event['initiator_name']}")
# Get network traffic events (cloud-only)
traffic_events = client.events.get_network_traffic_events(
protocol="tcp",
page_size=100
)
for traffic in traffic_events[:5]:
print(f"Traffic: {traffic['source_ip']} -> {traffic['destination_ip']}")
```
## Network Visualization
The NetBird Python client includes powerful network visualization capabilities that can generate topology diagrams in multiple formats:
### Generate Network Maps
```python
from netbird import APIClient, generate_full_network_map
# Initialize client
client = APIClient(host="your-netbird-host.com", api_token="your-token")
# Generate enriched network data
networks = generate_full_network_map(client)
# Access enriched data
for network in networks:
print(f"Network: {network['name']}")
for resource in network.get('resources', []):
print(f" Resource: {resource['name']} - {resource['address']}")
for policy in network.get('policies', []):
print(f" Policy: {policy['name']}")
```
### Topology Visualization
```python
from netbird import get_network_topology_data
# Get optimized topology data for visualization
topology = get_network_topology_data(client, optimize_connections=True)
print(f"Found {len(topology['all_source_groups'])} source groups")
print(f"Found {len(topology['group_connections'])} group connections")
print(f"Found {len(topology['direct_connections'])} direct connections")
```
### Diagram Generation
Use the included unified diagram generator to create visual network topology diagrams:
```bash
# Set your API token
export NETBIRD_API_TOKEN="your-token-here"
# Generate Mermaid diagram (default, GitHub/GitLab compatible)
python unified-network-diagram.py
# Generate Graphviz diagram (PNG, SVG, PDF)
python unified-network-diagram.py --format graphviz
# Generate Python Diagrams (PNG)
python unified-network-diagram.py --format diagrams
# Custom output filename
python unified-network-diagram.py --format mermaid -o my_network_topology
```
### Supported Diagram Formats
| Format | Output Files | Best For |
|--------|-------------|----------|
| **Mermaid** | `.mmd`, `.md` | GitHub/GitLab documentation, web viewing |
| **Graphviz** | `.png`, `.svg`, `.pdf`, `.dot` | High-quality publications, presentations |
| **Diagrams** | `.png` | Code documentation, architecture diagrams |
### Diagram Features
- **Source Groups**: Visual representation of user groups with distinct colors
- **Networks & Resources**: Hierarchical network structure with resource details
- **Policy Connections**:
- 🟢 **Group-based access** (dashed lines)
- 🔵 **Direct resource access** (solid lines)
- **Optimized Layout**: Merged connections to reduce visual complexity
- **Rich Information**: Resource addresses, types, and group memberships
### Installation for Diagrams
```bash
# For Graphviz diagrams
pip install graphviz
# For Python Diagrams
pip install diagrams
# Mermaid requires no additional dependencies
```
## Error Handling
The client provides specific exception types for different error conditions:
```python
from netbird.exceptions import (
NetBirdAPIError,
NetBirdAuthenticationError,
NetBirdNotFoundError,
NetBirdRateLimitError,
NetBirdServerError,
NetBirdValidationError,
)
try:
user = client.users.get("invalid-user-id")
except NetBirdNotFoundError:
print("User not found")
except NetBirdAuthenticationError:
print("Invalid API token")
except NetBirdRateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds")
except NetBirdAPIError as e:
print(f"API error: {e.message}")
```
## Configuration Options
```python
client = APIClient(
host="your-netbird-host.com", # Your NetBird API host
api_token="your-token",
use_ssl=True, # Use HTTPS (default: True)
timeout=30.0, # Request timeout in seconds (default: 30)
base_path="/api" # API base path (default: "/api")
)
```
## Development
### Setting up Development Environment
```bash
# Clone the repository
git clone https://github.com/netbirdio/netbird-python-client.git
cd netbird-python-client
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run type checking
mypy src/
# Format code
black src/ tests/
isort src/ tests/
# Run linting
flake8 src/ tests/
```
### Testing & Coverage
The NetBird Python client has comprehensive test coverage ensuring reliability and stability:
#### Test Coverage Statistics
- **Total Coverage**: 98.01% (1,181 of 1,205 lines covered)
- **Unit Tests**: 230 tests covering all core functionality
- **Integration Tests**: 20 tests covering real API interactions
- **Total Tests**: 251 tests (250 passing, 1 skipped)
#### Coverage by Module
| Module | Coverage | Status |
|--------|----------|--------|
| **Models** | 100% | ✅ Complete |
| **Resources** | 100% | ✅ Complete |
| **Auth** | 100% | ✅ Complete |
| **Exceptions** | 100% | ✅ Complete |
| **Network Map** | 98% | ✅ Excellent |
| **Base Resources** | 95% | ✅ Excellent |
| **Client Core** | 95% | 🚀 Exceptional |
#### Running Tests
```bash
# Run all tests
pytest
# Run with coverage report
pytest --cov=src/netbird --cov-report=html
# Run specific test categories
pytest tests/unit/ # Unit tests only
pytest tests/integration/ # Integration tests only
# Generate detailed coverage report
pytest --cov=src/netbird --cov-report=html --cov-report=term-missing
```
#### Test Categories
**Unit Tests** (tests/unit/)
- API client functionality
- Model validation and serialization
- Resource method behavior
- Error handling scenarios
- Network topology generation
- Diagram creation (Mermaid, Graphviz, Python Diagrams)
**Integration Tests** (tests/integration/)
- Real API endpoint interactions
- CRUD operations across all resources
- Authentication and authorization
- Error handling with live API responses
- End-to-end workflows
## Response Format
The NetBird Python client provides clean and intuitive API responses:
- **Input validation**: Uses Pydantic models for type safety and validation
- **API responses**: Returns standard Python dictionaries for easy access
- **Familiar patterns**: Simple dictionary-based responses
```python
# Input: Type-safe Pydantic models
user_data = UserCreate(email="john@example.com", name="John Doe")
# Output: Standard Python dictionaries
user = client.users.create(user_data)
print(user['name']) # Access like a dictionary
print(user['email']) # Easy dictionary access
print(user.get('role')) # Safe access with .get()
```
## Interactive Demo
Explore the client with our **Jupyter notebook demo**:
```bash
# Install Jupyter if you haven't already
pip install jupyter
# Start the demo notebook
jupyter notebook netbird_demo.ipynb
```
The demo notebook shows real usage examples for all API resources.
## Documentation
- **[Jupyter Demo](netbird_demo.ipynb)** - Interactive demonstration of all features
- **[Integration Tests](tests/integration/)** - Real API usage examples
- **[Unit Tests](tests/unit/)** - Complete test coverage examples
- **[NetBird Documentation](https://docs.netbird.io/)** - Official NetBird docs
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Quick Contribution Guide
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (`pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to your branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Disclaimer & Legal
**This is an unofficial, community-maintained client library.**
- ❌ **Not official**: This library is NOT affiliated with, endorsed by, or officially supported by NetBird or the NetBird team
- ❌ **No warranty**: This software is provided "as is" without warranty of any kind
- ❌ **No official support**: For official NetBird support, please contact NetBird directly
- ✅ **Open source**: This is a community effort to provide Python developers with NetBird API access
- ✅ **Best effort compatibility**: We strive to maintain compatibility with NetBird's official API
**NetBird** is a trademark of NetBird. This project is not endorsed by or affiliated with NetBird.
For official NetBird tools, documentation, and support:
- **Official Website**: [netbird.io](https://netbird.io)
- **Official Documentation**: [docs.netbird.io](https://docs.netbird.io)
- **Official GitHub**: [github.com/netbirdio/netbird](https://github.com/netbirdio/netbird)
## Support
- **GitHub Issues**: [Report bugs or request features](https://github.com/drtinkerer/netbird-python-client/issues)
- **NetBird Community**: [Join the discussion](https://github.com/netbirdio/netbird/discussions)
- **Documentation**: [API Documentation](https://docs.netbird.io/api)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
---
Made with ❤️ by [Bhushan Rane](https://github.com/drtinkerer)
Raw data
{
"_id": null,
"home_page": null,
"name": "netbird",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "api, client, mesh, netbird, networking, vpn",
"author": null,
"author_email": "Bhushan Rane <eulersidentity2718@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6b/94/25cd1264ba8ea9a7b829694ed3703a73eda2d79dd4a7803ebd9a038dcf13/netbird-1.1.0.tar.gz",
"platform": null,
"description": "# NetBird Python Client (Unofficial)\n\n[](https://badge.fury.io/py/netbird)\n[](https://pypi.org/project/netbird/)\n[](https://opensource.org/licenses/MIT)\n\n**Unofficial** Python client library for the [NetBird](https://netbird.io) API. Provides complete access to all NetBird API resources with a simple, intuitive interface.\n\n> **\u26a0\ufe0f Disclaimer**: This is an **unofficial**, community-maintained client library. It is **not affiliated with, endorsed by, or officially supported** by NetBird or the NetBird team. For official NetBird tools and support, please visit [netbird.io](https://netbird.io).\n\nThis client follows the same upstream schemas as the official NetBird REST APIs, ensuring full compatibility and consistency with the NetBird ecosystem.\n\n## Features\n\n- \u2705 **Complete API Coverage** - All 11 NetBird API resources supported\n- \u2705 **Upstream Schema Compliance** - Follows official NetBird REST API schemas exactly\n- \u2705 **Dictionary Responses** - Clean dictionary responses for easy data access\n- \u2705 **Type Safety** - Pydantic models for input validation, dictionaries for responses\n- \u2705 **Network Visualization** - Generate network topology diagrams in multiple formats\n- \u2705 **Modern Python** - Built for Python 3.8+ with async support ready\n- \u2705 **Comprehensive Error Handling** - Detailed exception classes for different error types\n- \u2705 **Exceptional Test Coverage** - 98.01% total coverage with comprehensive unit and integration tests\n- \u2705 **Extensive Documentation** - Complete API reference and examples\n- \u2705 **PyPI Ready** - Easy installation and distribution\n\n## Supported Resources\n\n| Resource | Description | Endpoints |\n|----------|-------------|-----------|\n| **Accounts** | Account management and settings | List, Update, Delete |\n| **Users** | User lifecycle management | CRUD + Invite, Current user |\n| **Tokens** | API token management | CRUD operations |\n| **Peers** | Network peer management | CRUD + Accessible peers |\n| **Setup Keys** | Peer setup key management | CRUD operations |\n| **Groups** | Peer group management | CRUD operations |\n| **Networks** | Network and resource management | CRUD + Resources/Routers |\n| **Policies** | Access control policies | CRUD operations |\n| **Routes** | Network routing configuration | CRUD operations |\n| **DNS** | DNS settings and nameservers | Nameserver groups + Settings |\n| **Events** | Audit and traffic events | Audit logs, Network traffic |\n\n## Installation\n\n```bash\npip install netbird\n```\n\n## Quick Start\n\n```python\nfrom netbird import APIClient\n\n# Initialize the client\nclient = APIClient(\n host=\"your-netbird-host.com\", # e.g., \"api.netbird.io\" for cloud\n api_token=\"your-api-token-here\"\n)\n\n# List all peers\npeers = client.peers.list()\nprint(f\"Found {len(peers)} peers\")\n\n# Get current user\nuser = client.users.get_current()\nprint(f\"Logged in as: {user['name']}\")\n\n# Create a new group\nfrom netbird.models import GroupCreate\ngroup_data = GroupCreate(\n name=\"My Team\",\n peers=[\"peer-1\", \"peer-2\"]\n)\ngroup = client.groups.create(group_data)\nprint(f\"Created group: {group['name']}\")\n```\n\n## Authentication\n\nNetBird uses token-based authentication. You can use either a personal access token or a service user token:\n\n### Personal Access Token (Recommended)\n```python\nclient = APIClient(\n host=\"your-netbird-host.com\", # e.g., \"api.netbird.io\" for cloud\n api_token=\"your-personal-access-token\"\n)\n```\n\n### Service User Token\n```python\nclient = APIClient(\n host=\"your-netbird-host.com\", # e.g., \"api.netbird.io\" for cloud\n api_token=\"your-service-user-token\"\n)\n```\n\n### Self-Hosted NetBird\n```python\nclient = APIClient(\n host=\"netbird.yourcompany.com:33073\",\n api_token=\"your-token\",\n use_ssl=True # or False for HTTP\n)\n```\n\n## Examples\n\n### User Management\n```python\nfrom netbird.models import UserCreate, UserRole\n\n# Create a new user\nuser_data = UserCreate(\n email=\"user@company.com\",\n name=\"New User\",\n role=UserRole.USER,\n auto_groups=[\"group-default\"]\n)\nuser = client.users.create(user_data)\nprint(f\"Created user: {user['name']} ({user['email']})\")\n\n# Update user role\nfrom netbird.models import UserUpdate\nupdate_data = UserUpdate(role=UserRole.ADMIN)\nupdated_user = client.users.update(user['id'], update_data)\nprint(f\"Updated user role to: {updated_user['role']}\")\n```\n\n### Network Management\n```python\nfrom netbird.models import NetworkCreate, PolicyCreate, PolicyRule\n\n# Create a network\nnetwork_data = NetworkCreate(\n name=\"My Network\",\n description=\"Network environment\"\n)\nnetwork = client.networks.create(network_data)\nprint(f\"Created network: {network['name']}\")\n\n# Create access policy\nrule = PolicyRule(\n name=\"Allow Access\",\n action=\"accept\",\n protocol=\"tcp\", \n ports=[\"22\"],\n sources=[\"source-group\"],\n destinations=[\"destination-group\"]\n)\npolicy_data = PolicyCreate(\n name=\"Access Policy\",\n rules=[rule]\n)\npolicy = client.policies.create(policy_data)\nprint(f\"Created policy: {policy['name']}\")\n```\n\n### Setup Key Management\n```python\nfrom netbird.models import SetupKeyCreate\n\n# Create a reusable setup key\nkey_data = SetupKeyCreate(\n name=\"Environment Setup\",\n type=\"reusable\",\n expires_in=86400, # 24 hours\n usage_limit=10,\n auto_groups=[\"default-group\"]\n)\nsetup_key = client.setup_keys.create(key_data)\nprint(f\"Setup key: {setup_key['key']}\")\nprint(f\"Key valid: {setup_key['valid']}\")\n```\n\n### Event Monitoring\n```python\n# Get audit events\naudit_events = client.events.get_audit_events()\nfor event in audit_events[-10:]: # Last 10 events\n print(f\"{event['timestamp']}: {event['activity']}\")\n if event.get('initiator_name'):\n print(f\" Initiated by: {event['initiator_name']}\")\n\n# Get network traffic events (cloud-only)\ntraffic_events = client.events.get_network_traffic_events(\n protocol=\"tcp\",\n page_size=100\n)\nfor traffic in traffic_events[:5]:\n print(f\"Traffic: {traffic['source_ip']} -> {traffic['destination_ip']}\")\n```\n\n## Network Visualization\n\nThe NetBird Python client includes powerful network visualization capabilities that can generate topology diagrams in multiple formats:\n\n### Generate Network Maps\n\n```python\nfrom netbird import APIClient, generate_full_network_map\n\n# Initialize client\nclient = APIClient(host=\"your-netbird-host.com\", api_token=\"your-token\")\n\n# Generate enriched network data\nnetworks = generate_full_network_map(client)\n\n# Access enriched data\nfor network in networks:\n print(f\"Network: {network['name']}\")\n for resource in network.get('resources', []):\n print(f\" Resource: {resource['name']} - {resource['address']}\")\n for policy in network.get('policies', []):\n print(f\" Policy: {policy['name']}\")\n```\n\n### Topology Visualization\n\n```python\nfrom netbird import get_network_topology_data\n\n# Get optimized topology data for visualization\ntopology = get_network_topology_data(client, optimize_connections=True)\n\nprint(f\"Found {len(topology['all_source_groups'])} source groups\")\nprint(f\"Found {len(topology['group_connections'])} group connections\")\nprint(f\"Found {len(topology['direct_connections'])} direct connections\")\n```\n\n### Diagram Generation\n\nUse the included unified diagram generator to create visual network topology diagrams:\n\n```bash\n# Set your API token\nexport NETBIRD_API_TOKEN=\"your-token-here\"\n\n# Generate Mermaid diagram (default, GitHub/GitLab compatible)\npython unified-network-diagram.py\n\n# Generate Graphviz diagram (PNG, SVG, PDF)\npython unified-network-diagram.py --format graphviz\n\n# Generate Python Diagrams (PNG)\npython unified-network-diagram.py --format diagrams\n\n# Custom output filename\npython unified-network-diagram.py --format mermaid -o my_network_topology\n```\n\n### Supported Diagram Formats\n\n| Format | Output Files | Best For |\n|--------|-------------|----------|\n| **Mermaid** | `.mmd`, `.md` | GitHub/GitLab documentation, web viewing |\n| **Graphviz** | `.png`, `.svg`, `.pdf`, `.dot` | High-quality publications, presentations |\n| **Diagrams** | `.png` | Code documentation, architecture diagrams |\n\n### Diagram Features\n\n- **Source Groups**: Visual representation of user groups with distinct colors\n- **Networks & Resources**: Hierarchical network structure with resource details\n- **Policy Connections**: \n - \ud83d\udfe2 **Group-based access** (dashed lines)\n - \ud83d\udd35 **Direct resource access** (solid lines)\n- **Optimized Layout**: Merged connections to reduce visual complexity\n- **Rich Information**: Resource addresses, types, and group memberships\n\n### Installation for Diagrams\n\n```bash\n# For Graphviz diagrams\npip install graphviz\n\n# For Python Diagrams\npip install diagrams\n\n# Mermaid requires no additional dependencies\n```\n\n## Error Handling\n\nThe client provides specific exception types for different error conditions:\n\n```python\nfrom netbird.exceptions import (\n NetBirdAPIError,\n NetBirdAuthenticationError,\n NetBirdNotFoundError,\n NetBirdRateLimitError,\n NetBirdServerError,\n NetBirdValidationError,\n)\n\ntry:\n user = client.users.get(\"invalid-user-id\")\nexcept NetBirdNotFoundError:\n print(\"User not found\")\nexcept NetBirdAuthenticationError:\n print(\"Invalid API token\")\nexcept NetBirdRateLimitError as e:\n print(f\"Rate limited. Retry after {e.retry_after} seconds\")\nexcept NetBirdAPIError as e:\n print(f\"API error: {e.message}\")\n```\n\n## Configuration Options\n\n```python\nclient = APIClient(\n host=\"your-netbird-host.com\", # Your NetBird API host\n api_token=\"your-token\",\n use_ssl=True, # Use HTTPS (default: True)\n timeout=30.0, # Request timeout in seconds (default: 30)\n base_path=\"/api\" # API base path (default: \"/api\")\n)\n```\n\n## Development\n\n### Setting up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/netbirdio/netbird-python-client.git\ncd netbird-python-client\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run type checking\nmypy src/\n\n# Format code\nblack src/ tests/\nisort src/ tests/\n\n# Run linting\nflake8 src/ tests/\n```\n\n### Testing & Coverage\n\nThe NetBird Python client has comprehensive test coverage ensuring reliability and stability:\n\n#### Test Coverage Statistics\n- **Total Coverage**: 98.01% (1,181 of 1,205 lines covered)\n- **Unit Tests**: 230 tests covering all core functionality\n- **Integration Tests**: 20 tests covering real API interactions \n- **Total Tests**: 251 tests (250 passing, 1 skipped)\n\n#### Coverage by Module\n| Module | Coverage | Status |\n|--------|----------|--------|\n| **Models** | 100% | \u2705 Complete |\n| **Resources** | 100% | \u2705 Complete | \n| **Auth** | 100% | \u2705 Complete |\n| **Exceptions** | 100% | \u2705 Complete |\n| **Network Map** | 98% | \u2705 Excellent |\n| **Base Resources** | 95% | \u2705 Excellent |\n| **Client Core** | 95% | \ud83d\ude80 Exceptional |\n\n#### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage report\npytest --cov=src/netbird --cov-report=html\n\n# Run specific test categories\npytest tests/unit/ # Unit tests only\npytest tests/integration/ # Integration tests only\n\n# Generate detailed coverage report\npytest --cov=src/netbird --cov-report=html --cov-report=term-missing\n```\n\n#### Test Categories\n\n**Unit Tests** (tests/unit/)\n- API client functionality\n- Model validation and serialization\n- Resource method behavior\n- Error handling scenarios\n- Network topology generation\n- Diagram creation (Mermaid, Graphviz, Python Diagrams)\n\n**Integration Tests** (tests/integration/)\n- Real API endpoint interactions\n- CRUD operations across all resources\n- Authentication and authorization\n- Error handling with live API responses\n- End-to-end workflows\n\n## Response Format\n\nThe NetBird Python client provides clean and intuitive API responses:\n\n- **Input validation**: Uses Pydantic models for type safety and validation\n- **API responses**: Returns standard Python dictionaries for easy access\n- **Familiar patterns**: Simple dictionary-based responses\n\n```python\n# Input: Type-safe Pydantic models\nuser_data = UserCreate(email=\"john@example.com\", name=\"John Doe\")\n\n# Output: Standard Python dictionaries\nuser = client.users.create(user_data)\nprint(user['name']) # Access like a dictionary\nprint(user['email']) # Easy dictionary access\nprint(user.get('role')) # Safe access with .get()\n```\n\n## Interactive Demo\n\nExplore the client with our **Jupyter notebook demo**:\n\n```bash\n# Install Jupyter if you haven't already\npip install jupyter\n\n# Start the demo notebook\njupyter notebook netbird_demo.ipynb\n```\n\nThe demo notebook shows real usage examples for all API resources.\n\n## Documentation\n\n- **[Jupyter Demo](netbird_demo.ipynb)** - Interactive demonstration of all features\n- **[Integration Tests](tests/integration/)** - Real API usage examples\n- **[Unit Tests](tests/unit/)** - Complete test coverage examples\n- **[NetBird Documentation](https://docs.netbird.io/)** - Official NetBird docs\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Contribution Guide\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to your branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer & Legal\n\n**This is an unofficial, community-maintained client library.**\n\n- \u274c **Not official**: This library is NOT affiliated with, endorsed by, or officially supported by NetBird or the NetBird team\n- \u274c **No warranty**: This software is provided \"as is\" without warranty of any kind\n- \u274c **No official support**: For official NetBird support, please contact NetBird directly\n- \u2705 **Open source**: This is a community effort to provide Python developers with NetBird API access\n- \u2705 **Best effort compatibility**: We strive to maintain compatibility with NetBird's official API\n\n**NetBird** is a trademark of NetBird. This project is not endorsed by or affiliated with NetBird.\n\nFor official NetBird tools, documentation, and support:\n- **Official Website**: [netbird.io](https://netbird.io)\n- **Official Documentation**: [docs.netbird.io](https://docs.netbird.io)\n- **Official GitHub**: [github.com/netbirdio/netbird](https://github.com/netbirdio/netbird)\n\n## Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/drtinkerer/netbird-python-client/issues)\n- **NetBird Community**: [Join the discussion](https://github.com/netbirdio/netbird/discussions)\n- **Documentation**: [API Documentation](https://docs.netbird.io/api)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.\n\n---\n\nMade with \u2764\ufe0f by [Bhushan Rane](https://github.com/drtinkerer)",
"bugtrack_url": null,
"license": null,
"summary": "Python client for the NetBird API",
"version": "1.1.0",
"project_urls": {
"Changelog": "https://github.com/drtinkerer/netbird-python-client/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/drtinkerer/netbird-python-client",
"Homepage": "https://github.com/drtinkerer/netbird-python-client",
"Issues": "https://github.com/drtinkerer/netbird-python-client/issues",
"Repository": "https://github.com/drtinkerer/netbird-python-client"
},
"split_keywords": [
"api",
" client",
" mesh",
" netbird",
" networking",
" vpn"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb6b04d8693624abe7317947b79cf666031d8df0ed635fc1c47500af54f6e6e7",
"md5": "a437d7af419bdd4818897ba0074feb27",
"sha256": "3e205b3264c8ce561f8f1e629f319e9ca8bf96936a69e6f3fa23014d9b3b1d7c"
},
"downloads": -1,
"filename": "netbird-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a437d7af419bdd4818897ba0074feb27",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 42458,
"upload_time": "2025-08-01T01:36:39",
"upload_time_iso_8601": "2025-08-01T01:36:39.269860Z",
"url": "https://files.pythonhosted.org/packages/eb/6b/04d8693624abe7317947b79cf666031d8df0ed635fc1c47500af54f6e6e7/netbird-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6b9425cd1264ba8ea9a7b829694ed3703a73eda2d79dd4a7803ebd9a038dcf13",
"md5": "52846972755cee0992e02553c2a8a43b",
"sha256": "b83c6b3910adc2234e42323cbf097f4ddbe64ba74ccce291d45fde5aa7fb26f2"
},
"downloads": -1,
"filename": "netbird-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "52846972755cee0992e02553c2a8a43b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 108844,
"upload_time": "2025-08-01T01:36:40",
"upload_time_iso_8601": "2025-08-01T01:36:40.431777Z",
"url": "https://files.pythonhosted.org/packages/6b/94/25cd1264ba8ea9a7b829694ed3703a73eda2d79dd4a7803ebd9a038dcf13/netbird-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 01:36:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "drtinkerer",
"github_project": "netbird-python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "netbird"
}
