{"id":20597429,"url":"https://github.com/loveduckie/google-calendar-tool","last_synced_at":"2026-04-29T23:33:12.942Z","repository":{"id":260591799,"uuid":"868617137","full_name":"LoveDuckie/google-calendar-tool","owner":"LoveDuckie","description":"A simple tool for listing your availability during the day. Sourced from your own Google Calendar.","archived":false,"fork":false,"pushed_at":"2024-12-03T11:49:05.000Z","size":407,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-06T15:21:18.788Z","etag":null,"topics":["gcal","google","google-calendar","google-calendar-api","python","python3"],"latest_commit_sha":null,"homepage":"https://lucshelton.codes","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LoveDuckie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-06T20:40:20.000Z","updated_at":"2024-12-08T01:02:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"a725eac6-56c4-4d5f-b681-1bfd40bfcbb1","html_url":"https://github.com/LoveDuckie/google-calendar-tool","commit_stats":null,"previous_names":["loveduckie/google-calendar-tool"],"tags_count":0,"template":false,"template_full_name":"LoveDuckie/python-tool-template","purl":"pkg:github/LoveDuckie/google-calendar-tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoveDuckie%2Fgoogle-calendar-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoveDuckie%2Fgoogle-calendar-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoveDuckie%2Fgoogle-calendar-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoveDuckie%2Fgoogle-calendar-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LoveDuckie","download_url":"https://codeload.github.com/LoveDuckie/google-calendar-tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LoveDuckie%2Fgoogle-calendar-tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32448400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"ssl_error","status_checked_at":"2026-04-29T22:10:49.234Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gcal","google","google-calendar","google-calendar-api","python","python3"],"created_at":"2024-11-16T08:22:25.807Z","updated_at":"2026-04-29T23:33:12.925Z","avatar_url":"https://github.com/LoveDuckie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Google Calendar Tool\n\n\u003c/div\u003e\n\nThis tool allows you to generate a list of available time slots in your Google Calendar for the upcoming week. It integrates with the Google Calendar API to fetch events and compute free slots within working hours. The tool uses `rich_click` to provide a command-line interface.\n\nIt might do other things in the future but it was originally developed to do one thing and to do it well.\n\n---\n\n:warning: **NOTE:** :warning:  This was created in a couple of hours so please moderate your expectations around code-quality and any potential issues that you might find.\n\n## Why?\n\nThis tool was built to answer the age-old question often asked by recruiters and employers when scheduling job interviews.\n\n\u003e \"What's your availability like?\"\n\nInstead of laboriously formatting and reading my calendar for the following week, I thought it would instead be more appropriate to use a tool that would automate it for me.\n\n### Why not use a calendar scheduling tool, like Calendly?\n\nSurprisingly, some recruiters or employers don't like to use them or they would rather use their own in-house solution instead. This tool is meant to specifically solve instances where this problem might occur.\n\nUsing this tool offers convenience and saves time for the prospective employer and the candidate (presumably you, the person reading this).\n\n## Demonstration\n\n\u003cdiv align=\"center\"\u003e\n\n![google-calendar-tool demonstration](\u003cassets/gcal-tool-generate.gif\u003e)\n\n\u003c/div\u003e\n\n## Requirements\n\n1. An account with Google Cloud Platform.\n2. OAuth2 access to the account with the calendar.\n\n## Installation\n\n1. Clone the repository:\n\n   ```sh\n   #!/usr/bin/env bash\n   git clone https://github.com/LoveDuckie/google-calendar-tool\n   cd google-calendar-tool\n   ```\n\n2. Install the package:\n\n   ```sh\n   #!/usr/bin/env bash\n   pip install .\n   ```\n\n3. Ensure you have the required Google Calendar API credentials in a JSON file. You can create these by following the [Google Calendar API quickstart guide](https://developers.google.com/calendar/quickstart/python).\n\n## Usage\n\n### Generating Availability\n\nThe tool provides a command-line command to generate a list of availability slots from your Google Calendar. \n\n```sh\n#!/usr/bin/env bash\ngcal-tool generate [OPTIONS]\n```\n\n### Options\n\n- `--credentials-filepath` (default: `./credentials.json`):  \n  The path to where the Google API credentials JSON file is stored. You can generate this file in the Google Cloud Console.\n\n- `--output-type` (default: `default`):  \n  Specifies the output format of the generated availability. The allowed values are:\n  - `default`: Prints the availability in a human-readable format.\n  - `json`: Outputs the availability as a JSON object.\n\n- `--buffer-minutes` (default: 30):  \n  The buffer time in minutes to leave before and after each event to allow for preparation and transition.\n\n### Example\n\nTo generate your availability using a custom credentials file and in JSON format:\n\n```sh\n#!/usr/bin/env bash\ngcal-tool generate --credentials-filepath \"/path/to/credentials.json\" --output-type \"json\"\n```\n\n## How It Works\n\nThe `generate` command uses the Google Calendar API to retrieve events from the primary calendar of the authenticated user for the next 7 days. It then calculates free time slots in the calendar, considering a buffer of 30 minutes before and after each event.\n\nThe tool checks each working day (Monday to Friday) for availability, and prints out the available time slots in the following format:\n\n```\nAvailability for Monday, October 7th:\n - Available: 09:00 to 11:30\n - Available: 14:00 to 17:00\n```\n\n### Key Functions\n\n- **`authenticate_google_calendar(credentials_filepath: str)`**  \n  Authenticates and returns a Google Calendar API service instance using the specified credentials file.\n\n- **`get_free_slots(service, start_date, end_date)`**  \n  Fetches events between `start_date` and `end_date` and calculates the available time slots for each working day.\n\n## Dependencies\n\n- Python 3.6+\n- `google-auth`\n- `google-auth-oauthlib`\n- `google-api-python-client`\n- `rich-click`\n\nYou can install these dependencies using:\n\n```sh\n#!/usr/bin/env bash\npip install -r requirements.txt\n```\n\n## Error Handling\n\nThe tool will raise errors for the following cases:\n- If the `context` object or any required arguments are invalid.\n- If the credentials file path is not defined or the file does not exist.\n\n## Troubleshooting\n\nEnsure you have the appropriate permissions for the Google Calendar API and that the credentials file (`credentials.json`) is valid and accessible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floveduckie%2Fgoogle-calendar-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floveduckie%2Fgoogle-calendar-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floveduckie%2Fgoogle-calendar-tool/lists"}