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

pip install lightwheel-sdk

Quick Start

Basic Usage

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

# 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

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

Custom Headers

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

export LW_SDK_HEADERS_X_CUSTOM_HEADER="custom_value"

Development

Running Tests

python -m pytest tests/

Building

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.