# 📅 ICS Calendar Utils
[](https://badge.fury.io/py/ronschaeffer-ics-calendar-utils)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](https://github.com/ronschaeffer/ics_calendar_utils/actions)
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
```bash
pip install ics-calendar-utils
```
## 🚀 Usage
### Basic Usage
```python
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:
```python
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:
```python
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:
```python
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
```bash
# 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
```bash
# 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
```bash
# 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/`](examples/) directory for working examples:
- **Basic Usage**: Simple calendar generation
- **Processing Examples**: Custom field mapping and error handling
- **Rugby Fixtures**: Sports calendar example
## 🧪 Testing
```bash
# 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
```bash
# 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](LICENSE) file for details.
## 📞 Support
For questions, issues, or contributions, please open an issue on GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "ronschaeffer-ics-calendar-utils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "python, ics, calendar, events",
"author": "ronschaeffer",
"author_email": "ron@ronschaeffer.com",
"download_url": "https://files.pythonhosted.org/packages/38/df/767113a5c3dd5f6aa3ac36c3f7b50f4a40b3de562cd37ce3c4f80162abc9/ronschaeffer_ics_calendar_utils-0.2.2.tar.gz",
"platform": null,
"description": "# \ud83d\udcc5 ICS Calendar Utils\n\n[](https://badge.fury.io/py/ronschaeffer-ics-calendar-utils)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/ronschaeffer/ics_calendar_utils/actions)\n\nA Python library for processing events and generating ICS calendar files from various data sources.\n\n## \u2728 Features\n\n- **Event Processing**: Normalize events from any source with customizable field mappings\n- **Date/Time Parsing**: Handles various date and time formats\n- **Event Validation**: Data quality validation before calendar generation\n- **Statistics & Analytics**: Event data insights and reporting\n- **Error Handling**: Detailed error reporting for invalid data\n- **ICS Generation**: RFC 5545 compliant ICS calendar files\n- **Modern Python**: Built with Python 3.11+ type hints\n\n## \ud83d\udc8e Installation\n\n```bash\npip install ics-calendar-utils\n```\n\n## \ud83d\ude80 Usage\n\n### Basic Usage\n\n```python\nfrom ics_calendar_utils import create_calendar\n\n# Your event data from any source\nevents = [\n {\n 'title': 'Team Meeting',\n 'date': '2024-12-20',\n 'time': '14:00',\n 'location': 'Conference Room A',\n 'description': 'Weekly team sync'\n },\n {\n 'title': 'Project Deadline',\n 'date': 'Dec 25, 2024',\n 'location': 'Online'\n }\n]\n\n# Simple field mapping\nfield_mapping = {\n 'title': 'summary',\n 'date': 'dtstart_date',\n 'time': 'dtstart_time'\n}\n\n# Generate ICS calendar\nics_content = create_calendar(\n events,\n calendar_name=\"My Calendar\",\n filename=\"my_events.ics\",\n field_mapping=field_mapping\n)\n\nprint(\"Calendar generated successfully!\")\n```\n\n## \u2699\ufe0f Configuration\n\n### Advanced Usage\n\nFor more control over processing and detailed results:\n\n```python\nfrom ics_calendar_utils import process_and_generate\n\n# Events with custom field names\nevents = [\n {\n 'event_name': 'Rugby Match: England vs Wales',\n 'event_date': '2024-12-21',\n 'kickoff_time': '15:00',\n 'venue': 'Twickenham Stadium',\n 'competition': 'Six Nations',\n 'ticket_url': 'https://example.com/tickets'\n }\n]\n\n# Custom field mapping\nfield_mapping = {\n 'event_name': 'summary',\n 'event_date': 'dtstart_date',\n 'kickoff_time': 'dtstart_time',\n 'venue': 'location',\n 'competition': 'categories',\n 'ticket_url': 'url'\n}\n\n# Process with detailed results\nresult = process_and_generate(\n events,\n calendar_name=\"Rugby Fixtures\",\n output_file=\"rugby_calendar.ics\",\n field_mapping=field_mapping,\n validate=True\n)\n\n# Access detailed information\nprint(f\"Processed {result['stats']['total_events']} events\")\nprint(f\"Events with times: {result['stats']['events_with_time']}\")\nprint(f\"Date range: {result['stats']['date_range']['earliest']} to {result['stats']['date_range']['latest']}\")\n\nif result['processing_errors']:\n print(\"Processing errors:\", result['processing_errors'])\n```\n\n### Low-Level API\n\nFor maximum control:\n\n```python\nfrom ics_calendar_utils import EventProcessor, ICSGenerator\n\n# Initialize components\nprocessor = EventProcessor()\nprocessor.add_mapping({\n 'event_title': 'summary',\n 'start_date': 'dtstart_date'\n})\n\ngenerator = ICSGenerator(calendar_name=\"Custom Calendar\")\n\n# Process events\nprocessed_events = processor.process_events(raw_events)\n\n# Validate before generation\nvalidation_errors = generator.validate_events(processed_events)\nif validation_errors:\n print(\"Validation issues:\", validation_errors)\n\n# Generate ICS\nics_content = generator.generate_ics(processed_events)\n```\n\n## \ud83c\udfaf Supported Date/Time Formats\n\nThe library parses various date and time formats:\n\n### Date Formats\n\n- ISO format: `2024-12-20`\n- US format: `Dec 20, 2024` or `December 20, 2024`\n- European format: `20/12/2024` or `20 December 2024`\n- Various separators: dots, slashes, spaces, hyphens\n\n### Time Formats\n\n- 24-hour: `14:30`, `09:00`\n- 12-hour: `2:30pm`, `9am`, `noon`\n- Multiple times: `14:30 & 16:45`\n- Flexible separators and spacing\n\n## \ud83e\uddea Error Handling\n\nThe library provides error handling:\n\n```python\nresult = process_and_generate(events, validate=True)\n\n# Check for issues\nif result['processing_errors']:\n print(\"Data processing issues:\")\n for error in result['processing_errors']:\n print(f\" - {error}\")\n\nif result['validation_errors']:\n print(\"Validation issues:\")\n for error in result['validation_errors']:\n print(f\" - {error}\")\n```\n\n## \ud83d\udee0\ufe0f Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/ronschaeffer/ics-calendar-utils.git\ncd ics-calendar-utils\n\n# Install with Poetry (recommended)\npoetry install\n\n# Or install in development mode\npip install -e .\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=ics_calendar_utils\n\n# Run specific test\npoetry run pytest tests/test_event_processor.py\n```\n\n### Code Quality\n\n```bash\n# Format code\npoetry run ruff format\n\n# Lint code\npoetry run ruff check\n\n# Fix auto-fixable issues\npoetry run ruff check --fix\n```\n\n## \ud83d\udccb Examples\n\nCheck out the [`examples/`](examples/) directory for working examples:\n\n- **Basic Usage**: Simple calendar generation\n- **Processing Examples**: Custom field mapping and error handling\n- **Rugby Fixtures**: Sports calendar example\n\n## \ud83e\uddea Testing\n\n```bash\n# Run all tests\npoetry run pytest\n\n# Run with coverage\npoetry run pytest --cov=ics_calendar_utils\n\n# Run specific test\npoetry run pytest tests/test_event_processor.py\n```\n\n### Code Quality\n\n```bash\n# Format code\npoetry run ruff format\n\n# Lint code\npoetry run ruff check\n\n# Fix auto-fixable issues\npoetry run ruff check --fix\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please open an issue to discuss proposed changes or submit a pull request.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udcde Support\n\nFor questions, issues, or contributions, please open an issue on GitHub.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python utility library for generating and manipulating ICS calendar files",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/ronschaeffer/ics_calendar_utils",
"Issues": "https://github.com/ronschaeffer/ics_calendar_utils/issues",
"Repository": "https://github.com/ronschaeffer/ics_calendar_utils.git"
},
"split_keywords": [
"python",
" ics",
" calendar",
" events"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d1698c276a05b35f0159508af18a6c583ab5b33159674b8db9f70d42039c0b5c",
"md5": "aac8b6ff4fda15f238b5328323ca3f89",
"sha256": "3c8cd8a42f623c7d55fbcccabb326c2e1c6ac5ea1b3192c1317c0ed8361c21a4"
},
"downloads": -1,
"filename": "ronschaeffer_ics_calendar_utils-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aac8b6ff4fda15f238b5328323ca3f89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 11749,
"upload_time": "2025-08-07T17:26:50",
"upload_time_iso_8601": "2025-08-07T17:26:50.178532Z",
"url": "https://files.pythonhosted.org/packages/d1/69/8c276a05b35f0159508af18a6c583ab5b33159674b8db9f70d42039c0b5c/ronschaeffer_ics_calendar_utils-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "38df767113a5c3dd5f6aa3ac36c3f7b50f4a40b3de562cd37ce3c4f80162abc9",
"md5": "17f202e1d8b29d7d31fec67da16442f2",
"sha256": "e5c0488c7ff906c010b89b77840dcffd7a05821f8818fc89f00f0ca23d1e7854"
},
"downloads": -1,
"filename": "ronschaeffer_ics_calendar_utils-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "17f202e1d8b29d7d31fec67da16442f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 12158,
"upload_time": "2025-08-07T17:26:51",
"upload_time_iso_8601": "2025-08-07T17:26:51.113697Z",
"url": "https://files.pythonhosted.org/packages/38/df/767113a5c3dd5f6aa3ac36c3f7b50f4a40b3de562cd37ce3c4f80162abc9/ronschaeffer_ics_calendar_utils-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 17:26:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ronschaeffer",
"github_project": "ics_calendar_utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ronschaeffer-ics-calendar-utils"
}
JSON
