### Install Remnawave Python SDK

Source: https://github.com/sm1ky/remnawave-api/blob/production/README.md

Instructions for installing the Remnawave Python SDK from PyPI. It covers the recommended new package, the deprecated legacy package, and the development version from GitHub.

```bash
pip install remnawave
```

```bash
pip install remnawave_api  # Deprecated - use 'remnawave' instead
```

```bash
pip install git+https://github.com/remnawave/python-sdk.git@development
```

--------------------------------

### Python SDK Update Imports for New Features

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Provides an example of updating import statements to include new models and DTOs introduced in version 2.0.0, necessary for utilizing new controllers or features.

```python
# Add new imports for v2.0.0 features
from remnawave_api.models import (
    GetAllConfigProfilesResponseDto,
    CreateInternalSquadRequestDto,
    # ... other new models
)
```

--------------------------------

### Python SDK Update Creation Requests with New Fields

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Shows an example of updating a creation request DTO, such as 'CreateHostRequestDto', to include newly required fields like 'config_profile_inbound_uuid'.

```python
# Host creation now requires config_profile_inbound_uuid
host_request = CreateHostRequestDto(
    inbound_uuid="...",
    config_profile_inbound_uuid="...",  # New required field
    remark="...",
    address="...",
    port=...
)
```

--------------------------------

### Initialize and Fetch Users with Remnawave SDK

Source: https://github.com/sm1ky/remnawave-api/blob/production/README.md

Demonstrates how to initialize the Remnawave SDK with base URL and token, and then fetch all users using an asynchronous function. It shows how to access response data like total user count and the list of users.

```python
import os
import asyncio

from remnawave import RemnawaveSDK
from remnawave.models import (
    UsersResponseDto,
    UserResponseDto,
    GetAllConfigProfilesResponseDto,
    CreateInternalSquadRequestDto
)

async def main():
    # URL to your panel (ex. https://vpn.com or http://127.0.0.1:3000)
    base_url: str = os.getenv("REMNAWAVE_BASE_URL")
    # Bearer Token from panel (section: API Tokens) 
    token: str = os.getenv("REMNAWAVE_TOKEN")

    # Initialize the SDK
    remnawave = RemnawaveSDK(base_url=base_url, token=token)

    # Fetch all users
    response: UsersResponseDto = await remnawave.users.get_all_users_v2()
    total_users: int = response.total
    users: list[UserResponseDto] = response.users
    print("Total users: ", total_users)
    print("List of users: ", users)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Python SDK Basic Operations Unchanged

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Demonstrates that fundamental SDK operations like client initialization and host operations remain the same after the update. Authentication methods also continue to work without modification.

```python
# ✅ Basic operations unchanged
client = RemnawaveSDK(base_url="...", username="...", password="...")
async with client:
    # Host operations work the same
    host = await client.hosts.create_host(request)
    uuid = host.uuid  # Direct field access still works
    
    # Authentication unchanged  
    login_response = await client.auth.login(credentials)
    token = login_response.access_token
```

--------------------------------

### Run Project Tests

Source: https://github.com/sm1ky/remnawave-api/blob/production/README.md

Command to execute the project's test suite using Poetry, the dependency management and packaging tool.

```bash
poetry run pytest
```

--------------------------------

### RootModel for List Iteration and Indexing

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Enhances list responses by implementing Pydantic's RootModel for direct iteration and indexing, simplifying data access for collections of items.

```python
from typing import List
from pydantic import RootModel

# Assuming NodeResponseDto is defined elsewhere
class NodeResponseDto(BaseModel):
    # ... fields for NodeResponseDto
    pass

# Enhanced list responses with direct access:
class GetAllNodesResponseDto(RootModel[List[NodeResponseDto]]):
    def __iter__(self):
        return iter(self.root)
    
    def __getitem__(self, item):
        return self.root[item]

# Usage:
# nodes = await client.nodes.get_all_nodes()
# for node in nodes:  # Direct iteration
#     print(node.name)
# first_node = nodes[0]  # Direct indexing
```

--------------------------------

### Python SDK Enhanced List Responses

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Shows how list responses from the SDK have been enhanced for more convenient usage. Users can now directly iterate over responses or use indexing, while the old access methods are still supported.

```python
# ✅ List responses get enhanced capabilities
hosts = await client.hosts.get_all_hosts()
# Old way still works: host_list = hosts.root
# New way is more convenient:
for host in hosts:  # ✅ Direct iteration
    print(host.uuid)
first_host = hosts[0]  # ✅ Direct indexing
```

--------------------------------

### Remnawave API v2.0.0 Controllers

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Lists the new controllers available in the Remnawave SDK for managing various aspects of the Remnawave platform, including configuration, squads, billing, and node usage.

```apidoc
Controllers:
  ConfigProfilesController: Manages configuration profiles.
  InternalSquadsController: Handles squad operations and user management.
  InfraBillingController: Manages infrastructure billing and provider details.
  NodesUsageHistoryController: Provides historical usage data and statistics for nodes.
```

--------------------------------

### Python SDK New Paginated Responses

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Illustrates how certain endpoints, like config profiles, now return paginated data. The response object includes total counts and the actual list of items, requiring a slight adjustment in how data is accessed.

```python
# ✅ New paginated responses
profiles = await client.config_profiles.get_config_profiles()
total_count = profiles.total
profile_list = profiles.config_profiles
```

--------------------------------

### Python SDK Handle Paginated Response Data

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Demonstrates the required change for handling paginated responses, specifically for endpoints like 'config_profiles'. Users need to access the data via the new 'config_profiles' attribute and check the 'total' count.

```python
# Config profiles now return paginated data
result = await client.config_profiles.get_config_profiles()
profiles = result.config_profiles 
total = result.total
```

--------------------------------

### Breaking Changes: Response Structure Updates

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Highlights changes in response structures, specifically mentioning paginated responses for configuration profiles, requiring adjustments in data access patterns.

```apidoc
Breaking Change: Response Structure Updates

Description: Some responses now include pagination information, such as a 'response' object containing 'total' and the list of items.

Example:
  Config profiles now return paginated response:
  profiles = await client.config_profiles.get_config_profiles()
  total = profiles.response.total
  profile_list = profiles.response.config_profiles
```

--------------------------------

### Breaking Changes: List Response Models

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Details a breaking change in list response models, transitioning from accessing data via `__root__` to direct iteration, improving usability.

```apidoc
Breaking Change: List Response Models

Description: List response models now use Pydantic's RootModel for direct iteration and indexing, replacing the previous `__root__` attribute access.

Example:
  v1.x: hosts_list = response.__root__
  v2.0: for host in response: ...  # Direct iteration now possible
```

--------------------------------

### Handle Paginated API Responses

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Demonstrates how to define Pydantic models to correctly parse paginated API responses, including total counts and lists of items, with field aliasing for camelCase to snake_case conversion.

```python
from typing import List
from pydantic import BaseModel, Field

# Assuming ConfigProfileDto is defined elsewhere
class ConfigProfileDto(BaseModel):
    # ... fields for ConfigProfileDto
    pass

# API v2.0.0 returns paginated responses like:
# {
#   "response": {
#     "total": 6,
#     "configProfiles": [...] 
#   }
# }

# Fixed models to handle this correctly:
class GetAllConfigProfilesResponsePaginated(BaseModel):
    total: int
    config_profiles: List[ConfigProfileDto] = Field(alias="configProfiles")

class GetAllConfigProfilesResponseDto(BaseModel):
    response: GetAllConfigProfilesResponsePaginated
```

--------------------------------

### Field Alias and Optional Field Corrections

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Illustrates corrections for field alias mapping (camelCase to snake_case) and proper marking of optional fields in Pydantic models based on API specifications.

```python
from typing import List, Optional
from uuid import UUID
from pydantic import BaseModel, Field

# Assuming InboundsDto is defined elsewhere
class InboundsDto(BaseModel):
    # ... other fields
    pass

# Fixed camelCase vs snake_case mapping issues:
class NodeConfigProfileDto(BaseModel):
    active_config_profile_uuid: UUID = Field(alias="activeConfigProfileUuid")
    active_inbounds: List[InboundsDto] = Field(alias="activeInbounds")

# Fixed optional fields where API may omit values:
class InboundsDto(BaseModel):
    network: Optional[str] = None
    security: Optional[str] = None
    port: Optional[float] = None
```

--------------------------------

### Breaking Changes: New Required Fields

Source: https://github.com/sm1ky/remnawave-api/blob/production/MIGRATION_V2.md

Notes that certain models have new required fields, which may necessitate updates to request payloads when creating or modifying resources.

```apidoc
Breaking Change: New Required Fields

Description: Several models have introduced new required fields, impacting the structure of request payloads.

Examples:
  - NodeConfigProfileDto now requires active_config_profile_uuid and active_inbounds.
  - CreateHostRequestDto now requires config_profile_inbound_uuid.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.