rogs/caldav2google
rogs/caldav2google
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
caldav2google/README.md
Roger Gonzalez 7dfcb2ba5c
Modified README
2024-11-24 21:06:57 -03:00

4.8 KiB
Raw Blame History

CalDAV2GoogleCalendar

caldav2google

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.
  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:

    git clone https://gitlab.com/rogs/caldav2google.git
cd caldav2google

  2. Install dependencies:

    poetry install

  3. Create .env file:

    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:

    poetry shell

  2. Run synchronization:

    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

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

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: