ronschaeffer-ics-calendar-utils 0.2.2

Python utility library for generating and manipulating ICS calendar files

📅 ICS Calendar Utils

A Python library for processing events and generating ICS calendar files from various data sources.

✨ Features

• Event Processing: Normalize events from any source with customizable field mappings
• Date/Time Parsing: Handles various date and time formats
• Event Validation: Data quality validation before calendar generation
• Statistics & Analytics: Event data insights and reporting
• Error Handling: Detailed error reporting for invalid data
• ICS Generation: RFC 5545 compliant ICS calendar files
• Modern Python: Built with Python 3.11+ type hints

💎 Installation

pip install ics-calendar-utils

🚀 Usage

Basic Usage

from ics_calendar_utils import create_calendar

# Your event data from any source
events = [
    {
        'title': 'Team Meeting',
        'date': '2024-12-20',
        'time': '14:00',
        'location': 'Conference Room A',
        'description': 'Weekly team sync'
    },
    {
        'title': 'Project Deadline',
        'date': 'Dec 25, 2024',
        'location': 'Online'
    }
]

# Simple field mapping
field_mapping = {
    'title': 'summary',
    'date': 'dtstart_date',
    'time': 'dtstart_time'
}

# Generate ICS calendar
ics_content = create_calendar(
    events,
    calendar_name="My Calendar",
    filename="my_events.ics",
    field_mapping=field_mapping
)

print("Calendar generated successfully!")

⚙️ Configuration

Advanced Usage

For more control over processing and detailed results:

from ics_calendar_utils import process_and_generate

# Events with custom field names
events = [
    {
        'event_name': 'Rugby Match: England vs Wales',
        'event_date': '2024-12-21',
        'kickoff_time': '15:00',
        'venue': 'Twickenham Stadium',
        'competition': 'Six Nations',
        'ticket_url': 'https://example.com/tickets'
    }
]

# Custom field mapping
field_mapping = {
    'event_name': 'summary',
    'event_date': 'dtstart_date',
    'kickoff_time': 'dtstart_time',
    'venue': 'location',
    'competition': 'categories',
    'ticket_url': 'url'
}

# Process with detailed results
result = process_and_generate(
    events,
    calendar_name="Rugby Fixtures",
    output_file="rugby_calendar.ics",
    field_mapping=field_mapping,
    validate=True
)

# Access detailed information
print(f"Processed {result['stats']['total_events']} events")
print(f"Events with times: {result['stats']['events_with_time']}")
print(f"Date range: {result['stats']['date_range']['earliest']} to {result['stats']['date_range']['latest']}")

if result['processing_errors']:
    print("Processing errors:", result['processing_errors'])

Low-Level API

For maximum control:

from ics_calendar_utils import EventProcessor, ICSGenerator

# Initialize components
processor = EventProcessor()
processor.add_mapping({
    'event_title': 'summary',
    'start_date': 'dtstart_date'
})

generator = ICSGenerator(calendar_name="Custom Calendar")

# Process events
processed_events = processor.process_events(raw_events)

# Validate before generation
validation_errors = generator.validate_events(processed_events)
if validation_errors:
    print("Validation issues:", validation_errors)

# Generate ICS
ics_content = generator.generate_ics(processed_events)

🎯 Supported Date/Time Formats

The library parses various date and time formats:

Date Formats

• ISO format: 2024-12-20
• US format: Dec 20, 2024 or December 20, 2024
• European format: 20/12/2024 or 20 December 2024
• Various separators: dots, slashes, spaces, hyphens

Time Formats

• 24-hour: 14:30, 09:00
• 12-hour: 2:30pm, 9am, noon
• Multiple times: 14:30 & 16:45
• Flexible separators and spacing

🧪 Error Handling

The library provides error handling:

result = process_and_generate(events, validate=True)

# Check for issues
if result['processing_errors']:
    print("Data processing issues:")
    for error in result['processing_errors']:
        print(f"  - {error}")

if result['validation_errors']:
    print("Validation issues:")
    for error in result['validation_errors']:
        print(f"  - {error}")

🛠️ Development

Setup

# Clone the repository
git clone https://github.com/ronschaeffer/ics-calendar-utils.git
cd ics-calendar-utils

# Install with Poetry (recommended)
poetry install

# Or install in development mode
pip install -e .

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=ics_calendar_utils

# Run specific test
poetry run pytest tests/test_event_processor.py

Code Quality

# Format code
poetry run ruff format

# Lint code
poetry run ruff check

# Fix auto-fixable issues
poetry run ruff check --fix

📋 Examples

Check out the examples/ directory for working examples:

• Basic Usage: Simple calendar generation
• Processing Examples: Custom field mapping and error handling
• Rugby Fixtures: Sports calendar example

🧪 Testing

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=ics_calendar_utils

# Run specific test
poetry run pytest tests/test_event_processor.py

Code Quality

# Format code
poetry run ruff format

# Lint code
poetry run ruff check

# Fix auto-fixable issues
poetry run ruff check --fix

🤝 Contributing

Contributions are welcome! Please open an issue to discuss proposed changes or submit a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

For questions, issues, or contributions, please open an issue on GitHub.