feat: add initial songbox API client library
This commit introduces the initial version of the songbox API client library, including: - Core client implementation with authentication and HTTP handling - Modular sub-clients for auth, user, and music operations - Comprehensive exception hierarchy for error handling - CLI interface with support for all API operations - Setup configuration with dependencies and package metadata - Documentation including README with usage examples
This commit is contained in:
284
README.md
Normal file
284
README.md
Normal file
@ -0,0 +1,284 @@
|
||||
# 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://github.com/yourusername/songbox.git
|
||||
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://github.com/yourusername/songbox.git
|
||||
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.
|
||||
Reference in New Issue
Block a user