kayrozen.com
atproto-calendar-import is a library and CLI tool for importing calendar events in python & rust
1# AT Protocol Calendar Import
2
3A Python library and CLI tool for importing calendar events from external providers (Google, Outlook, Apple, ICS) into the [AT Protocol](https://atproto.com/).
4
5## Features
6
7- 📅 **Multiple Calendar Sources**: Google Calendar, Microsoft Outlook, Apple Calendar (CalDAV), ICS files/URLs
8- 🔄 **AT Protocol Integration**: Publish events directly to AT Protocol/Bluesky
9- 🌐 **REST API**: FastAPI-based server for integration
10- 💻 **CLI Tool**: Command-line interface for batch imports
11- 🔍 **Smart Event Detection**: Automatically detects virtual/hybrid/in-person events
12- 🚀 **Async Support**: Built with modern async/await patterns
13- 🛡️ **Type Safety**: Full type hints with Pydantic models
14
15## Quick Start
16
17### Installation
18
19```bash
20# Basic installation
21pip install -e .
22
23# With API server support
24pip install -e ".[api]"
25
26# With development tools
27pip install -e ".[dev]"
28```
29
30### CLI Usage
31
32```bash
33# Import from ICS URL
34atproto-calendar import --provider ics --source "https://calendar.example.com/events.ics"
35
36# Import from Google Calendar (requires OAuth setup)
37atproto-calendar import --provider google --credentials-file google_creds.json
38
39# Import and publish to AT Protocol
40atproto-calendar import \
41 --provider ics \
42 --source "events.ics" \
43 --publish \
44 --handle "user.bsky.social" \
45 --password "app-password"
46```
47
48### API Server
49
50```bash
51# Start the API server
52python -m atproto_calendar.api.server
53
54# Make import request
55curl -X POST "http://localhost:8000/import" \
56 -H "Content-Type: application/json" \
57 -d '{
58 "provider": "ics",
59 "source": "https://calendar.example.com/events.ics"
60 }'
61```
62
63### Python API
64
65```python
66from atproto_calendar.import.ics import ICSImporter
67from atproto_calendar.transform.converter import EventConverter
68
69# Import events
70importer = ICSImporter("https://calendar.example.com/events.ics")
71external_events = await importer.import_events()
72
73# Convert to AT Protocol format
74at_events = [
75 EventConverter.convert_external_event(event)
76 for event in external_events
77]
78```
79
80## Supported Calendar Providers
81
82| Provider | Authentication | Status |
83|----------|---------------|---------|
84| ICS Files/URLs | None | ✅ Ready |
85| Google Calendar | OAuth2 | 🚧 In Progress |
86| Microsoft Outlook | OAuth2 | 🚧 In Progress |
87| Apple Calendar | CalDAV | 🚧 In Progress |
88
89## Configuration
90
91The application can be configured via environment variables or configuration files:
92
93```bash
94# AT Protocol settings
95ATPROTO_HANDLE=user.bsky.social
96ATPROTO_PASSWORD=app-password
97ATPROTO_PDS_URL=https://bsky.social
98
99# API server settings
100API_HOST=0.0.0.0
101API_PORT=8000
102DEBUG=false
103
104# Optional: Database settings
105REDIS_URL=redis://localhost:6379
106POSTGRES_URL=postgresql://user:pass@localhost/db
107```
108
109## Development
110
111### Setup Development Environment
112
113```bash
114# Clone the repository
115git clone <repository-url>
116cd atproto-calendar-import/PYTHON
117
118# Install in development mode
119pip install -e ".[dev]"
120
121# Install pre-commit hooks
122pre-commit install
123```
124
125### Running Tests
126
127```bash
128# Run all tests
129pytest
130
131# Run with coverage
132pytest --cov=src --cov-report=html
133
134# Run specific test file
135pytest tests/test_import/test_ics.py
136```
137
138### Code Quality
139
140```bash
141# Format code
142black . && isort .
143
144# Lint code
145flake8 . && mypy .
146
147# Run pre-commit checks
148pre-commit run --all-files
149```
150
151## Architecture
152
153The project follows a modular architecture:
154
155- **Import Layer**: Handles importing from various calendar providers
156- **Transform Layer**: Converts external events to AT Protocol format
157- **AT Protocol Layer**: Manages authentication and publishing to AT Protocol
158- **API Layer**: Provides REST endpoints for integration
159- **CLI Layer**: Command-line interface for batch operations
160
161## Contributing
162
1631. Fork the repository
1642. Create a feature branch (`git checkout -b feature/amazing-feature`)
1653. Commit your changes (`git commit -m 'Add amazing feature'`)
1664. Push to the branch (`git push origin feature/amazing-feature`)
1675. Open a Pull Request
168
169## License
170
171This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
172
173## Support
174
175- 📖 [Documentation](https://atproto-calendar-import.readthedocs.io)
176- 🐛 [Issue Tracker](https://github.com/example/atproto-calendar-import/issues)
177- 💬 [Discussions](https://github.com/example/atproto-calendar-import/discussions)