record-shelf 1.0.0
A tool for creating custom reports from music collection data
Requires Python: >=3.8
Keywords: discogs, music, collection, report, excel, csv

# 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](https://www.discogs.com/settings/developers)
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

```bash
# 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:

```bash
export DISCOGS_TOKEN="your_token_here"
```

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

## Usage

### Generate a Full Collection Report

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

### Generate Report with Token

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

### Filter by Specific Shelf

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

### Generate CSV Report

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

### List Available Shelves

```bash
python main.py list-shelves --username YOUR_DISCOGS_USERNAME
```

### Enable Debug Logging

```bash
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:

```bash
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!