Metadata-Version: 2.4
Name: lightwheel_sdk
Version: 1.0.3
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: termcolor
Requires-Dist: pyyaml
Requires-Dist: click
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"

# Lightwheel SDK Python

A Python SDK for interacting with the Lightwheel API, featuring comprehensive logging capabilities.

## Features

- **Authentication Management**: Secure login/logout with token caching and refresh
- **Comprehensive Logging**: Detailed logging throughout the SDK for debugging and monitoring
- **CLI Interface**: Command-line tools for easy interaction
- **Error Handling**: Robust exception handling with detailed error logging

## Installation

```bash
pip install lightwheel-sdk
```

## Quick Start

### Basic Usage

```python
from lightwheel_sdk.loader import LightwheelClient

# Initialize client
client = LightwheelClient(host="https://api.lightwheel.net")

# Login
client.login(username="your_username", password="your_password")

# Make API calls
response = client.post("/api/your/endpoint", data={"key": "value"})
```

### CLI Usage

```bash
# Login
lightwheel login --username your_username --password your_password

# Logout
lightwheel logout
```

## Logging Configuration

The SDK includes comprehensive logging capabilities that can be configured through environment variables or programmatically.

### Environment Variables

- `LW_SDK_LOG_LEVEL`: Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- `LW_SDK_LOG_FILE`: Optional path to log file
- `LW_API_ENDPOINT`: API endpoint URL

### Programmatic Configuration

```python
from lightwheel_sdk.logger import setup_logger

# Configure logger
logger = setup_logger(
    name="my_app",
    level="DEBUG",
    log_file="/path/to/logfile.log"
)
```

### Logging Levels

- **DEBUG**: Detailed information for debugging
- **INFO**: General information about SDK operations
- **WARNING**: Warning messages for potential issues
- **ERROR**: Error messages for failed operations
- **CRITICAL**: Critical errors that may cause the application to stop

### Log Categories

The SDK uses different logger names for different components:

- `lightwheel_sdk.client`: Client operations and API calls
- `lightwheel_sdk.login`: Authentication and login management
- `lightwheel_sdk.cli`: Command-line interface operations
- `lightwheel_sdk.exception`: Exception handling and error logging

### Example Log Output

```
2025-01-27 10:30:15,123 - lightwheel_sdk.client - INFO - Initializing LightwheelClient with host: https://api.lightwheel.net
2025-01-27 10:30:15,124 - lightwheel_sdk.client - INFO - Starting login process
2025-01-27 10:30:15,125 - lightwheel_sdk.client - INFO - Performing authentication with API
2025-01-27 10:30:15,200 - lightwheel_sdk.client - INFO - Login successful for user: john_doe
2025-01-27 10:30:15,201 - lightwheel_sdk.client - DEBUG - Making POST request to /api/your/endpoint
2025-01-27 10:30:15,250 - lightwheel_sdk.client - DEBUG - POST request to /api/your/endpoint completed successfully
```

## API Reference

### LightwheelClient

Main client class for interacting with the Lightwheel API.

#### Methods

- `login(force_login=False, username=None, password=None)`: Authenticate with the API
- `logout()`: Clear authentication and remove cached credentials
- `post(path, data=None, timeout=None)`: Make POST requests to the API

### Login Manager

High-level interface for authentication management.

#### Methods

- `login(force_login=False, username=None, password=None)`: Login to the API
- `logout()`: Logout from the API
- `get_headers()`: Get authentication headers

## Error Handling

The SDK provides comprehensive error handling with detailed logging:

- `ApiException`: API-related errors with status codes and response details
- `AuthenticationFailedException`: Authentication failures
- `UnknownException`: Unexpected errors

All exceptions include detailed logging for debugging purposes.

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `LW_API_ENDPOINT` | API endpoint URL | `https://api.lightwheel.net` |
| `LW_SDK_LOG_LEVEL` | Logging level | `INFO` |
| `LW_SDK_LOG_FILE` | Log file path | None (console only) |
| `LW_SDK_HEADERS_*` | Custom headers | None |
| `LoaderUserName` | Username for authentication | None |
| `LoaderToken` | Token for authentication | None |

### Custom Headers

You can set custom headers using environment variables with the prefix `LW_SDK_HEADERS_`:

```bash
export LW_SDK_HEADERS_X_CUSTOM_HEADER="custom_value"
```

## Development

### Running Tests

```bash
python -m pytest tests/
```

### Building

```bash
python -m build
```

## License

Copyright 2025 Lightwheel Team

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
