191 lines
4.8 KiB
Markdown
191 lines
4.8 KiB
Markdown
# CalDAV2GoogleCalendar
|
|
|
|
<p align="center">
|
|
<img src="https://gitlab.com/uploads/-/system/project/avatar/64798757/logo.jpg" alt="caldav2google"/>
|
|
</p>
|
|
|
|
A Python utility to synchronize events from a CalDAV calendar to Google Calendar, maintaining a local state to track changes.
|
|
|
|
## Features
|
|
- One-way synchronization from CalDAV to Google Calendar
|
|
- Intelligent change detection:
|
|
- Adds new events
|
|
- Updates modified events
|
|
- Removes deleted events
|
|
- Local state management to track synchronized events
|
|
- Detailed logging of synchronization activities
|
|
- Rate limiting to prevent API throttling
|
|
- Error handling with failed events tracking
|
|
|
|
## Prerequisites
|
|
|
|
### 1. Python Environment
|
|
- Python 3.10 or higher
|
|
- Poetry for dependency management
|
|
|
|
### 2. CalDAV Server Details
|
|
You'll need:
|
|
- CalDAV server URL
|
|
- Username
|
|
- Password
|
|
- Calendar name to synchronize
|
|
|
|
### 3. Google Calendar Setup
|
|
|
|
To interact with the Google Calendar API, follow these steps:
|
|
|
|
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
|
|
2. Create a new project or select an existing one.
|
|
3. Enable the **Google Calendar API** for the project.
|
|
4. Create OAuth 2.0 credentials:
|
|
- Go to **APIs & Services > Credentials**.
|
|
- Click **Create Credentials** > **OAuth Client ID**.
|
|
- Configure the consent screen (if not already done).
|
|
- Select **Desktop App** as the application type.
|
|
- Download the `credentials.json` file.
|
|
5. Place the `credentials.json` file in the project directory.
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://gitlab.com/rogs/caldav2google.git
|
|
cd caldav2google
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
poetry install
|
|
```
|
|
|
|
3. Create `.env` file:
|
|
```env
|
|
CALDAV_URL=https://your-caldav-server.com
|
|
CALDAV_USERNAME=your_username
|
|
CALDAV_PASSWORD=your_password
|
|
CALDAV_CALENDAR_NAME=your_calendar_name
|
|
GOOGLE_CALENDAR_NAME=target_google_calendar_name
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Activate virtual environment:
|
|
```bash
|
|
poetry shell
|
|
```
|
|
|
|
2. Run synchronization:
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
On first run:
|
|
- Browser opens for Google OAuth authentication
|
|
- Grant requested calendar permissions
|
|
- Token is saved locally for future use
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── auth_google.py # Google Calendar authentication
|
|
├── caldav_client.py # CalDAV server interactions
|
|
├── main.py # Main synchronization script
|
|
├── sync_logic.py # Core synchronization logic
|
|
pyproject.toml # Project configuration
|
|
env.example # Environment variables example file
|
|
.env # Environment variables
|
|
README.md # README instructions
|
|
credentials.json # Google OAuth credentials
|
|
token.pickle # Stored Google token
|
|
calendar_sync.json # Local sync state
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
### credentials.json
|
|
Downloaded from Google Cloud Console (required)
|
|
|
|
### .env
|
|
```env
|
|
CALDAV_URL=https://caldav.example.com
|
|
CALDAV_USERNAME=user
|
|
CALDAV_PASSWORD=pass
|
|
CALDAV_CALENDAR_NAME=My Calendar
|
|
GOOGLE_CALENDAR_NAME=CalDAV Events
|
|
```
|
|
|
|
### calendar_sync.json
|
|
Automatically maintained by the script to track synchronization state.
|
|
|
|
## Error Handling
|
|
|
|
The script provides robust error handling:
|
|
- Failed events are tracked and reported
|
|
- Rate limiting prevents API throttling
|
|
- Detailed error messages for troubleshooting
|
|
- Synchronization state preserved on failure
|
|
|
|
## Troubleshooting
|
|
|
|
### Authentication Issues
|
|
|
|
#### Google Calendar
|
|
- Error: `Invalid client credentials`
|
|
- Verify `credentials.json` is correctly downloaded and placed
|
|
- Ensure OAuth consent screen is configured
|
|
|
|
- Error: `Token has been expired or revoked`
|
|
- Delete `token.pickle`
|
|
- Re-run script to authenticate
|
|
|
|
#### CalDAV
|
|
- Error: `Could not connect to server`
|
|
- Check URL format and accessibility
|
|
- Verify network connectivity
|
|
- Confirm server SSL certificate if using HTTPS
|
|
|
|
### Synchronization Issues
|
|
|
|
- Error: `Calendar not found`
|
|
- Verify calendar names in `.env`
|
|
- Check calendar visibility/permissions
|
|
|
|
- Error: `Failed to add/update events`
|
|
- Check event data formatting
|
|
- Verify calendar write permissions
|
|
- Review API quotas and limits
|
|
|
|
## Development
|
|
|
|
### Pre-commit Hooks
|
|
```bash
|
|
poetry run pre-commit install
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create feature branch
|
|
3. Commit changes
|
|
4. Push to branch
|
|
5. Submit pull request
|
|
|
|
Please:
|
|
- Follow existing code style
|
|
- Add tests for new features
|
|
- Update documentation
|
|
- Run pre-commit hooks
|
|
|
|
## License
|
|
|
|
GNU General Public License v3.0 or later
|
|
|
|
## Credits
|
|
|
|
Built with:
|
|
- [caldav](https://pypi.org/project/caldav/) - CalDAV client library
|
|
- [google-api-python-client](https://github.com/googleapis/google-api-python-client) - Google Calendar API
|
|
- [python-dotenv](https://pypi.org/project/python-dotenv/) - Environment management
|
|
- [Poetry](https://python-poetry.org/) - Dependency management
|