# Discogs Record Shelf
A Python tool for creating custom reports from your Discogs music collection with sorting by shelf and then alphabetically.
## Installation
```bash
pip install discogs-record-shelf
```
## 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. Quick Start
After installation, the `record-shelf` command is available globally.
### 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
record-shelf generate --username YOUR_DISCOGS_USERNAME --output my_collection.xlsx
```
### Generate Report with Token
```bash
record-shelf generate --token YOUR_TOKEN --username YOUR_DISCOGS_USERNAME
```
### Filter by Specific Shelf
```bash
record-shelf generate --username YOUR_DISCOGS_USERNAME --shelf "Vinyl" --output vinyl_collection.xlsx
```
### Generate CSV Report
```bash
record-shelf generate --username YOUR_DISCOGS_USERNAME --format csv --output collection.csv
```
### List Available Shelves
```bash
record-shelf list-shelves --username YOUR_DISCOGS_USERNAME
```
### Enable Debug Logging
```bash
record-shelf --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
record-shelf --debug generate --username YOUR_USERNAME
```
Logs are also saved to `record_shelf.log`.
## Development
### Project Structure
```
discogs-record-shelf/
├── record_shelf/
│ ├── __init__.py # Package initialization
│ ├── cli.py # Main CLI application
│ ├── config.py # Configuration management
│ ├── report_generator.py # Core report generation logic
│ └── utils.py # Utility functions
├── docs/ # Documentation
├── tests/ # Test suite
├── pyproject.toml # Project configuration
├── README.md # This file
└── LICENSE # BSD 3-Clause License
```
### Adding New Features
1. Core logic goes in `report_generator.py`
2. CLI commands are added to `cli.py`
3. Configuration options go in `config.py`
4. Utilities and helpers go in `utils.py`
## License
This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.
Please respect Discogs' Terms of Service and API rate limits when using this tool.
## Links
- **PyPI**: https://pypi.org/project/discogs-record-shelf/
- **GitHub**: https://github.com/bryankemp/discogs-record-shelf
- **Documentation**: https://discogs-record-shelf.readthedocs.io/
## Contributing
Feel free to submit issues and enhancement requests on GitHub!
Raw data
{
"_id": null,
"home_page": null,
"name": "discogs-record-shelf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "discogs, music, collection, report, excel, csv",
"author": null,
"author_email": "Bryan Kemp <bryan@kempville.com>",
"download_url": "https://files.pythonhosted.org/packages/02/78/b98560771c85fb500545b1ba494d80058130710324d61c67ddc15c633948/discogs_record_shelf-1.0.2.tar.gz",
"platform": null,
"description": "# Discogs Record Shelf\n\nA Python tool for creating custom reports from your Discogs music collection with sorting by shelf and then alphabetically.\n\n## Installation\n\n```bash\npip install discogs-record-shelf\n```\n\n## Features\n\n- Generate detailed collection reports in Excel, CSV, or HTML format\n- Sort items by shelf, then alphabetically by artist and title\n- Filter reports by specific shelves\n- Export separate sheets for each shelf (Excel format)\n- Command-line interface for easy automation\n- Rate limiting to respect Discogs API limits\n- Comprehensive logging and error handling\n\n## Setup\n\n### 1. Get a Discogs API Token\n\n1. Go to [Discogs Developer Settings](https://www.discogs.com/settings/developers)\n2. Create a new application or use an existing one\n3. Generate a personal access token\n4. Save your token - you'll need it to run the tool\n\n### 2. Quick Start\n\nAfter installation, the `record-shelf` command is available globally.\n\n### 3. Set Environment Variable (Optional)\n\nYou can set your Discogs token as an environment variable:\n\n```bash\nexport DISCOGS_TOKEN=\"your_token_here\"\n```\n\nOr pass it directly via the `--token` option when running commands.\n\n## Usage\n\n### Generate a Full Collection Report\n\n```bash\nrecord-shelf generate --username YOUR_DISCOGS_USERNAME --output my_collection.xlsx\n```\n\n### Generate Report with Token\n\n```bash\nrecord-shelf generate --token YOUR_TOKEN --username YOUR_DISCOGS_USERNAME\n```\n\n### Filter by Specific Shelf\n\n```bash\nrecord-shelf generate --username YOUR_DISCOGS_USERNAME --shelf \"Vinyl\" --output vinyl_collection.xlsx\n```\n\n### Generate CSV Report\n\n```bash\nrecord-shelf generate --username YOUR_DISCOGS_USERNAME --format csv --output collection.csv\n```\n\n### List Available Shelves\n\n```bash\nrecord-shelf list-shelves --username YOUR_DISCOGS_USERNAME\n```\n\n### Enable Debug Logging\n\n```bash\nrecord-shelf --debug generate --username YOUR_DISCOGS_USERNAME\n```\n\n## Report Format\n\nThe generated reports include the following columns:\n\n- **Shelf**: Collection folder/shelf name\n- **Artist**: Artist name(s)\n- **Title**: Release title\n- **Label**: Record label(s)\n- **Catalog Number**: Label catalog number(s)\n- **Format**: Format details (e.g., \"Vinyl, LP, Album\")\n- **Year**: Release year\n- **Genre**: Music genre(s)\n- **Style**: Music style(s)\n- **Country**: Country of release\n- **Discogs ID**: Unique Discogs release ID\n- **Master ID**: Master release ID (if applicable)\n- **Rating**: Your rating (if set)\n- **Notes**: Your personal notes (if any)\n\n## Output Formats\n\n### Excel (.xlsx)\n- Main \"Collection\" sheet with all items\n- Separate sheet for each shelf\n- Sortable columns and formatting\n\n### CSV (.csv)\n- Single file with all collection data\n- Compatible with spreadsheet applications\n\n### HTML (.html)\n- Web-viewable table format\n- Can be opened in any web browser\n\n## Command Line Options\n\n### Global Options\n- `--debug`: Enable debug logging\n\n### Generate Command\n- `--token`: Discogs API token (or use DISCOGS_TOKEN env var)\n- `--username`: Your Discogs username (required)\n- `--output`, `-o`: Output file path (default: discogs_report.xlsx)\n- `--shelf`: Filter by specific shelf name (optional)\n- `--format`: Output format - xlsx, csv, or html (default: xlsx)\n\n### List Shelves Command\n- `--token`: Discogs API token (or use DISCOGS_TOKEN env var)\n- `--username`: Your Discogs username (required)\n\n## Rate Limiting\n\nThe tool includes built-in rate limiting to respect Discogs API limits:\n- 1 second delay between API calls (configurable)\n- Progress bars show processing status\n- Automatic retry on rate limit errors\n\n## Troubleshooting\n\n### Common Issues\n\n**Authentication Error**\n- Verify your Discogs token is correct\n- Ensure token has proper permissions\n- Check if token is set via environment variable or --token option\n\n**Empty Collection**\n- Verify the username is correct\n- Check if the collection is public\n- Ensure the user has items in their collection\n\n**Missing Shelves**\n- Some collections may not have custom shelves\n- Default shelf names vary by user\n\n### Debug Mode\n\nRun with `--debug` flag to see detailed logging:\n\n```bash\nrecord-shelf --debug generate --username YOUR_USERNAME\n```\n\nLogs are also saved to `record_shelf.log`.\n\n## Development\n\n### Project Structure\n\n```\ndiscogs-record-shelf/\n\u251c\u2500\u2500 record_shelf/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 cli.py # Main CLI application\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 report_generator.py # Core report generation logic\n\u2502 \u2514\u2500\u2500 utils.py # Utility functions\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 README.md # This file\n\u2514\u2500\u2500 LICENSE # BSD 3-Clause License\n```\n\n### Adding New Features\n\n1. Core logic goes in `report_generator.py`\n2. CLI commands are added to `cli.py`\n3. Configuration options go in `config.py`\n4. Utilities and helpers go in `utils.py`\n\n## License\n\nThis project is licensed under the BSD 3-Clause License. See the LICENSE file for details.\n\nPlease respect Discogs' Terms of Service and API rate limits when using this tool.\n\n## Links\n\n- **PyPI**: https://pypi.org/project/discogs-record-shelf/\n- **GitHub**: https://github.com/bryankemp/discogs-record-shelf\n- **Documentation**: https://discogs-record-shelf.readthedocs.io/\n\n## Contributing\n\nFeel free to submit issues and enhancement requests on GitHub!\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A tool for creating custom reports from music collection data",
"version": "1.0.2",
"project_urls": {
"Bug Reports": "https://github.com/bryankemp/discogs-record-shelf/issues",
"Changelog": "https://github.com/bryankemp/discogs-record-shelf/blob/main/CHANGELOG.md",
"Documentation": "https://discogs-record-shelf.readthedocs.io/",
"Homepage": "https://github.com/bryankemp/discogs-record-shelf",
"Source": "https://github.com/bryankemp/discogs-record-shelf"
},
"split_keywords": [
"discogs",
" music",
" collection",
" report",
" excel",
" csv"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fa2d6315bcedf1689a928a46f555d4096a07ab73ad1ea66c0d11ef97ef93e03e",
"md5": "555944d78932db141cc09575e2e93857",
"sha256": "57b9b547c8134ea9db3bf305faffe888cf3f817127c3ffb360d9b525d974815f"
},
"downloads": -1,
"filename": "discogs_record_shelf-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "555944d78932db141cc09575e2e93857",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10933,
"upload_time": "2025-07-19T03:34:48",
"upload_time_iso_8601": "2025-07-19T03:34:48.448472Z",
"url": "https://files.pythonhosted.org/packages/fa/2d/6315bcedf1689a928a46f555d4096a07ab73ad1ea66c0d11ef97ef93e03e/discogs_record_shelf-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0278b98560771c85fb500545b1ba494d80058130710324d61c67ddc15c633948",
"md5": "e8cf55b16b05205300b9dbcd0412202c",
"sha256": "aafc4a088f4f4518d713fa49fd19ff95cacf8519972a67b1434022f6284e953f"
},
"downloads": -1,
"filename": "discogs_record_shelf-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "e8cf55b16b05205300b9dbcd0412202c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16411,
"upload_time": "2025-07-19T03:34:49",
"upload_time_iso_8601": "2025-07-19T03:34:49.787843Z",
"url": "https://files.pythonhosted.org/packages/02/78/b98560771c85fb500545b1ba494d80058130710324d61c67ddc15c633948/discogs_record_shelf-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 03:34:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bryankemp",
"github_project": "discogs-record-shelf",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "openpyxl",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "discogs-client",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.65.0"
]
]
}
],
"tox": true,
"lcname": "discogs-record-shelf"
}
JSON
