Configuration

Record Shelf provides several configuration options to customize its behavior.

API Token Setup

Before using Record Shelf, you need to obtain a Discogs API token:

Visit Discogs Developer Settings

Go to https://www.discogs.com/settings/developers
Create or Select Application
- Create a new application or use an existing one
- Fill in the required information
- Note your Consumer Key and Consumer Secret
Generate Personal Access Token
- Click “Generate new token”
- Copy the generated token
- Store it securely

Token Configuration

Environment Variable (Recommended)

Set the token as an environment variable:

# Linux/Mac
export DISCOGS_TOKEN="your_token_here"

# Windows Command Prompt
set DISCOGS_TOKEN=your_token_here

# Windows PowerShell
$env:DISCOGS_TOKEN="your_token_here"

Command Line Option

Pass the token directly to commands:

record-shelf --token "your_token_here" generate --username myuser

Configuration File

Create a .env file in your project directory:

DISCOGS_TOKEN=your_token_here

Advanced Configuration

Rate Limiting

Record Shelf includes built-in rate limiting to respect Discogs API limits:

Default delay: 1 second between API calls
Configurable: Can be adjusted via code configuration
Automatic: No manual intervention required

To modify rate limiting in code:

from record_shelf import Config

config = Config(
    token="your_token",
    rate_limit_delay=2.0  # 2 seconds between requests
)

User Agent

Customize the User-Agent header for API requests:

from record_shelf import Config

config = Config(
    token="your_token",
    user_agent="MyApp/1.0"
)

Logging Configuration

Record Shelf provides detailed logging:

Log Levels:

INFO: Standard operation messages
DEBUG: Detailed debugging information
WARNING: Non-fatal issues
ERROR: Fatal errors

Enable Debug Logging:

record-shelf --debug generate --username myuser

Log File Location:

Default: record_shelf.log in current directory
Contains detailed operation logs
Rotated automatically

Output Configuration

File Formats

Record Shelf supports multiple output formats:

Supported Formats
Format	Extension	Description
Excel	`.xlsx`	Default format with multiple sheets
CSV	`.csv`	Comma-separated values
HTML	`.html`	Web-viewable table

Default Settings

Default output file: collection_report.xlsx
Default format: Excel (.xlsx)
Default location: Current working directory

Custom Output:

record-shelf generate --username myuser --output my_collection.csv --format csv

Filtering Configuration

Shelf Filtering

Filter reports by specific shelves:

# Single shelf
record-shelf generate --username myuser --shelf "Vinyl"

# List available shelves first
record-shelf list-shelves --username myuser

Data Filtering

Record Shelf automatically filters and organizes data:

Sorting: By shelf, then artist, then title
Deduplication: Removes duplicate entries
Cleaning: Handles missing or invalid data gracefully

Security Configuration

Token Security

Best Practices:

Store tokens in environment variables
Never commit tokens to version control
Use different tokens for different environments
Rotate tokens periodically
Limit token permissions if possible

Token Storage:

# Good: Environment variable
export DISCOGS_TOKEN="token_here"

# Bad: Hardcoded in script
config = Config(token="token_here")  # Don't do this!

Network Security

All API calls use HTTPS
No sensitive data stored locally
Rate limiting prevents abuse
Respectful API usage

Performance Configuration

Optimization Settings

For Large Collections:

Use shelf filtering to process smaller subsets
Increase rate limiting delay for stability
Use CSV format for faster processing
Run during off-peak hours

For Slow Networks:

Increase rate limiting delay
Enable debug mode to monitor progress
Process during better network conditions

Memory Optimization:

CSV format uses less memory than Excel
Process shelves separately for very large collections
Close other applications during processing

Troubleshooting Configuration

Common Configuration Issues

Token Not Found:

Error: Discogs API token is required

Solution:
- Set DISCOGS_TOKEN environment variable
- Or use --token command line option

Invalid Token:

Error: Authentication failed

Solution:
- Verify token is correct
- Check token hasn't expired
- Ensure token has proper permissions

Permission Errors:

Error: Permission denied writing to file

Solution:
- Check file permissions
- Ensure write access to output directory
- Try different output location

Configuration Validation

Test your configuration:

# Test basic connectivity
record-shelf list-shelves --username your_username

# Test with debug logging
record-shelf --debug list-shelves --username your_username

# Test output formats
record-shelf generate --username your_username --format csv --output test.csv

Development Configuration

Development Environment

For development and testing:

# Clone repository
git clone https://github.com/username/record-shelf.git
cd record-shelf

# Setup development environment
make setup

# Activate virtual environment
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

Testing Configuration

Test environment setup:

# Run tests
pytest

# Run with coverage
pytest --cov=record_shelf

# Run linting
make lint

# Run all checks
make dev-test