### Install gcsa from source

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/getting_started.md

Install the gcsa library by cloning the repository and running the setup script. This method is useful for development or when using the latest unreleased code.

```bash
git clone git@github.com:kuzmoyev/google-calendar-simple-api.git
cd google-calendar-simple-api
python setup.py install
```

--------------------------------

### Install GCSA

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Install the gcsa library using pip or uv.

```bash
pip install gcsa
```

```bash
uv add gcsa
```

--------------------------------

### Example User Settings Output

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/settings.md

This is an example of the output format when printing the `Settings` object, showing various user preferences.

```text
User settings:
auto_add_hangouts=true
date_field_order=DMY
default_event_length=60
format24_hour_time=false
hide_invitations=false
hide_weekends=true
locale=en
remind_on_responded_events_only=false
show_declined_events=true
timezone=Europe/Prague
use_keyboard_shortcuts=true
week_start=1
```

--------------------------------

### Install Dependencies

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/CONTRIBUTING.md

Install project dependencies using pip. Use the dev extra for running tests and compiling documentation.

```bash
pip install -e .

```

```bash
pip install -e .[dev]
```

--------------------------------

### Install gcsa using pip

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/README.rst

Use this command to install the gcsa library using pip.

```bash
pip install gcsa
```

--------------------------------

### Install gcsa using uv

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/README.rst

Use this command to add the gcsa library to your project with the uv package manager.

```bash
uv add gcsa
```

--------------------------------

### List and Set Event Colors

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Provides examples for listing available event colors and setting a specific color for an event, both during creation and for an existing event.

```python
from gcsa.event import Event
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

# List available event colors
for color_id, color in gc.list_event_colors().items():
    print(color_id, color['background'], color['foreground'])
# Available IDs: '1'=Lavender, '2'=Sage, '3'=Grape, '4'=Flamingo,
#                '5'=Banana, '6'=Tangerine, '7'=Peacock, '8'=Graphite,
#                '9'=Blueberry, '10'=Basil, '11'=Tomato

from datetime import datetime
event = Event('Important Deadline', start=datetime(2024, 5, 1, 10, 0), color_id='11')  # Tomato
event = gc.add_event(event)

# Update color of existing event
event.color_id = '4'  # Flamingo
gc.update_event(event)
```

--------------------------------

### Create and List Google Calendar Events

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/getting_started.md

This example demonstrates how to create a recurring event with specific exclusions and then list all events for a year. It utilizes the `beautiful_date` library for date manipulation. Ensure `credentials.json` is in `~/.credentials/` or specified otherwise, and that the Google Calendar API is enabled in your GCP project.

```python
from gcsa.event import Event
from gcsa.google_calendar import GoogleCalendar
from gcsa.recurrence import Recurrence, DAILY, SU, SA

from beautiful_date import Jan, Apr


calendar = GoogleCalendar('your_email@gmail.com')
event = Event(
    'Breakfast',
    start=(1 / Jan / 2019)[9:00],
    recurrence=[
        Recurrence.rule(freq=DAILY),
        Recurrence.exclude_rule(by_week_day=[SU, SA]),
        Recurrence.exclude_times([
            (19 / Apr / 2019)[9:00],
            (22 / Apr / 2019)[9:00]
        ])
    ],
    minutes_before_email_reminder=50
)

calendar.add_event(event)

for event in calendar:
    print(event)
```

--------------------------------

### Create, retrieve, update, and delete calendars

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Provides a comprehensive guide to managing calendars, including creating new ones, fetching details, modifying them, and deleting them.

```APIDOC
## Create, retrieve, update, and delete calendars

### Description
This section details the lifecycle management of Google Calendars using the API, covering operations such as creating secondary calendars, retrieving calendar metadata, updating calendar properties, and deleting calendars.

### Methods
`gc.get_calendar()`
`gc.add_calendar(calendar)`
`gc.update_calendar(calendar)`
`gc.get_calendar_list(min_access_role)`
`gc.add_calendar_list_entry(list_entry)`
`gc.delete_calendar_list_entry(list_entry)`
`gc.delete_calendar(calendar)`
`gc.clear_calendar()`

### Parameters
- `calendar` (Calendar): A Calendar object with properties like `summary`, `description`, and `timezone`.
- `list_entry` (CalendarListEntry): An entry representing a calendar in the user's list, potentially with a `summary_override`.
- `min_access_role` (AccessRoles): Filters the calendar list by minimum access role.

### Request Example
```python
from gcsa.calendar import Calendar, CalendarListEntry, AccessRoles
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

# Get the default calendar's metadata
calendar = gc.get_calendar()
print(calendar.summary, calendar.timezone)

# Create a new secondary calendar
new_cal = Calendar(
    'Travel Plans',
    description='Events related to upcoming trips',
    timezone='America/New_York'
)
new_cal = gc.add_calendar(new_cal)
print(new_cal.calendar_id)

# Update calendar metadata
new_cal.summary = 'International Travel'
new_cal.description = 'All international trip events'
gc.update_calendar(new_cal)

# List all calendars in the user's calendar list
for entry in gc.get_calendar_list(min_access_role=AccessRoles.READER):
    print(entry.summary, entry.calendar_id)

# Add an existing calendar to the user's list with a custom display name
list_entry = CalendarListEntry(
    calendar_id=new_cal.calendar_id,
    summary_override='My Travel Calendar'
)
gc.add_calendar_list_entry(list_entry)

# Remove from list and delete the calendar
gc.delete_calendar_list_entry(list_entry)
gc.delete_calendar(new_cal)

# Clear all events from primary calendar (irreversible!)
gc.clear_calendar()
```
```

--------------------------------

### Get Free/Busy for Multiple Calendars and Groups

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/free_busy.md

Fetch free/busy data for a list of calendars and groups. The results are organized by calendar and group in the returned FreeBusy object.

```python
free_busy = gc.get_free_busy(
    [
        'primary',
        'secondary_calendar_id@gmail.com',
        'group_id'
    ]
)

print('Primary calendar:')
for start, end in free_busy.calendars['primary']:
    print(f'Busy from {start} to {end}')

print('Secondary calendar:')
for start, end in free_busy.calendars['secondary_calendar_id@gmail.com']:
    print(f'Busy from {start} to {end}')

print('Group info:')
for calendar in free_busy.groups['group_id']:
    print(f'{calendar}:')
    for start, end in free_busy.calendars[calendar]:
        print(f'Busy from {start} to {end}')
```

--------------------------------

### Get Calendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieves a calendar by its ID. If no ID is provided, it fetches the default calendar.

```APIDOC
## Get Calendar

### Description
Retrieves a calendar specified by its ID. If no calendar ID is provided, it defaults to the calendar set in the `GoogleCalendar` instance.

### Method
`get_calendar(calendar_id: str = None)`

### Parameters
#### Path Parameters
- **calendar_id** (string) - Optional - The ID of the calendar to retrieve. If omitted, the default calendar is used.

### Response
#### Success Response (200)
- **Calendar** (object) - An object representing the calendar with its metadata.
```

--------------------------------

### Retrieve Free/Busy Information

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/free_busy.md

This snippet demonstrates how to get the free/busy information for the next two weeks for the primary calendar.

```APIDOC
## Retrieve Free/Busy Information

### Description
Retrieves the free/busy information for the primary calendar for the next two weeks.

### Method
`gc.get_free_busy()`

### Parameters
None

### Response
A `FreeBusy` object containing time slots.

### Request Example
```python
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()
free_busy = gc.get_free_busy()

for start, end in free_busy:
    print(f'Busy from {start} to {end}')
```
```

--------------------------------

### Add Single Email Reminder to Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/reminders.md

Create an event with a single email reminder set for 30 minutes before the start time. Requires importing `EmailReminder` and `Event`.

```python
from gcsa.reminders import EmailReminder, PopupReminder

event = Event('Meeting',
              start=(22/Apr/2019)[12:00],
              reminders=EmailReminder(minutes_before_start=30))
```

--------------------------------

### Create an All-Day Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Create an all-day event by using date objects for the start and end times. This is suitable for events that span an entire day or multiple consecutive days.

```python
from beautiful_date import Aug, days
from gcsa.event import Event

start = 1/Aug/2021
end = start + 7 * days
event = Event('Vacation',
              start=start,
              end=end)
```

--------------------------------

### Get Free/Busy for Primary Calendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/free_busy.md

Retrieve free/busy information for the next two weeks for the primary calendar. The result can be iterated directly if only one calendar is requested.

```python
free_busy = gc.get_free_busy()

for start, end in free_busy:
    print(f'Busy from {start} to {end}')
```

--------------------------------

### Create recurring event with exclusion rules

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/recurrence.md

Combine multiple recurrence rules, including exclusions, for complex event scheduling. This example excludes weekends from a daily recurring event.

```python
Event('Breakfast',
      (1/Jan/2019)[9:00],
      (1/Jan/2020)[9:00],
      recurrence=[
         Recurrence.rule(freq=DAILY),
         Recurrence.exclude_rule(by_week_day=[SU, SA])
      ])
```

--------------------------------

### Add Daily Push-Up Reminders to Google Calendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/why_gcsa.md

This Python script uses GCSA to create daily calendar events for a push-up challenge. It calculates the start date and iterates through a list of push-up counts to add corresponding events, setting a reminder for each.

```python
from gcsa.google_calendar import GoogleCalendar
from gcsa.event import Event
from beautiful_date import D, drange, days, MO

gc = GoogleCalendar()

PUSH_UPS_COUNT = [
    5, 5, 0, 5, 10, 0, 10,
    0, 12, 12, 0, 15, 15, 0,
    20, 24, 0, 25, 30, 0, 32,
    35, 35, 0, 38, 40, 0, 42,
    45, 50
]

# starting next Monday (of course)
# +1 days for the case that today is Monday
start = D.today()[9:00] + 1 * days + MO
end = start + len(PUSH_UPS_COUNT) * days

for day, push_ups in zip(drange(start, end), PUSH_UPS_COUNT):
    e = Event(
        f'{push_ups} Push-Ups' if push_ups else 'Rest',
        start=day,
        minutes_before_popup_reminder=5
    )
    gc.add_event(e)
```

--------------------------------

### Create Event with Google Calendar Simple API

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/README.rst

Create an Event object with title, start time, and location, then add it to your Google Calendar. The `minutes_before_popup_reminder` parameter sets a reminder.

```python
from gcsa.event import Event

event = Event(
    'The Glass Menagerie',
    start=datetime(2020, 7, 10, 19, 0),
    location='Záhřebská 468/21',
    minutes_before_popup_reminder=15
)
calendar.add_event(event)
```

--------------------------------

### List Events for One Year

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Iterate through events starting from the current date for a duration of one year. This provides a simple way to view upcoming events.

```python
for event in gc:
    print(event)
```

--------------------------------

### List Events within a Time Range

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Specify a start and end time to retrieve events within a specific period. Events can be ordered by 'updated' or 'startTime'. Time range can also be specified using slicing syntax.

```python
events = gc.get_events(time_min, time_max, order_by='updated')
```

```python
events = gc[time_min:time_max:'updated']
```

--------------------------------

### Daily Recurrence Every 20 Minutes Between 9 AM and 4:40 PM

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/recurrence.md

Sets a daily recurrence with events every 20 minutes, starting from 9:00 AM up to 4:40 PM. It uses `by_hour` and `by_minute` to define the time intervals.

```python
Recurrence.rule(freq=DAILY,
                by_hour=list(range(9, 17)),
                by_minute=[0, 20, 40])
```

--------------------------------

### Create a Time-Based Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Create a new event with a specified start and end time using the Event class. The beautiful_date library can be used for convenient date and time manipulation.

```python
from beautiful_date import Apr, hours
from gcsa.event import Event

start = (22/Apr/2019)[12:00]
end = start + 2 * hours
event = Event('Meeting',
              start=start,
              end=end)
```

--------------------------------

### Create Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Creates a new event in the calendar. Events can be time-based or all-day events. Supports custom start and end times using datetime objects.

```APIDOC
## Create event

```python
from beautiful_date import Apr, hours
from gcsa.event import Event

start = (22/Apr/2019)[12:00]
end = start + 2 * hours
event = Event('Meeting',
              start=start,
              end=end)
```

or to create an **all-day** event, use a date object:

```python
from beautiful_date import Aug, days
from gcsa.event import Event

start = 1/Aug/2021
end = start + 7 * days
event = Event('Vacation',
              start=start,
              end=end)
```

For `date`/`datetime` objects you can use Pythons [datetime](https://docs.python.org/3/library/datetime.html) module or as in the example [beautiful_date](https://github.com/kuzmoyev/beautiful-date) library (*because it’s beautiful… just like you*).

Now **add** your event to the calendar:

```python
event = gc.add_event(event)
```
```

--------------------------------

### Create Recurring Event with Google Calendar Simple API

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/README.rst

Define a recurring event using the `Recurrence` class, specifying the frequency (e.g., DAILY), and add it to the calendar. The `start` parameter should be a date object.

```python
from gcsa.recurrence import Recurrence, DAILY

event = Event(
    'Breakfast',
    start=date(2020, 7, 16),
    recurrence=Recurrence.rule(freq=DAILY)
)
calendar.add_event(event)
```

--------------------------------

### Get Filtered Calendar List

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieve the user's calendar list with options to include deleted and hidden entries, and to filter by minimum access role. Requires importing `AccessRoles`.

```python
from gcsa.calendar import AccessRoles

gc.get_calendar_list(
    min_access_role=AccessRoles.READER,
    show_deleted=True,
    show_hidden=True
)
```

--------------------------------

### Add Existing Conference Solution with Multiple Entry Points

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/conference.md

Provide a list of EntryPoints to ConferenceSolution to include multiple ways to join a conference, such as video and phone. This allows users to choose their preferred method.

```python
event = Event(
    'Event with conference',
    start=(22 / Nov / 2020)[15:00],
    conference_solution=ConferenceSolution(
        entry_points=[
            EntryPoint(
                EntryPoint.VIDEO,
                uri='https://meet.google.com/aaa-bbbb-ccc'
            ),
            EntryPoint(
                EntryPoint.PHONE,
                uri='tel:+12345678900'
            )
        ],
        solution_type=SolutionType.HANGOUTS_MEET,
    )
)
```

--------------------------------

### Get Calendar List Entry

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieves a specific calendar list entry by its ID.

```APIDOC
## Get Calendar List Entry

### Description
Retrieves a specific entry from the user's calendar list, identified by its calendar ID. If no ID is provided, it defaults to the calendar set in the `GoogleCalendar` instance.

### Method
`get_calendar_list_entry(calendar_id: str = None)`

### Parameters
#### Path Parameters
- **calendar_id** (string) - Optional - The ID of the calendar list entry to retrieve. If omitted, the default calendar list entry is used.

### Response
#### Success Response (200)
- **CalendarListEntry** (object) - An object representing the calendar list entry.
```

--------------------------------

### Get Default Calendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieve metadata for the calendar that is set as default in your GoogleCalendar instance.

```python
calendar = gc.get_calendar()
```

--------------------------------

### Authenticate with Credentials File

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Authenticate using a credentials file. The library defaults to '~/.credentials/credentials.json' and saves the token to '~/.credentials/token.pickle'. Custom paths can be specified.

```python
from gcsa.google_calendar import GoogleCalendar

# Uses ~/.credentials/credentials.json; saves token to ~/.credentials/token.pickle
gc = GoogleCalendar('your_email@gmail.com')
```

```python
from gcsa.google_calendar import GoogleCalendar

# Custom credential and token paths
gc = GoogleCalendar(
    credentials_path='secrets/credentials.json',
    token_path='secrets/user1_token.pickle',
    save_token=True,
    read_only=False
)
```

--------------------------------

### Get Event by ID

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Retrieves a specific event from the calendar using its unique event ID.

```APIDOC
## Get event by id

```python
event = gc.get_event('<event_id>')
```
```

--------------------------------

### Get Single Event by ID

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Retrieve a specific event from the calendar using its unique event ID.

```python
event = gc.get_event('<event_id>')
print(event.summary, event.start, event.end)
```

--------------------------------

### Initialize GoogleCalendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/free_busy.md

Create a GoogleCalendar instance to interact with the Google Calendar API. Ensure you have your credentials set up.

```python
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()
```

--------------------------------

### Initialize GoogleCalendar with custom credentials path

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/authentication.md

Specify the exact path to your credentials.json file if it's not in the default location. The token.pickle will be managed in the same directory.

```python
gc = GoogleCalendar(credentials_path='path/to/credentials.json')
```

```python
gc = GoogleCalendar(credentials_path='path/to/client_secret_273833015691-qwerty.apps.googleusercontent.com.json')
```

--------------------------------

### Get ACL Rule by ID

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/acl.md

Retrieves a specific access control rule using its unique ID.

```APIDOC
## Get rule by id

### Description
Retrieves a single access control rule by its unique identifier.

### Method
`gc.get_acl_rule(rule_id)`

### Parameters
#### Query Parameters
- **rule_id** (string) - Required - The unique identifier of the ACL rule to retrieve.

### Response
- An `AccessControlRule` object representing the requested rule.

### Request Example
```python
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()

rule = gc.get_acl_rule(rule_id='<acl_rule_id>')
print(rule)
```

### Response Example
```
AccessControlRule(role=<ACLRole.READER: 'reader'>, scope_type=<ACLScopeType.USER: 'user'>, scope_value='example@example.com', id='<acl_rule_id>')
```
```

--------------------------------

### Create, Retrieve, Update, and Delete Calendars

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Demonstrates the full lifecycle of managing calendars, including creating new secondary calendars, updating their metadata, listing calendars, adding/removing them from the user's list, and finally deleting them. Also includes clearing all events from the primary calendar.

```python
from gcsa.calendar import Calendar, CalendarListEntry, AccessRoles
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

# Get the default calendar's metadata
calendar = gc.get_calendar()
print(calendar.summary, calendar.timezone)

# Create a new secondary calendar
new_cal = Calendar(
    'Travel Plans',
    description='Events related to upcoming trips',
    timezone='America/New_York'
)
new_cal = gc.add_calendar(new_cal)
print(new_cal.calendar_id)

# Update calendar metadata
new_cal.summary = 'International Travel'
new_cal.description = 'All international trip events'
gc.update_calendar(new_cal)

# List all calendars in the user's calendar list
for entry in gc.get_calendar_list(min_access_role=AccessRoles.READER):
    print(entry.summary, entry.calendar_id)

# Add an existing calendar to the user's list with a custom display name
list_entry = CalendarListEntry(
    calendar_id=new_cal.calendar_id,
    summary_override='My Travel Calendar'
)
gc.add_calendar_list_entry(list_entry)

# Remove from list and delete the calendar
gc.delete_calendar_list_entry(list_entry)
gc.delete_calendar(new_cal)

# Clear all events from primary calendar (irreversible!)
gc.clear_calendar()
```

--------------------------------

### Initialize GoogleCalendar with default credentials

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/authentication.md

Use this when your credentials.json file is in the default directory (~/.credentials). The token.pickle will be read from or saved to this directory.

```python
gc = GoogleCalendar()
```

--------------------------------

### Get Calendar List Entry

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/colors.md

Retrieve a specific calendar list entry to modify its properties. Requires the calendar ID.

```python
calendar_list_entry = gc.get_calendar_list_entry('<calendar_id>')
```

--------------------------------

### Initialize GoogleCalendar with custom token path

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/authentication.md

Define a specific path for the token.pickle file, separate from the credentials file. This is useful for managing multiple accounts or custom storage.

```python
gc = GoogleCalendar(credentials_path='path/to/credentials.json',
                    token_path='another/path/user1_token.pickle')
```

--------------------------------

### Get Default Calendar List Entry

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieve the calendar list entry for the default calendar specified in the GoogleCalendar instance.

```python
gc.get_calendar_list_entry()
```

--------------------------------

### Attach an Existing Conference to an Event

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Shows how to attach an existing conference solution, like a Google Meet link, to a new event.

```python
from datetime import datetime
from gcsa.event import Event
from gcsa.conference import ConferenceSolution, EntryPoint, SolutionType
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

event = Event(
    'Remote Standup',
    start=datetime(2024, 4, 22, 9, 0),
    conference_solution=ConferenceSolution(
        entry_points=[
            EntryPoint(EntryPoint.VIDEO, uri='https://meet.google.com/aaa-bbbb-ccc'),
            EntryPoint(EntryPoint.PHONE, uri='tel:+12345678900')
        ],
        solution_type=SolutionType.HANGOUTS_MEET
    )
)
gc.add_event(event)
```

--------------------------------

### Get Free/Busy for Specific Calendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/free_busy.md

Request free/busy information for a specific calendar using its ID. The result can be iterated directly.

```python
free_busy = gc.get_free_busy('secondary_calendar_id@gmail.com')

for start, end in free_busy:
    print(f'Busy from {start} to {end}')
```

--------------------------------

### Create Attendee Object and Add to Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/attendees.md

Demonstrates creating an Attendee object with display name and additional guests, then passing it to the Event constructor. Requires importing the Attendee class.

```python
from gcsa.attendee import Attendee

attendee = Attendee(
    'attendee@gmail.com',
    display_name='Friend',
    additional_guests=3
)

event = Event('Meeting',
              start=(17/Jul/2020)[12:00],
              attendees=attendee)
```

--------------------------------

### Get Calendar List

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieves the user's calendar list, optionally including deleted/hidden entries and filtering by access role.

```APIDOC
## Get User's Calendar List

### Description
Retrieves the collection of calendars in the user's calendar list. Supports filtering by minimum access role and showing deleted or hidden entries.

### Method
`get_calendar_list(min_access_role: AccessRoles = None, show_deleted: bool = False, show_hidden: bool = False)`

### Parameters
#### Query Parameters
- **min_access_role** (AccessRoles) - Optional - Filters the list to include only calendars with at least this access role.
- **show_deleted** (boolean) - Optional - Whether to include deleted calendar entries.
- **show_hidden** (boolean) - Optional - Whether to include hidden calendar entries.

### Response
#### Success Response (200)
- **List[CalendarListEntry]** - A list of `CalendarListEntry` objects representing the calendars in the user's list.
```

--------------------------------

### Get Event by ID

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Retrieve a specific event using its unique event ID. This is useful for fetching details of a known event.

```python
event = gc.get_event('<event_id>')
```

--------------------------------

### List and Set Calendar List Entry Colors

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Shows how to list available calendar colors and apply a color to a calendar list entry using either a color ID or custom hex values for background and foreground.

```python
# List available calendar colors (24 options)
for color_id, color in gc.list_calendar_colors().items():
    print(color_id, color['background'])

# Apply color to a calendar list entry by color ID or hex values
cal_entry = gc.get_calendar_list_entry('<calendar_id>')
cal_entry.color_id = '16'          # Blueberry
# or use custom hex values:
cal_entry.background_color = '#626364'
cal_entry.foreground_color = '#FFFFFF'
gc.update_calendar_list_entry(cal_entry)
```

--------------------------------

### Clone Repository

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/CONTRIBUTING.md

Clone the forked repository to your local machine.

```bash
git clone git@github.com:{your_username}/google-calendar-simple-api.git
```

--------------------------------

### List and set event colors

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Provides instructions on how to list available event colors and how to assign a specific color to an event.

```APIDOC
## List and set event colors

### Description
This section explains how to retrieve a list of available event colors and how to apply a color to a calendar event, either during creation or by updating an existing event.

### Methods
`gc.list_event_colors()`
`gc.add_event(event)`
`gc.update_event(event)`

### Parameters
- `event` (Event): An Event object.
- `color_id` (string): The ID of the color to apply to the event (e.g., '11' for Tomato).

### Request Example
```python
from gcsa.event import Event
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

# List available event colors
for color_id, color in gc.list_event_colors().items():
    print(color_id, color['background'], color['foreground'])
# Available IDs: '1'=Lavender, '2'=Sage, '3'=Grape, '4'=Flamingo,
#                '5'=Banana, '6'=Tangerine, '7'=Peacock, '8'=Graphite,
#                '9'=Blueberry, '10'=Basil, '11'=Tomato

from datetime import datetime
event = Event('Important Deadline', start=datetime(2024, 5, 1, 10, 0), color_id='11')  # Tomato
event = gc.add_event(event)

# Update color of existing event
event.color_id = '4'  # Flamingo
gc.update_event(event)
```
```

--------------------------------

### Get Calendar List Entry by ID

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieve a specific calendar list entry using its calendar ID. Replace 'calendar_id' with the actual ID.

```python
gc.get_calendar_list_entry('calendar_id')
```

--------------------------------

### Add Existing Conference Solution with Single Entry Point

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/conference.md

Use ConferenceSolution with a single EntryPoint to add an existing conference link to an event. Ensure SolutionType and EntryPoint details are correctly specified.

```python
from gcsa.conference import ConferenceSolution, EntryPoint, SolutionType

event = Event(
    'Meeting',
    start=(22 / Nov / 2020)[15:00],
    conference_solution=ConferenceSolution(
        entry_points=EntryPoint(
            EntryPoint.VIDEO,
            uri='https://meet.google.com/aaa-bbbb-ccc'
        ),
        solution_type=SolutionType.HANGOUTS_MEET,
    )
)
```

--------------------------------

### Get User's Calendar List

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieve a collection of all calendars currently in the user's calendar list. Each entry contains metadata about the calendar.

```python
for calendar in gc.get_calendar_list():
    print(calendar)
```

--------------------------------

### Get Calendar by ID

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Retrieve metadata for a specific calendar using its unique ID. Replace '<calendar_id>' with the actual ID of the calendar you want to access.

```python
calendar = gc.get_calendar('<calendar_id>')
```

--------------------------------

### Set Specific Time Reminders

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/reminders.md

Create reminders for specific times using `days_before` and `at` arguments. The API converts these to `minutes_before_start` for Google Calendar.

```python
from datetime import time

event = Event(
    'Meeting',
    start=(22/Apr/2019)[12:00],
    reminders=[
        # Day before the event at 13:30
        EmailReminder(days_before=1, at=time(13, 30)),
        # 2 days before the event at 19:15
        PopupReminder(days_before=2, at=time(19, 15))
    ]
)

event.add_popup_reminder(days_before=3, at=time(8, 30))
event.add_email_reminder(days_before=4, at=time(9, 0))
```

--------------------------------

### Add File Attachments to an Event

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Demonstrates how to add file attachments to a new event and how to add an attachment to an existing event.

```python
from datetime import datetime
from gcsa.event import Event
from gcsa.attachment import Attachment
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

attachment = Attachment(
    file_url='https://docs.google.com/document/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
    title='Meeting Notes',
    mime_type='application/vnd.google-apps.document'
)

event = Event(
    'Sprint Planning',
    start=datetime(2024, 4, 22, 9, 0),
    attachments=[attachment]
)
event = gc.add_event(event)

# Add attachment to existing event
event.add_attachment(
    'Q2 Report',
    file_url='https://drive.google.com/file/d/ABC123',
    mime_type='application/pdf'
)
event = gc.update_event(event)
```

--------------------------------

### Add Multiple Attendees to Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/attendees.md

Illustrates how to pass a list of attendees, including a mix of email strings and Attendee objects, to the Event constructor.

```python
event = Event('Meeting',
              start=(17/Jul/2020)[12:00],
              attendees=[
                  'attendee@gmail.com',
                  Attendee('attendee2@gmail.com', display_name='Friend')
              ])
```

--------------------------------

### List and set calendar list entry colors

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Details how to list available calendar colors and how to apply a specific color to a calendar list entry.

```APIDOC
## List and set calendar list entry colors

### Description
This section covers listing the available colors for calendar list entries and applying a color to a specific entry using either a color ID or custom hex values.

### Methods
`gc.list_calendar_colors()`
`gc.get_calendar_list_entry(calendar_id)`
`gc.update_calendar_list_entry(cal_entry)`

### Parameters
- `cal_entry` (CalendarListEntry): The calendar list entry object to update.
- `color_id` (string): The ID of the color to apply (e.g., '16' for Blueberry).
- `background_color` (string): Custom background color in hex format (e.g., '#626364').
- `foreground_color` (string): Custom foreground color in hex format (e.g., '#FFFFFF').

### Request Example
```python
# List available calendar colors (24 options)
for color_id, color in gc.list_calendar_colors().items():
    print(color_id, color['background'])

# Apply color to a calendar list entry by color ID or hex values
cal_entry = gc.get_calendar_list_entry('<calendar_id>')
cal_entry.color_id = '16'          # Blueberry
# or use custom hex values:
cal_entry.background_color = '#626364'
cal_entry.foreground_color = '#FFFFFF'
gc.update_calendar_list_entry(cal_entry)
```
```

--------------------------------

### Yearly Recurrence on Monday of Week 20

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/recurrence.md

Defines a yearly recurrence on a Monday of week number 20. It specifies the week start day, which defaults to Monday.

```python
Recurrence.rule(freq=YEARLY,
                by_week=20,
                week_start=MO)
```

--------------------------------

### Add Reminders Using Event Parameters

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/reminders.md

Set email and popup reminders directly as parameters when creating an event. This is a convenient shorthand for adding multiple reminders.

```python
event = Event('Meeting',
              start=(22/Apr/2019)[12:00],
              minutes_before_popup_reminder=15,
              minutes_before_email_reminder=30)
```

--------------------------------

### Run Tests with Tox

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/CONTRIBUTING.md

Execute various test suites using tox. These tests will also be run automatically on pull requests.

```bash
tox
```

```bash
tox -e pytest
```

```bash
tox -e flake8
```

```bash
tox -e sphinx
```

```bash
tox -e mypy
```

--------------------------------

### Get ACL Rule by ID

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/acl.md

Fetch a specific access control rule using its unique identifier. Replace '<acl_rule_id>' with the actual ID of the rule you want to retrieve.

```python
rule = gc.get_acl_rule(rule_id='<acl_rule_id>')
print(rule)
```

--------------------------------

### Attach an existing conference to an event

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Shows how to associate a pre-existing conference solution, like a Google Meet link or a phone number, with a calendar event.

```APIDOC
## Attach an existing conference to an event

### Description
This example demonstrates how to add a conference solution, such as a video conferencing link or a dial-in number, to a calendar event.

### Method
`gc.add_event(event)`

### Parameters
- `event` (Event): An Event object configured with a `ConferenceSolution`.
- `conference_solution` (ConferenceSolution): A ConferenceSolution object containing `entry_points` and `solution_type`.
  - `entry_points` (list): A list of EntryPoint objects, each specifying a `type` (e.g., EntryPoint.VIDEO, EntryPoint.PHONE) and a `uri`.
  - `solution_type` (SolutionType): The type of conference solution (e.g., SolutionType.HANGOUTS_MEET).

### Request Example
```python
from datetime import datetime
from gcsa.event import Event
from gcsa.conference import ConferenceSolution, EntryPoint, SolutionType
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

event = Event(
    'Remote Standup',
    start=datetime(2024, 4, 22, 9, 0),
    conference_solution=ConferenceSolution(
        entry_points=[
            EntryPoint(EntryPoint.VIDEO, uri='https://meet.google.com/aaa-bbbb-ccc'),
            EntryPoint(EntryPoint.PHONE, uri='tel:+12345678900')
        ],
        solution_type=SolutionType.HANGOUTS_MEET
    )
)
gc.add_event(event)
```
```

--------------------------------

### Get Events using Generator

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/events.md

Retrieve events using the get_events() method, which returns a generator. This is memory-efficient for large numbers of events. You can iterate directly or convert to a list.

```python
for event in gc.get_events():
    print(event)
```

```python
events = list(gc.get_events())
```

--------------------------------

### Import Recurrence class and day constants

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/recurrence.md

Import the necessary Recurrence class and constants for days of the week to define recurrence rules.

```python
from gcsa.recurrence import Recurrence

# days of the week
from gcsa.recurrence import SU, MO, TU, WE, TH, FR, SA
```

--------------------------------

### Authenticate with Pre-built Credentials Object

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Authenticate by passing a pre-built google.oauth2.credentials.Credentials object directly, bypassing file-based authentication.

```python
from google.oauth2.credentials import Credentials
from gcsa.google_calendar import GoogleCalendar

token = Credentials(
    token='<access_token>',
    refresh_token='<refresh_token>',
    client_id='<client_id>',
    client_secret='<client_secret>',
    scopes=['https://www.googleapis.com/auth/calendar'],
    token_uri='https://oauth2.googleapis.com/token'
)
gc = GoogleCalendar(credentials=token)
```

--------------------------------

### Get Free/Busy Ignoring Errors

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/free_busy.md

Retrieve free/busy information while ignoring any errors that occur for specific calendars or groups. Errors can be accessed via the `groups_errors` and `calendars_errors` fields.

```python
free_busy = gc.get_free_busy(
    resource_ids=[
        'primary',
        'secondary_calendar_id@gmail.com',
        'group_id'
    ],
    ignore_errors=True
)

print(free_busy.groups_errors)
print(free_busy.calendars_errors)
```

--------------------------------

### Request a New Google Meet Conference

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Demonstrates how to request a new Google Meet conference for an event. The status of the conference creation should be checked asynchronously.

```python
from datetime import datetime
from gcsa.event import Event
from gcsa.conference import ConferenceSolutionCreateRequest, SolutionType
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

event = gc.add_event(Event(
    'New Meeting',
    start=datetime(2024, 4, 22, 14, 0),
    conference_solution=ConferenceSolutionCreateRequest(
        solution_type=SolutionType.HANGOUTS_MEET
    )
))

# Conference creation is asynchronous; check status
if event.conference_solution.status == 'success':
    print('Meet link:', event.conference_solution.entry_points[0].uri)
elif event.conference_solution.status == 'pending':
    print('Conference request is still being processed.')
elif event.conference_solution.status == 'failure':
    print('Conference creation failed.')
```

--------------------------------

### Add New Calendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Create and add a new calendar to your Google account. Provide a summary (title) and an optional description for the new calendar.

```python
from gcsa.calendar import Calendar

calendar = Calendar(
    'Travel calendar',
    description='Calendar for travel related events'
)
calendar = gc.add_calendar(calendar)
```

--------------------------------

### Create Attachment for Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/attachments.md

Use the `Attachment` class to define an attachment. Pass it as the `attachments` parameter when creating an `Event`.

```python
from gcsa.attachment import Attachment

attachment = Attachment(file_url='https://bit.ly/3lZo0Cc',
                        title='My file',
                        mime_type='application/vnd.google-apps.document')

event = Event('Meeting',
              start=(22/Apr/2019)[12:00],
              attachments=attachment)
```

--------------------------------

### EntryPoint to JSON

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/serializers.md

Serializes an EntryPoint object, typically used for conference details, into JSON format. Requires 'entryPointType' and 'uri'.

```python
from gcsa.conference import EntryPoint
from gcsa.serializers.conference_serializer import EntryPointSerializer

entry_point = EntryPoint(
    EntryPoint.VIDEO,
    uri='https://meet.google.com/aaa-bbbb-ccc'
)

EntryPointSerializer.to_json(entry_point)
```

```javascript
{
    'entryPointType': 'video',
    'uri': 'https://meet.google.com/aaa-bbbb-ccc'
}
```

--------------------------------

### Add Attendee by Email to Event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/attendees.md

Shows how to add an attendee to an event by simply providing their email address to the Event constructor. The Attendee object is created automatically.

```python
event = Event('Meeting',
              start=(17/Jul/2020)[12:00],
              attendees='attendee@gmail.com')
```

--------------------------------

### Add Calendar

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/calendars.md

Creates a new calendar with the specified details.

```APIDOC
## Add Calendar

### Description
Creates a new calendar with a given summary and description.

### Method
`add_calendar(calendar: Calendar)`

### Parameters
#### Request Body
- **calendar** (Calendar) - Required - A `Calendar` object containing the details for the new calendar.
  - **summary** (string) - Required - The title of the calendar.
  - **description** (string) - Optional - A description for the calendar.

### Response
#### Success Response (200)
- **Calendar** (object) - The newly created `Calendar` object.
```

--------------------------------

### Specific Time Reminder Conversion

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/reminders.md

Demonstrates how GCSA converts `days_before` and `at` to `minutes_before_start` after an event is added or updated. Note that `days_before` and `at` will be `None` after conversion.

```python
from datetime import time

event = Event(
    'Meeting',
    start=(22/Apr/2019)[12:00],
    reminders=[
        # Day before the event at 12:00
        EmailReminder(days_before=1, at=time(12, 00))
    ]
)

event.reminders[0].minutes_before_start is None
event.reminders[0].days_before == 1
event.reminders[0].at == time(12, 00)

event = gc.add_event(event)

event.reminders[0].minutes_before_start == 24 * 60  # exactly one day before
event.reminders[0].days_before is None
event.reminders[0].at is None
```

--------------------------------

### Weekly Recurrence Every Other Week on Specific Days for 8 Occurrences

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/recurrence.md

Defines a weekly recurrence that repeats every other week on Tuesdays and Thursdays, for a total of 8 occurrences. This example includes interval, count, and multiple day specifications.

```python
Recurrence.rule(freq=WEEKLY,
                interval=2,
                count=8,
                by_week_day=[TU, TH])
```

--------------------------------

### Create a simple daily recurring event

Source: https://github.com/kuzmoyev/google-calendar-simple-api/blob/master/docs/source/recurrence.md

Use Recurrence.rule() to define a daily recurrence for an event. This is useful for events that repeat every day.

```python
Event('Breakfast',
      (1/Jan/2020)[9:00],
      (1/Jan/2020)[10:00],
      recurrence=Recurrence.rule(freq=DAILY))
```

--------------------------------

### Manually Serialize GCSA Objects to Google API JSON

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Provides examples of using GCSA serializers to convert GCSA objects (like Event, Attachment, ACL Rule) into Google API JSON format and vice versa. This is useful for custom integrations or debugging.

```python
from gcsa.event import Event
from gcsa.serializers.event_serializer import EventSerializer
from gcsa.attachment import Attachment
from gcsa.serializers.attachment_serializer import AttachmentSerializer
from gcsa.acl import AccessControlRule, ACLRole, ACLScopeType
from gcsa.serializers.acl_rule_serializer import ACLRuleSerializer
from datetime import datetime

# Event → JSON
event = Event('Meeting', start=datetime(2024, 4, 22, 18, 0))
json_dict = EventSerializer.to_json(event)
# {'summary': 'Meeting', 'start': {'dateTime': '2024-04-22T18:00:00+...', ...}, ...}

# JSON → Event
restored = EventSerializer.to_object(json_dict)
# <Event 2024-04-22 18:00:00 - Meeting>

# Attachment → JSON
attachment = Attachment(
    file_url='https://bit.ly/3lZo0Cc',
    title='My file',
    mime_type='application/vnd.google-apps.document'
)
AttachmentSerializer.to_json(attachment)
# {'title': 'My file', 'fileUrl': 'https://bit.ly/3lZo0Cc', 'mimeType': '...'}

# ACL rule → JSON
rule = AccessControlRule(
    role=ACLRole.READER,
    scope_type=ACLScopeType.USER,
    scope_value='friend@gmail.com'
)
ACLRuleSerializer.to_json(rule)
# {'role': 'reader', 'scope': {'type': 'user', 'value': 'friend@gmail.com'}}
```

--------------------------------

### Create Timed and All-Day Events

Source: https://context7.com/kuzmoyev/google-calendar-simple-api/llms.txt

Create and add timed or all-day events to the calendar. Supports setting reminders and descriptions.

```python
from datetime import datetime, date
from gcsa.event import Event
from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar('your_email@gmail.com')

# Timed event
event = Event(
    'Team Meeting',
    start=datetime(2024, 4, 22, 12, 0),
    end=datetime(2024, 4, 22, 13, 0),
    location='Conference Room A',
    description='Quarterly planning session',
    minutes_before_popup_reminder=15,
    minutes_before_email_reminder=30
)
event = gc.add_event(event)
print(event.id)  # Google-assigned event ID

# All-day event
all_day = Event(
    'Company Holiday',
    start=date(2024, 8, 1),
    end=date(2024, 8, 2)
)
gc.add_event(all_day)
```