diff --git a/README.md b/README.md index 8695e16..c1afd44 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,36 @@ # CalDAV2GoogleCalendar -This project synchronizes events from a CalDAV calendar to a specific Google Calendar. +

+ caldav2google +

+ +A Python utility to synchronize events from a CalDAV calendar to Google Calendar, maintaining a local state to track changes. ## Features -- Connects to a CalDAV server to fetch calendar events. -- Compares fetched events with locally stored events to identify new, updated, and deleted events. -- Synchronizes changes to a specified Google Calendar: - - Adds new events. - - Updates modified events. - - Deletes removed events. +- 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 -Ensure you have Python 3.7 or higher installed. It is recommended to use a virtual environment. +- Python 3.10 or higher +- Poetry for dependency management -### 2. CalDAV Server -A CalDAV server should be set up and accessible. Ensure you have the following: +### 2. CalDAV Server Details +You'll need: - CalDAV server URL - Username - Password +- Calendar name to synchronize -### 3. Google Calendar API Credentials +### 3. Google Calendar Setup To interact with the Google Calendar API, follow these steps: @@ -38,85 +47,144 @@ To interact with the Google Calendar API, follow these steps: ## Installation -1. Clone this repository: +1. Clone the repository: ```bash - git clone https://github.com/your-username/caldav2googlecalendar.git - cd caldav2googlecalendar + git clone https://gitlab.com/rogs/caldav2google.git + cd caldav2google ``` -2. Install dependencies using Poetry: +2. Install dependencies: ```bash poetry install ``` -3. Activate the virtual environment: +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 ``` -## Configuration - -1. Update the `CALDAV_URL`, `USERNAME`, and `PASSWORD` variables in the script to match your CalDAV server credentials. -2. Ensure the `LOCAL_SYNC_FILE` points to the file where locally synced events will be stored. - -## Usage - -1. Run the script: +2. Run synchronization: ```bash - python sync_caldav_to_google.py + python main.py ``` -2. On the first run, a browser window will open for Google authentication. Grant the necessary permissions to access your Google Calendar. -3. The script will: - - Fetch events from the CalDAV calendar. - - Compare with the locally stored events. - - Add, update, or delete events in the specified Google Calendar. +On first run: +- Browser opens for Google OAuth authentication +- Grant requested calendar permissions +- Token is saved locally for future use ## Project Structure ``` -caldav2googlecalendar/ -├── sync_caldav_to_google.py # Main script -├── pyproject.toml # Project metadata and dependencies -├── README.md # Project documentation -├── credentials.json # Google API credentials (not included in the repository) -├── calendar_sync.json # Locally synced events -└── .venv/ # Virtual environment (not included in the repository) +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 ``` -## Logging +## Configuration Files -- The script provides detailed logs during execution: - - Number of new, updated, and deleted events. - - Any errors encountered during synchronization. +### 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 -### Common Issues +### Authentication Issues -#### 1. `HttpError 400` when adding events -- Ensure the event data is correctly formatted (ISO 8601 format for `start` and `end` dates). -- Check if required fields (`summary`, `start`, `end`) are missing. +#### Google Calendar +- Error: `Invalid client credentials` + - Verify `credentials.json` is correctly downloaded and placed + - Ensure OAuth consent screen is configured -#### 2. Authentication Issues -- Ensure the `credentials.json` file is in the correct location. -- Delete the `token.pickle` file and re-authenticate by running the script again. +- Error: `Token has been expired or revoked` + - Delete `token.pickle` + - Re-run script to authenticate -#### 3. CalDAV Connection Issues -- Verify the `CALDAV_URL`, `USERNAME`, and `PASSWORD` values. -- Test connectivity to the CalDAV server using another CalDAV client (e.g., Thunderbird). +#### CalDAV +- Error: `Could not connect to server` + - Check URL format and accessibility + - Verify network connectivity + - Confirm server SSL certificate if using HTTPS -## Contributions +### Synchronization Issues -Contributions are welcome! Please fork the repository, make your changes, and submit a pull request. +- 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 -This project is licensed under the GNU General Public License v3.0 or later. See the LICENSE file for more details. - -## Acknowledgments - -- [Radicale](https://radicale.org/) for providing a lightweight CalDAV server. -- [Google Calendar API](https://developers.google.com/calendar) for seamless calendar integration. +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 diff --git a/logo.jpg b/logo.jpg new file mode 100644 index 0000000..c701a6a Binary files /dev/null and b/logo.jpg differ