record-shelf 1.0.0

A tool for creating custom reports from music collection data

Discogs Custom Reports Tool

A Python tool for creating custom reports from your Discogs collection with sorting by shelf and then alphabetically.

Features

• Generate detailed collection reports in Excel, CSV, or HTML format
• Sort items by shelf, then alphabetically by artist and title
• Filter reports by specific shelves
• Export separate sheets for each shelf (Excel format)
• Command-line interface for easy automation
• Rate limiting to respect Discogs API limits
• Comprehensive logging and error handling

Setup

1. Get a Discogs API Token

1. Go to Discogs Developer Settings
2. Create a new application or use an existing one
3. Generate a personal access token
4. Save your token - you'll need it to run the tool

2. Install Dependencies

# Activate virtual environment
source venv/bin/activate

# Install required packages
pip install -r requirements.txt

3. Set Environment Variable (Optional)

You can set your Discogs token as an environment variable:

export DISCOGS_TOKEN="your_token_here"

Or pass it directly via the --token option when running commands.

Usage

Generate a Full Collection Report

python main.py generate --username YOUR_DISCOGS_USERNAME --output my_collection.xlsx

Generate Report with Token

python main.py generate --token YOUR_TOKEN --username YOUR_DISCOGS_USERNAME

Filter by Specific Shelf

python main.py generate --username YOUR_DISCOGS_USERNAME --shelf "Vinyl" --output vinyl_collection.xlsx

Generate CSV Report

python main.py generate --username YOUR_DISCOGS_USERNAME --format csv --output collection.csv

List Available Shelves

python main.py list-shelves --username YOUR_DISCOGS_USERNAME

Enable Debug Logging

python main.py --debug generate --username YOUR_DISCOGS_USERNAME

Report Format

The generated reports include the following columns:

• Shelf: Collection folder/shelf name
• Artist: Artist name(s)
• Title: Release title
• Label: Record label(s)
• Catalog Number: Label catalog number(s)
• Format: Format details (e.g., "Vinyl, LP, Album")
• Year: Release year
• Genre: Music genre(s)
• Style: Music style(s)
• Country: Country of release
• Discogs ID: Unique Discogs release ID
• Master ID: Master release ID (if applicable)
• Rating: Your rating (if set)
• Notes: Your personal notes (if any)

Output Formats

Excel (.xlsx)

• Main "Collection" sheet with all items
• Separate sheet for each shelf
• Sortable columns and formatting

CSV (.csv)

• Single file with all collection data
• Compatible with spreadsheet applications

HTML (.html)

• Web-viewable table format
• Can be opened in any web browser

Command Line Options

Global Options

• --debug: Enable debug logging

Generate Command

• --token: Discogs API token (or use DISCOGS_TOKEN env var)
• --username: Your Discogs username (required)
• --output, -o: Output file path (default: discogs_report.xlsx)
• --shelf: Filter by specific shelf name (optional)
• --format: Output format - xlsx, csv, or html (default: xlsx)

List Shelves Command

• --token: Discogs API token (or use DISCOGS_TOKEN env var)
• --username: Your Discogs username (required)

Rate Limiting

The tool includes built-in rate limiting to respect Discogs API limits:

• 1 second delay between API calls (configurable)
• Progress bars show processing status
• Automatic retry on rate limit errors

Troubleshooting

Common Issues

Authentication Error

• Verify your Discogs token is correct
• Ensure token has proper permissions
• Check if token is set via environment variable or --token option

Empty Collection

• Verify the username is correct
• Check if the collection is public
• Ensure the user has items in their collection

Missing Shelves

• Some collections may not have custom shelves
• Default shelf names vary by user

Debug Mode

Run with --debug flag to see detailed logging:

python main.py --debug generate --username YOUR_USERNAME

Logs are also saved to discogs_tool.log.

Development

Project Structure

discogs-report-tool/
├── main.py              # Main CLI application
├── config.py            # Configuration management
├── report_generator.py  # Core report generation logic
├── utils.py             # Utility functions
├── requirements.txt     # Python dependencies
├── README.md           # This file
└── venv/               # Virtual environment

Adding New Features

1. Core logic goes in report_generator.py
2. CLI commands are added to main.py
3. Configuration options go in config.py
4. Utilities and helpers go in utils.py

License

This project is for personal use. Please respect Discogs' Terms of Service and API rate limits.

Contributing

Feel free to submit issues and enhancement requests!