Metadata-Version: 2.4
Name: record-shelf
Version: 1.0.0
Summary: A tool for creating custom reports from music collection data
Home-page: https://github.com/bryankemp/record-shelf
Author: Bryan Kemp
Author-email: Bryan Kemp <bryan@kempville.com>
Project-URL: Homepage, https://github.com/bryankemp/record-shelf
Project-URL: Bug Reports, https://github.com/bryankemp/record-shelf/issues
Project-URL: Source, https://github.com/bryankemp/record-shelf
Project-URL: Documentation, https://record-shelf.readthedocs.io/
Project-URL: Changelog, https://github.com/bryankemp/record-shelf/blob/main/CHANGELOG.md
Keywords: discogs,music,collection,report,excel,csv
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Office/Business
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: discogs-client>=2.3.0
Requires-Dist: click>=8.1.0
Requires-Dist: tqdm>=4.65.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pylint>=2.15.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: tox>=4.0.0; extra == "dev"
Requires-Dist: build>=0.8.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: sphinx>=8.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == "dev"
Requires-Dist: sphinx-click>=6.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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!

