API Reference
Record Shelf provides a well-structured API for developers who want to integrate music collection reporting functionality into their own applications.
Core Modules
Quick Reference
Core Classes
|
Application configuration |
|
Generates custom reports from Discogs collection data |
Main Functions
|
Main entry point for the CLI application. |
|
Setup logging configuration |
|
Print collection statistics in a readable format |
Usage Examples
Basic API Usage
from record_shelf import Config, ReportGenerator
# Create configuration
config = Config(token="your_discogs_token")
# Initialize report generator
generator = ReportGenerator(config)
# Fetch collection data
data = generator.fetch_collection_data("username")
# Generate report
generator.create_report(data, "output.xlsx", "xlsx")
Advanced Usage
from record_shelf import Config, ReportGenerator
from record_shelf.utils import setup_logging, print_stats
# Setup logging
setup_logging(debug=True)
# Create configuration with custom settings
config = Config(
token="your_discogs_token",
user_agent="MyApp/1.0",
rate_limit_delay=2.0,
debug=True
)
# Initialize report generator
generator = ReportGenerator(config)
# Get available categories
categories = generator.get_user_categories("username")
print(f"Available categories: {categories}")
# Fetch filtered data
data = generator.fetch_collection_data(
username="username",
category_filter="Vinyl"
)
# Generate statistics
stats = generator.generate_summary_stats(data)
print_stats(stats)
# Create multiple format reports
generator.create_report(data, "vinyl.xlsx", "xlsx")
generator.create_report(data, "vinyl.csv", "csv")
generator.create_report(data, "vinyl.html", "html")
Type Hints
Record Shelf includes comprehensive type hints for better IDE support and code quality:
from typing import Dict, List, Any, Optional
from record_shelf import Config, ReportGenerator
def process_collection(
username: str,
token: str,
category_filter: Optional[str] = None
) -> List[Dict[str, Any]]:
config = Config(token=token)
generator = ReportGenerator(config)
return generator.fetch_collection_data(username, category_filter)
Error Handling
from record_shelf import Config, ReportGenerator
import logging
try:
config = Config(token="invalid_token")
generator = ReportGenerator(config)
data = generator.fetch_collection_data("username")
except ValueError as e:
logging.error(f"Configuration error: {e}")
except Exception as e:
logging.error(f"API error: {e}")
Customization
Custom Configuration
from record_shelf import Config
# Custom configuration
config = Config(
token="your_token",
user_agent="CustomApp/2.0",
rate_limit_delay=0.5, # Faster requests (be careful!)
debug=True
)
Custom Processing
from record_shelf import ReportGenerator
import pandas as pd
# Custom data processing
def process_vinyl_only(data):
df = pd.DataFrame(data)
vinyl_only = df[df['format'].str.contains('Vinyl', na=False)]
return vinyl_only.to_dict('records')
# Use with generator
generator = ReportGenerator(config)
raw_data = generator.fetch_collection_data("username")
vinyl_data = process_vinyl_only(raw_data)
generator.create_report(vinyl_data, "vinyl_only.xlsx")
Extending Functionality
Custom Report Generator
from record_shelf import ReportGenerator, Config
import pandas as pd
class CustomReportGenerator(ReportGenerator):
def create_summary_report(self, data, output_path):
"""Create a summary report with statistics."""
df = pd.DataFrame(data)
summary = {
'total_items': len(df),
'unique_artists': df['artist'].nunique(),
'formats': df['format'].value_counts().to_dict(),
'years': df['year'].value_counts().sort_index().to_dict()
}
# Create summary DataFrame
summary_df = pd.DataFrame([
{'Metric': k, 'Value': v} for k, v in summary.items()
if not isinstance(v, dict)
])
with pd.ExcelWriter(output_path, engine='openpyxl') as writer:
summary_df.to_excel(writer, sheet_name='Summary', index=False)
df.to_excel(writer, sheet_name='Full Data', index=False)
# Usage
config = Config(token="your_token")
generator = CustomReportGenerator(config)
data = generator.fetch_collection_data("username")
generator.create_summary_report(data, "summary.xlsx")
Integration Examples
Flask Web Application
from flask import Flask, request, send_file
from record_shelf import Config, ReportGenerator
import tempfile
import os
app = Flask(__name__)
@app.route('/generate_report', methods=['POST'])
def generate_report():
username = request.form['username']
token = request.form['token']
format_type = request.form.get('format', 'xlsx')
try:
config = Config(token=token)
generator = ReportGenerator(config)
data = generator.fetch_collection_data(username)
# Create temporary file
with tempfile.NamedTemporaryFile(delete=False, suffix=f'.{format_type}') as tmp:
generator.create_report(data, tmp.name, format_type)
return send_file(tmp.name, as_attachment=True,
download_name=f'{username}_collection.{format_type}')
except Exception as e:
return f"Error: {e}", 400
CLI Integration
import click
from record_shelf import Config, ReportGenerator
@click.command()
@click.option('--username', required=True)
@click.option('--token', envvar='DISCOGS_TOKEN')
@click.option('--output', default='report.xlsx')
def my_custom_command(username, token, output):
"""Custom command using Record Shelf API."""
config = Config(token=token)
generator = ReportGenerator(config)
click.echo(f"Fetching data for {username}...")
data = generator.fetch_collection_data(username)
click.echo(f"Generating report to {output}...")
generator.create_report(data, output)
click.echo("Done!")
if __name__ == '__main__':
my_custom_command()