ポキ
161a4d42d6
- Move auth, user, and music clients into new clients package - Update imports to use new module paths - Add __init__.py to expose clients from package - Clean up code formatting and imports - Add pre-commit configuration for code quality checks
285 lines
6.7 KiB
Markdown
285 lines
6.7 KiB
Markdown
# API Client Library
|
|
|
|
A comprehensive Python client library for a music streaming API. This library provides both programmatic access and command-line interface (CLI) for interacting with songbox's music platform.
|
|
|
|
## Features
|
|
|
|
- 🔐 **Authentication**: Login with mobile number and OTP verification
|
|
- 👤 **User Management**: Get user profile, following lists, and user operations
|
|
- 🎵 **Music Operations**: Search songs, get albums, artists, and trending music
|
|
- 🖥️ **CLI Support**: Full command-line interface for all operations
|
|
- 🔧 **Modular Design**: Separate clients for different API categories
|
|
- 📦 **Easy Installation**: Simple pip install with all dependencies
|
|
- 🛡️ **Error Handling**: Comprehensive exception handling with meaningful errors
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install songbox
|
|
```
|
|
|
|
Or install from source:
|
|
|
|
```bash
|
|
git clone https://git.cubable.date/CustomIcon/songbox
|
|
cd songbox
|
|
pip install -e .
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Python Library Usage
|
|
|
|
```python
|
|
from songbox import SongboxClient
|
|
|
|
# Create client
|
|
client = SongboxClient()
|
|
|
|
# Authenticate
|
|
verify_id = client.auth.login("960", "7777777")
|
|
opt_code = input("Enter OTP: ")
|
|
token = client.auth.verify_otp(otp_code, verify_id)
|
|
|
|
# Get user info
|
|
user_info = client.user.get_me()
|
|
print(f"Welcome, {user_info['username']}!")
|
|
|
|
# Search for music
|
|
results = client.music.search("huttaa")
|
|
for category in results:
|
|
print(f"Category: {category['title']}")
|
|
for item in category['items']:
|
|
print(f" - {item['heading']} by {item['sub_heading']}")
|
|
|
|
# Get album details
|
|
album = client.music.get_album("808")
|
|
print(f"Album: {album['name']} by {album['artist_name']}")
|
|
print(f"Songs: {len(album['songs'])}")
|
|
|
|
# Close client when done
|
|
client.close()
|
|
```
|
|
|
|
### CLI Usage
|
|
|
|
```bash
|
|
# Login
|
|
songbox auth login --country-code 960 --mobile 7777777
|
|
songbox auth verify --otp 123456 --verify-id <verify_id>
|
|
|
|
# Set token for subsequent commands
|
|
export songbox_TOKEN="your_jwt_token_here"
|
|
|
|
# Get user info
|
|
songbox user me
|
|
|
|
# Search for music
|
|
songbox music search "huttaa"
|
|
|
|
# Get album information
|
|
songbox music album 808
|
|
|
|
# Get trending music
|
|
songbox music trending --limit 10
|
|
|
|
# Different output formats
|
|
songbox music search "huttaa" --format json
|
|
songbox user me --format table
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Authentication (`client.auth`)
|
|
|
|
- `login(country_code, mobile_number)` - Initiate login with mobile number
|
|
- `verify_otp(otp, verify_id)` - Verify OTP and get authentication token
|
|
- `refresh_token()` - Refresh the current authentication token
|
|
- `logout()` - Clear authentication token
|
|
- `get_token_info()` - Get information about current token
|
|
|
|
### User Management (`client.user`)
|
|
|
|
- `get_me()` - Get current user's profile information
|
|
- `get_following()` - Get list of followed users/artists
|
|
- `get_user_profile(user_id)` - Get profile of specific user
|
|
- `follow_user(user_id)` - Follow a user or artist
|
|
- `unfollow_user(user_id)` - Unfollow a user or artist
|
|
- `update_profile(**kwargs)` - Update current user's profile
|
|
|
|
### Music Operations (`client.music`)
|
|
|
|
- `search(query)` - Search for songs, artists, and albums
|
|
- `get_album(album_id)` - Get detailed album information
|
|
- `get_song(song_id)` - Get detailed song information
|
|
- `get_artist(artist_id)` - Get detailed artist information
|
|
- `get_recommendations(limit=None)` - Get personalized recommendations
|
|
- `get_playlists()` - Get user's playlists
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
- `songbox_TOKEN` - Authentication token for CLI usage
|
|
|
|
### Client Configuration
|
|
|
|
```python
|
|
client = SongboxClient(
|
|
timeout=30.0, # Request timeout in seconds
|
|
headers={"Custom-Header": "value"} # Additional headers
|
|
)
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The library provides specific exceptions for different error types:
|
|
|
|
```python
|
|
from songbox.exceptions import (
|
|
songboxError,
|
|
AuthenticationError,
|
|
APIError,
|
|
NotFoundError,
|
|
ValidationError
|
|
)
|
|
|
|
try:
|
|
user_info = client.user.get_me()
|
|
except AuthenticationError:
|
|
print("Please login first")
|
|
except NotFoundError:
|
|
print("User not found")
|
|
except APIError as e:
|
|
print(f"API Error: {e.message} (Status: {e.status_code})")
|
|
except songboxError as e:
|
|
print(f"General error: {e}")
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
### Authentication Commands
|
|
|
|
```bash
|
|
songbox auth login --country-code <code> --mobile <number>
|
|
songbox auth verify --otp <otp> --verify-id <verify_id>
|
|
songbox auth refresh
|
|
songbox auth logout
|
|
```
|
|
|
|
### User Commands
|
|
|
|
```bash
|
|
songbox user me
|
|
songbox user following
|
|
```
|
|
|
|
### Music Commands
|
|
|
|
```bash
|
|
songbox music search <query>
|
|
songbox music album <album_id>
|
|
songbox music song <song_id>
|
|
songbox music artist <artist_id>
|
|
songbox music trending [--limit <number>]
|
|
```
|
|
|
|
### Output Formats
|
|
|
|
- `--format simple` (default) - Human-readable format
|
|
- `--format json` - JSON output
|
|
- `--format table` - Tabular format
|
|
|
|
## Examples
|
|
|
|
### Complete Authentication Flow
|
|
|
|
```python
|
|
from songbox import SongboxClient
|
|
from songbox.exceptions import AuthenticationError
|
|
|
|
client = SongboxClient()
|
|
|
|
try:
|
|
# Step 1: Initiate login
|
|
verify_id = client.auth.login("960", "7777777")
|
|
print(f"OTP sent! Verification ID: {verify_id}")
|
|
|
|
# Step 2: Get OTP from user
|
|
otp = input("Enter OTP: ")
|
|
|
|
# Step 3: Verify OTP and get token
|
|
token = client.auth.verify_otp(otp, verify_id)
|
|
print(f"Login successful! Token: {token}")
|
|
|
|
# Step 4: Use the API
|
|
user_info = client.user.get_me()
|
|
print(f"Welcome, {user_info['username']}!")
|
|
|
|
except AuthenticationError as e:
|
|
print(f"Authentication failed: {e}")
|
|
finally:
|
|
client.close()
|
|
```
|
|
|
|
### Music Discovery
|
|
|
|
```python
|
|
# Search and explore music
|
|
results = client.music.search("maldivian music")
|
|
|
|
for category in results:
|
|
print(f"\n{category['title']}:")
|
|
for item in category['items'][:3]: # Show top 3
|
|
print(f" {item['heading']} - {item['sub_heading']}")
|
|
|
|
# Get detailed info if it's a song
|
|
if category['title'] == 'Songs':
|
|
try:
|
|
song_details = client.music.get_song(item['destination_id'])
|
|
print(f" Duration: {song_details.get('duration', 'Unknown')}s")
|
|
except:
|
|
pass
|
|
|
|
```
|
|
|
|
## Development
|
|
|
|
### Setting up for Development
|
|
|
|
```bash
|
|
git clone https://git.cubable.date/CustomIcon/songbox
|
|
cd songbox
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
### Code Formatting
|
|
|
|
```bash
|
|
black songbox/
|
|
flake8 songbox/
|
|
mypy songbox/
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
---
|
|
|
|
**Note**: This is an unofficial client library. songbox is a trademark of its respective owners.
|