### get_example()

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.examples.html

Retrieves a specific example component based on its directory and name. Raises an error if the example is not found.

```APIDOC
## get_example()

### Description
Return an example and raise an error if it is absent.

### Parameters
#### Path Parameters
- **_component_directory_** (string) - Required - The directory where the example component is located.
- **_example_name_** (string) - Required - The name of the example component to retrieve.

### Return Type
`bytes`
```

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

### Calendar Example Class Method

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.calendar.html

Creates an example calendar object.

```APIDOC
## Class Method: example

### Description
Return the calendar example with the given name.

### Parameters
* **_name** (str) - The name of the example calendar to retrieve.

### Returns
* **Calendar** - An example Calendar object.
```

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

### VEVENT Examples

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.event.html

Illustrates various VEVENT component examples as per RFC 5545.

```APIDOC
## VEVENT Examples

### Description
These examples showcase different use cases for the VEVENT component, including meetings, transparent reminders, annual anniversaries, and multi-day events.

### Example 1: Meeting (Opaque)
```icalendar
BEGIN:VEVENT
UID:19970901T130000Z-123401@example.com
DTSTAMP:19970901T130000Z
DTSTART:19970903T163000Z
DTEND:19970903T190000Z
SUMMARY:Annual Employee Review
CLASS:PRIVATE
CATEGORIES:BUSINESS,HUMAN RESOURCES
END:VEVENT
```

### Example 2: Transparent Reminder
```icalendar
BEGIN:VEVENT
UID:19970901T130000Z-123402@example.com
DTSTAMP:19970901T130000Z
DTSTART:19970401T163000Z
DTEND:19970402T010000Z
SUMMARY:Laurel is in sensitivity awareness class.
CLASS:PUBLIC
CATEGORIES:BUSINESS,HUMAN RESOURCES
TRANSP:TRANSPARENT
END:VEVENT
```

### Example 3: Annual Anniversary
```icalendar
BEGIN:VEVENT
UID:19970901T130000Z-123403@example.com
DTSTAMP:19970901T130000Z
DTSTART;VALUE=DATE:19971102
SUMMARY:Our Blissful Anniversary
TRANSP:TRANSPARENT
CLASS:CONFIDENTIAL
CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
RRULE:FREQ=YEARLY
END:VEVENT
```

### Example 4: Multi-day Event
```icalendar
BEGIN:VEVENT
UID:20070423T123432Z-541111@example.com
DTSTAMP:20070423T123432Z
DTSTART;VALUE=DATE:20070628
DTEND;VALUE=DATE:20070709
SUMMARY:Festival International de Jazz de Montreal
TRANSP:TRANSPARENT
END:VEVENT
```
```

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

### example classmethod

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.available.html

Returns an example calendar with the given name, conforming to RFC 7953.

```APIDOC
## classmethod example

### Description
Return the calendar example with the given name.

### Parameters
* **_name** (str) - Defaults to 'rfc_7953_1'. The name of the example calendar to retrieve.

### Return Type
`Available`
```

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

### start

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.event.html

The start property represents the start time of an event. It can be a date or datetime object.

```APIDOC
## start

### Description
The start of the event. Invalid values raise an InvalidCalendar. If there is no start, we also raise an IncompleteComponent error.

### Example
```python
>>> from datetime import datetime
>>> from icalendar import Event
>>> event = Event()
>>> event.start = datetime(2021, 1, 1, 12)
>>> event.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
>>> event.duration  # 1800 seconds == 30 minutes
datetime.timedelta(seconds=1800)
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART:20210101T120000
DTEND:20210101T123000
END:VEVENT
```
```

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

### Recurring AVAILABLE Sub-component Example

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.available.html

This example demonstrates the structure of a recurring 'AVAILABLE' sub-component, including its start and end times, recurrence rule, and location.

```icalendar
BEGIN:AVAILABLE
UID:57DD4AAF-3835-46B5-8A39-B3B253157F01
SUMMARY:Monday to Friday from 9:00 to 17:00
DTSTART;TZID=America/Denver:20111023T090000
DTEND;TZID=America/Denver:20111023T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
LOCATION:Denver
END:AVAILABLE

```

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

### Calculate Alarm Triggers

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.alarm.html

Demonstrates how to calculate alarm triggers based on TRIGGER, DURATION, and REPEAT properties. This example shows an alarm set to trigger multiple times before the parent component's start.

```python
>>> from icalendar import Alarm
>>> from datetime import timedelta
>>> alarm = Alarm()
>>> alarm.TRIGGER = timedelta(hours=-4)  # trigger 4 hours before START
>>> alarm.DURATION = timedelta(hours=1)  # after 1 hour trigger again
>>> alarm.REPEAT = 2  # trigger 2 more times
>>> alarm.triggers.start == (timedelta(hours=-4),  timedelta(hours=-3),  timedelta(hours=-2))
True
>>> alarm.triggers.end
()
>>> alarm.triggers.absolute
()
```

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

### Set event start, end, and duration

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.event.html

Illustrates how to set the start and end times of an event and how to calculate its duration. The duration is automatically computed if both start and end times are provided.

```python
>>> from datetime import datetime
>>> from icalendar import Event
>>> event = Event()
>>> event.start = datetime(2021, 1, 1, 12)
>>> event.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
>>> event.duration  # 1800 seconds == 30 minutes
datetime.timedelta(seconds=1800)
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART:20210101T120000
DTEND:20210101T123000
END:VEVENT
```

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

### Install icalendar for Development

Source: https://icalendar.readthedocs.io/en/stable/contribute/development.html

Run this command to install icalendar with all development dependencies, including those for tests, documentation, and code formatting. It also sets up a Python virtual environment.

```makefile
make dev

```

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

### Example of a Good Change Log Entry

Source: https://icalendar.readthedocs.io/en/stable/contribute/index.html

This example demonstrates a well-formatted change log entry for a feature addition. It includes a clear summary, references a specific component and property, and provides author attribution.

```python
Created a :meth:`~icalendar.prop.recur.weekday.vWeekday.ical_value` property for the :class:`~icalendar.prop.recur.weekday.vWeekday` component, mirroring the existing pattern on :class:`~icalendar.prop.boolean.vBoolean`. @mvanhorn
```

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

### Todo.example class method

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.todo.html

Returns an example Todo object with the specified name.

```APIDOC
## Todo.example class method

### Description
Return the todo example with the given name.

### Parameters
* `_name` (str) - Optional - The name for the example todo.

### Return Type
`Todo`
```

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

### Calculate alarm times for a Todo

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.todo.html

Shows how to check for alarm times associated with a VTODO component. This example initializes a Todo, sets its start time, and then checks the number of alarm times. Note that this calculation only considers DTSTART and DUE, ignoring RDATE, EXDATE, and RRULE.

```python
>>> from datetime import datetime
>>> from icalendar import Todo
>>> todo = Todo()  # empty without alarms
>>> todo.start = datetime(2024, 10, 26, 10, 21)
>>> len(todo.alarms.times)
0


```

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

### Get CLI Help

Source: https://icalendar.readthedocs.io/en/stable/how-to/cli.html

Use the -h option to display all available commands and their usage.

```bash
icalendar -h

```

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

### LINK Property Examples

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.component.html

Examples demonstrating the usage of the LINK property with different parameters and values, including references to external resources and XML fragments.

```icalendar
LINK;LINKREL=SOURCE;LABEL=Venue;VALUE=URI:
 https://example.com/events
```

```icalendar
LINK;LINKREL="https://example.com/linkrel/derivedFrom";
 VALUE=URI:
 https://example.com/tasks/01234567-abcd1234.ics
```

```icalendar
LINK;LINKREL="https://example.com/linkrel/costStructure";
 VALUE=XML-REFERENCE:
 https://example.com/xmlDocs/bidFramework.xml
 #xpointer(descendant::CostStruc/range-to(
 following::CostStrucEND[1]))
```

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

### Create an example audio alarm

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.alarm.html

Creates an example VALARM component with an audio attachment, duration, repeat count, and trigger time. Use this to generate a basic alarm structure.

```python
>>> from icalendar import Alarm
>>> alarm = Alarm.example()
>>> print(alarm.to_ical().decode())
BEGIN:VALARM
ACTION:AUDIO
ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/sounds/bell-01.aud
DURATION:PT15M
REPEAT:4
TRIGGER;VALUE=DATE-TIME:19970317T133000Z
END:VALARM


```

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

### Install uv on macOS, Linux, and Windows with WSL

Source: https://icalendar.readthedocs.io/en/stable/contribute/development.html

Use this command to install uv, a tool for managing Python versions and dependencies. Follow any further instructions provided in the console output.

```shell
curl -LsSf https://astral.sh/uv/install.sh | sh

```

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

### Install icalendar on Fedora

Source: https://icalendar.readthedocs.io/en/stable/how-to/install.html

Install the python3-icalendar package on Fedora systems using dnf.

```bash
sudo dnf install python3-icalendar
```

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

### Alarm Example Class Method

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.alarm.html

A class method to retrieve an example Alarm instance by name.

```APIDOC
## classmethod example(_name ='example'_)

Return the alarm example with the given name.

### Return type

`Alarm`
```

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

### START Property for VFREEBUSY

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.free_busy.html

Defines the inclusive start time for a VFREEBUSY component.

```APIDOC
## START Property for VFREEBUSY

### Description
The "DTSTART" property for a "VFREEBUSY" specifies the inclusive start of the component.

### Accepted Values
- `datetime`
- `date`

### Behavior
- If the attribute has invalid values, `InvalidCalendar` is raised.
- If the value is absent, `None` is returned.
- The value can be deleted using `del` or by setting it to `None`.
```

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

### Install icalendar on Debian or Ubuntu

Source: https://icalendar.readthedocs.io/en/stable/how-to/install.html

Install the python3-icalendar package on Debian or Ubuntu systems using apt-get.

```bash
sudo apt-get install python3-icalendar
```

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

### Set VTODO start, end, and duration

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.todo.html

Illustrates how to set the start, end, and duration for a VTODO component. The duration can be calculated from the start and end times.

```python
>>> from datetime import datetime
>>> from icalendar import Todo
>>> todo = Todo()
>>> todo.start = datetime(2021, 1, 1, 12)
>>> todo.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
>>> todo.duration  # 1800 seconds == 30 minutes
datetime.timedelta(seconds=1800)
>>> print(todo.to_ical())
BEGIN:VTODO
DTSTART:20210101T120000
DUE:20210101T123000
END:VTODO
```

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

### Install uv on Windows

Source: https://icalendar.readthedocs.io/en/stable/contribute/development.html

This PowerShell command installs uv on Windows systems. Ensure your execution policy allows script execution.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

```

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

### Install icalendar with pip

Source: https://icalendar.readthedocs.io/en/stable/how-to/install.html

Use this command to install the icalendar package for use in your Python projects. Successful installation allows importing the package.

```bash
pip install icalendar
```

```python
>>> import icalendar
```

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

### Event Categories Example

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.available.html

This example shows how to create an event, set its categories, and append new categories. It also demonstrates how to retrieve the iCalendar representation.

```python
>>> from icalendar import Event
>>> event = Event()
>>> event.categories = ["Work", "Meeting"]
>>> print(event.to_ical())
BEGIN:VEVENT
CATEGORIES:Work,Meeting
END:VEVENT
>>> event.categories.append("Lecture")
>>> event.categories == ["Work", "Meeting", "Lecture"]
True

```

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

### Install icalendar on Alpine Linux

Source: https://icalendar.readthedocs.io/en/stable/how-to/install.html

Install the py3-icalendar package on Alpine Linux using the apk package manager.

```bash
sudo apk add py3-icalendar
```

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

### Install icalendar on Arch Linux

Source: https://icalendar.readthedocs.io/en/stable/how-to/install.html

Install the python-icalendar package on Arch Linux and its derivatives using pacman.

```bash
sudo pacman -S python-icalendar
```

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

### Timezone.example

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.timezone.html

Returns a predefined timezone example component.

```APIDOC
## Timezone.example

### Description
Return the timezone example with the given name.

### Method
classmethod

### Parameters
* **name** (str) - Optional - The name of the timezone example to retrieve. Defaults to 'pacific_fiji'.

### Return Type
`Calendar`
```

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

### Example of a Poor Change Log Entry

Source: https://icalendar.readthedocs.io/en/stable/contribute/index.html

This example illustrates a poorly written change log entry that lacks clarity and proper formatting, failing to adhere to the contribution guidelines.

```text
Fix #123456 by chaning config of file [did_not_read_this_guide]
```

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

### icalendar.cal.examples Module

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.html

Provides access to example iCalendar data.

```APIDOC
## icalendar.cal.examples Module

### Description
This module contains functions for retrieving example iCalendar data.

### Methods
- `get_example()`: Retrieves an example iCalendar object.
```

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

### property start

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.todo.html

Represents the start time of the VTODO component. Raises InvalidCalendar or IncompleteComponent errors for invalid or missing values.

```APIDOC
## property start

### Description
The start of the VTODO.
Invalid values raise an InvalidCalendar. If there is no start, we also raise an IncompleteComponent error.
You can get the start, end and duration of a Todo as follows:
```python
>>> from datetime import datetime
>>> from icalendar import Todo
>>> todo = Todo()
>>> todo.start = datetime(2021, 1, 1, 12)
>>> todo.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
>>> todo.duration  # 1800 seconds == 30 minutes
datetime.timedelta(seconds=1800)
>>> print(todo.to_ical())
BEGIN:VTODO
DTSTART:20210101T120000
DUE:20210101T123000
END:VTODO
```

```

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

### Verify Icalendar Installation

Source: https://icalendar.readthedocs.io/en/stable/contribute/development.html

Launch a Python interpreter and import the icalendar library to verify a successful installation. This snippet shows the expected output when creating a basic Calendar object.

```python
>>> import icalendar
>>> icalendar.Calendar()
VCALENDAR({})

```

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

### VAVAILABILITY Component Example 1

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.availability.html

An example of a VAVAILABILITY component representing a user's availability from Monday to Friday, 9:00 am to 5:00 pm in the America/Montreal time zone.

```APIDOC
## VAVAILABILITY Component Example 1

### Description
This example demonstrates a VAVAILABILITY component that defines a recurring availability period.

### iCalendar Data
```icalendar
BEGIN:VAVAILABILITY
ORGANIZER:mailto:bernard@example.com
UID:0428C7D2-688E-4D2E-AC52-CD112E2469DF
DTSTAMP:20111005T133225Z
BEGIN:AVAILABLE
UID:34EDA59B-6BB1-4E94-A66C-64999089C0AF
SUMMARY:Monday to Friday from 9:00 to 17:00
DTSTART;TZID=America/Montreal:20111002T090000
DTEND;TZID=America/Montreal:20111002T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
END:AVAILABLE
END:VAVAILABILITY
```
```

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

### VAVAILABILITY Component Example 2

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.availability.html

An example of a VAVAILABILITY component with multiple AVAILABLE subcomponents, specifying different availability periods and locations within a date range.

```APIDOC
## VAVAILABILITY Component Example 2

### Description
This example shows a VAVAILABILITY component with two AVAILABLE subcomponents, detailing different work schedules and locations for weekdays and Fridays, within a specific date range.

### iCalendar Data
```icalendar
BEGIN:VAVAILABILITY
ORGANIZER:mailto:bernard@example.com
UID:84D0F948-7FC6-4C1D-BBF3-BA9827B424B5
DTSTAMP:20111005T133225Z
DTSTART;TZID=America/Montreal:20111002T000000
DTEND;TZID=America/Montreal:20111202T000000
BEGIN:AVAILABLE
UID:7B33093A-7F98-4EED-B381-A5652530F04D
SUMMARY:Monday to Thursday from 9:00 to 17:00
DTSTART;TZID=America/Montreal:20111002T090000
DTEND;TZID=America/Montreal:20111002T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH
LOCATION:Main Office
END:AVAILABLE
BEGIN:AVAILABLE
UID:DF39DC9E-D8C3-492F-9101-0434E8FC1896
SUMMARY:Friday from 9:00 to 12:00
DTSTART;TZID=America/Montreal:20111006T090000
DTEND;TZID=America/Montreal:20111006T120000
RRULE:FREQ=WEEKLY
LOCATION:Branch Office
END:AVAILABLE
END:VAVAILABILITY
```
```

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

### Import Calendar and Event Classes

Source: https://icalendar.readthedocs.io/en/stable/how-to/usage.html

These imports are used in subsequent examples to avoid repetition.

```python
>>> from icalendar import Calendar, Event
```

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

### icalendar.attr.get_start_property

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.attr.html

Retrieves the start property (DTSTART) with validation.

```APIDOC
## icalendar.attr.get_start_property(_component_)

### Description
Get the start property with validation.

### Parameters
* **component** (`Component`) – The component from which to get its start property.

### Return type
`date` | `datetime`

### Returns
The `DTSTART` value.

### Raises
**IncompleteComponent** – If no `DTSTART` is present.
```

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

### VAVAILABILITY Component Example 2

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.availability.html

Represents a user available Monday through Thursday, 9:00 am to 5:00 pm at the main office, and Friday, 9:00 am to 12:00 pm at the branch office, between October 2nd and December 2nd, 2011, in the America/Montreal time zone. This example shows multiple AVAILABLE subcomponents with different schedules and locations.

```icalendar
BEGIN:VAVAILABILITY
ORGANIZER:mailto:bernard@example.com
UID:84D0F948-7FC6-4C1D-BBF3-BA9827B424B5
DTSTAMP:20111005T133225Z
DTSTART;TZID=America/Montreal:20111002T000000
DTEND;TZID=America/Montreal:20111202T000000
BEGIN:AVAILABLE
UID:7B33093A-7F98-4EED-B381-A5652530F04D
SUMMARY:Monday to Thursday from 9:00 to 17:00
DTSTART;TZID=America/Montreal:20111002T090000
DTEND;TZID=America/Montreal:20111002T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH
LOCATION:Main Office
END:AVAILABLE
BEGIN:AVAILABLE
UID:DF39DC9E-D8C3-492F-9101-0434E8FC1896
SUMMARY:Friday from 9:00 to 12:00
DTSTART;TZID=America/Montreal:20111006T090000
DTEND;TZID=America/Montreal:20111006T120000
RRULE:FREQ=WEEKLY
LOCATION:Branch Office
END:AVAILABLE
END:VAVAILABILITY
```

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

### Get Default Timezone (zoneinfo)

Source: https://icalendar.readthedocs.io/en/stable/how-to/usage.html

Since version 6.0.0, icalendar defaults to using `zoneinfo` for timezone implementations. This example shows how to retrieve the start time of an example event and check its timezone info.

```python
>>> dt = icalendar.Calendar.example("timezoned").events[0].start
>>> dt.tzinfo
ZoneInfo(key='Europe/Vienna')

```

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

### Get SEQUENCE property of a revised Event

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.availability.html

Shows how to retrieve the sequence number of an event that has been revised multiple times, loaded from an example calendar.

```python
>>> from icalendar import Calendar
>>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
>>> event = calendar.events[0]
>>> event.sequence
10
```

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

### Display Make command help

Source: https://icalendar.readthedocs.io/en/stable/contribute/documentation/build-check.html

Shows available make commands and their descriptions. This is useful for understanding the different documentation build and check tasks.

```shell
make help

```

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

### Switch to pytz Timezone Implementation

Source: https://icalendar.readthedocs.io/en/stable/how-to/usage.html

To continue using `pytz` as the default timezone implementation after version 6.0.0, you can call the `icalendar.use_pytz()` function. This example demonstrates retrieving an event's start time after switching.

```python
>>> icalendar.use_pytz()
>>> dt = icalendar.Calendar.example("timezoned").events[0].start
>>> dt.tzinfo
<DstTzInfo 'Europe/Vienna' CET+1:00:00 STD>

```

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

### Create and Set Calendar Properties

Source: https://icalendar.readthedocs.io/en/stable/how-to/usage.html

Demonstrates creating a Calendar component and setting its 'dtstart' and 'summary' properties. The output shows the properties as key-value pairs.

```python
>>> cal = Calendar()
>>> cal["dtstart"] = "20050404T080000"
>>> cal["summary"] = "Python meeting about calendaring"
>>> for k,v in cal.items():
...     k,v
('DTSTART', '20050404T080000')
('SUMMARY', 'Python meeting about calendaring')
```

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

### Create Event Organizer with Parameters

Source: https://icalendar.readthedocs.io/en/stable/how-to/usage.html

Demonstrates creating a vCalAddress for an organizer and adding parameters like 'cn' (common name) and 'role'. Use vCalAddress and vText for parameter values.

```python
>>> from icalendar import vCalAddress, vText
>>> organizer = vCalAddress("MAILTO:noone@example.com")
>>> organizer.params["cn"] = vText("Max Rasmussen")
>>> organizer.params["role"] = vText("CHAIR")
>>> event["organizer"] = organizer
```

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

### Live HTML preview of documentation

Source: https://icalendar.readthedocs.io/en/stable/contribute/documentation/build-check.html

Builds documentation and serves it with live reload in the browser. This command is ideal for actively editing documentation files.

```shell
make livehtml

```

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

### Demonstrate Multiple Timezone Implementations

Source: https://icalendar.readthedocs.io/en/stable/how-to/usage.html

This example shows how to create an event using dateutil.tz, pytz, and zoneinfo, demonstrating that they all produce the same iCalendar output.

```python
>>> import pytz, zoneinfo, dateutil.tz  # timezone libraries
>>> import datetime, icalendar
>>> e = icalendar.Event()
>>> tz = dateutil.tz.tzstr("Europe/London")
>>> e["X-DT-DATEUTIL"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> tz = pytz.timezone("Europe/London")
>>> e["X-DT-USE-PYTZ"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> tz = zoneinfo.ZoneInfo("Europe/London")
>>> e["X-DT-ZONEINFO"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
>>> print(e.to_ical())  # the libraries yield the same result
BEGIN:VEVENT
X-DT-DATEUTIL;TZID=Europe/London:20240619T100100
X-DT-USE-PYTZ;TZID=Europe/London:20240619T100100
X-DT-ZONEINFO;TZID=Europe/London:20240619T100100
END:VEVENT

```

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

### Build documentation as HTML

Source: https://icalendar.readthedocs.io/en/stable/contribute/documentation/build-check.html

Generates static HTML documentation without live reload. The output can be viewed by opening `_build/html/index.html` in a browser.

```shell
make html

```

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

### Complete an example Todo component

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.todo.html

Demonstrates how to update an existing VTODO component with completion details, including setting percentage complete, completion date, and status. Requires importing `datetime`, `timezone`, `Todo`, and `STATUS`.

```python
>>> from datetime import datetime, timezone
>>> from icalendar import Todo, STATUS
>>> todo = Todo.example()
>>> todo["PERCENT-COMPLETE"] = 100
>>> todo["COMPLETED"] = datetime(2007, 5, 1, 12, tzinfo=timezone.utc)
>>> todo.status = STATUS.COMPLETED
>>> print(todo.to_ical().decode())
BEGIN:VTODO
CATEGORIES:FAMILY,FINANCE
CLASS:CONFIDENTIAL
COMPLETED:2007-05-01 12:00:00+00:00
DTSTAMP:20070313T123432Z
DUE;VALUE=DATE:20070501
PERCENT-COMPLETE:100
STATUS:COMPLETED
SUMMARY:Submit Quebec Income Tax Return for 2006
UID:20070313T123432Z-456553@example.com
END:VTODO

```

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

### Format Code

Source: https://icalendar.readthedocs.io/en/stable/contribute/development.html

Run this command to automatically format the project's code according to established conventions.

```bash
make format

```

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

### Create and Use CaselessDict

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.caselessdict.html

Demonstrates how to create a CaselessDict and access values using keys with different casing. Keys are normalized to uppercase internally.

```python
from icalendar.caselessdict import CaselessDict
d = CaselessDict(summary="Meeting")
d["SUMMARY"]
'Meeting'
"summary" in d
```

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

### set_start

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.alarms.html

Sets the start datetime for the component. This is necessary for alarms that are relative to the component's start time.

```APIDOC
## set_start(_dt_)

### Description
Set the start of the component. If you have only absolute alarms, this is not required. If you have alarms relative to the start of a component, set the start here.

### Parameters
#### Path Parameters
- **_dt_** (datetime) - Required - The start datetime for the component.
```

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

### Serve live HTML preview URL

Source: https://icalendar.readthedocs.io/en/stable/contribute/documentation/build-check.html

The URL provided by `make livehtml` to access the live preview in a web browser.

```shell
[sphinx-autobuild] Serving on http://127.0.0.1:8050

```

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

### Create a Fuzz Test Case Locally

Source: https://icalendar.readthedocs.io/en/stable/how-to/fuzz-testing.html

Use this template to create a local fuzz test case. Fill in the base64 string and a descriptive filename. This helps in reproducing errors.

```bash
echo "<base64>" | base64 -d | tee src/icalendar/tests/calendars/fuzz_testcase_<filename>.ics
```

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

### Create a new FreeBusy component

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.free_busy.html

Demonstrates how to create a new VFREEBUSY component using the `FreeBusy.new()` class method. The output shows the basic structure of a VFREEBUSY component with default properties.

```python
>>> from icalendar import FreeBusy
>>> free_busy = FreeBusy.new()
>>> print(free_busy.to_ical())
BEGIN:VFREEBUSY
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VFREEBUSY


```

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

### RELATED-TO Property Example (RFC 5545)

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.component.html

Example of the RELATED-TO property with a UID value, as specified in RFC 5545.

```icalendar
RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com
```

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

### PRODID Example

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.calendar.html

Example of the PRODID property, which identifies the product that created the iCalendar object. This format is a common convention.

```text
-//ABC Corporation//NONSGML My Product//EN
```

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

### Inclusive Properties Example

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.alarm.html

Illustrates the 'inclusive' class variable, showing pairs of properties where the presence of the first implies the presence of the second.

```python
('duration', 'repeat')

```

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

### Install Icalendar Manually

Source: https://icalendar.readthedocs.io/en/stable/contribute/development.html

Installs icalendar and its dependencies in your current Python environment for local testing. This is an alternative if tox cannot be used.

```bash
cd src/icalendar
python -m pip install -e .

```

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

### new Class Method

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.component.html

Creates a new component with specified properties.

```APIDOC
## new Class Method

### Description
Create a new component.

### Parameters
- **comments** (`list`[`str`] | `str` | `None`): The comments of the component.
- **concepts** (`list`[`vUri` | `str`] | `str` | `vUri` | `None`): The concepts of the component.
- **created** (`date` | `None`): The created date of the component.
- **last_modified** (`date` | `None`): The last modified date of the component.
- **links** (`str` | `vUri` | `vUid` | `vXmlReference` | `None` | `list`[`str` | `vUri` | `vUid` | `vXmlReference`]): The links associated with the component.
- **related_to** (`None` | `str` | `vText` | `vUri` | `vUid` | `list`[`str` | `vText` | `vUri` | `vUid`]): Related components.
- **stamp** (`date` | `None`): The DTSTAMP of the component.
- **subcomponents** (`Iterable`[`Component`] | `None`): The subcomponents of the component.

### Raises
**InvalidCalendar**: If the content is not valid according to RFC 5545.

### Return type
`Component`

### Warning
As time progresses, we will be stricter with the validation.
```

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

### RFC 5545 RELATED-TO SIBLING example

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.enums.html

Example of using RELTYPE=SIBLING within a RELATED-TO property as defined in RFC 5545.

```icalendar
RELATED-TO;RELTYPE=SIBLING:19960401-080045-4000F192713@
 example.com
```

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

### RELATED-TO Property Example with Datetime (RFC 5545)

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.component.html

Example of the RELATED-TO property with a datetime value, as specified in RFC 5545.

```icalendar
RELATED-TO:19960401-080045-4000F192713-0052@example.com
```

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

### Add, Commit, and Push Version Switcher Changes

Source: https://icalendar.readthedocs.io/en/stable/contribute/maintenance.html

Stage, commit, and push the changes made to the version switcher configuration file.

```bash
git add docs/_static/version-switcher.json
git commit -m "Update version switcher for $VERSION"
```

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

### Run Vale with Specific Options

Source: https://icalendar.readthedocs.io/en/stable/contribute/documentation/build-check.html

Use this command to run Vale and display only warnings or errors in the console for a single file. The `make vale` command installs Vale automatically on first use.

```bash
make vale VALEOPTS="--minAlertLevel='warning'" VALEFILES="docs/index.rst"
```

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

### RELATED-TO Property Example with URI and RELTYPE (RFC 9253)

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.component.html

Example of the RELATED-TO property with VALUE=URI and RELTYPE=STARTTOFINISH, as specified in RFC 9253.

```icalendar
RELATED-TO;VALUE=URI;RELTYPE=STARTTOFINISH:
 https://example.com/caldav/user/jb/cal/
 19960401-080045-4000F192713.ics
```

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

### RELATED Enum for Alarm Triggers

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.enums.html

Defines the relationship of an alarm trigger to a calendar component's start or end time. Defaults to START if not specified.

```python
END = 'END'#
```

```python
START = 'START'#
```

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

### RELATED-TO Property Examples

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.component.html

Examples of the RELATED-TO property as defined in RFC 5545 and RFC 9253, illustrating different relationship types and value formats.

```APIDOC
## RELATED-TO Property Examples

### RFC 5545 Examples

```
RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com
```

```
RELATED-TO:19960401-080045-4000F192713-0052@example.com
```

### RFC 9253 Examples

```
RELATED-TO;VALUE=URI;RELTYPE=STARTTOFINISH: https://example.com/caldav/user/jb/cal/ 19960401-080045-4000F192713.ics
```
```

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

### Creating an Email Alarm with Attendees

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.event.html

Illustrates how to create a new alarm component with multiple attendees and a summary. The example shows the resulting iCalendar format for the alarm.

```python
>>> from icalendar import Alarm, vCalAddress
>>> alarm = Alarm.new(attendees = [
...     vCalAddress("mailto:me@my-domain.com"),
...     vCalAddress("mailto:you@my-domain.com"),
... ], summary = "Email alarm")
>>> print(alarm.to_ical())
BEGIN:VALARM
ATTENDEE:mailto:me@my-domain.com
ATTENDEE:mailto:you@my-domain.com
SUMMARY:Email alarm
END:VALARM
```

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

### Example Fuzzed Calendar Data

Source: https://icalendar.readthedocs.io/en/stable/how-to/fuzz-testing.html

This is an example of the raw, decoded data that a fuzzer might generate. Observe the random data that could trigger errors.

```text
BEGIN:
Biiih:
Biiih0:
END:
```

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

### Accessing timezones in a Calendar object

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.calendar.html

Retrieve a list of timezone components from a Calendar object. This example demonstrates accessing timezone names after loading an example calendar.

```python
>>> from icalendar import Calendar
>>> calendar = Calendar.example("pacific_fiji")
>>> [timezone.tz_name for timezone in calendar.timezones]
['custom_Pacific/Fiji']
```

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

### Create a new Event object

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.event.html

Demonstrates how to create a new Event object with a specified start time and convert it to iCalendar format.

```python
>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event.new(start=datetime(2021, 1, 1, 12, 30, 0))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART:20210101T123000
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VEVENT
```

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

### Configure Sphinx Extension (Napoleon)

Source: https://icalendar.readthedocs.io/en/stable/contribute/documentation/build-check.html

Example configuration for the Napoleon Sphinx extension. This involves setting parameters like `napoleon_use_param`, `napoleon_google_docstring`, and `napoleon_attr_annotations` in the Sphinx configuration file.

```python
# -- Napolean configuration ----------------------------------
napoleon_use_param = True
napoleon_google_docstring = True
napoleon_attr_annotations = True

```

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

### Run Local Fuzz Tests

Source: https://icalendar.readthedocs.io/en/stable/how-to/fuzz-testing.html

After creating a test case file, run this command to execute the fuzz tests and verify that the error is reproduced.

```bash
tox -e py313 -- src/icalendar/tests/fuzzed/
```

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

### Example of CONCEPT property

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.component.html

The CONCEPT property defines formal categories for a calendar component, often referencing external resources. This example shows a URI pointing to event types.

```icalendar
CONCEPT:https://example.com/event-types/arts/music
```

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

### Creating a New Event

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.event.html

Demonstrates how to create a new Event object with a specified start time and convert it to iCalendar format.

```APIDOC
## Create a new Event

### Description
This snippet shows how to instantiate an Event object using the `new` class method, providing a start datetime, and then converting the event to its iCalendar string representation.

### Method
`Event.new(start=datetime)`

### Example
```python
>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event.new(start=datetime(2021, 1, 1, 12, 30, 0))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART:20210101T123000
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VEVENT
```
```

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

### Create and Push Release Tag

Source: https://icalendar.readthedocs.io/en/stable/contribute/maintenance.html

Create a Git tag for the release version and push it to the upstream repository.

```bash
git tag "v$VERSION"
git push upstream "v$VERSION" # to collective/icalendar
```

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

### Create a new Calendar instance

Source: https://icalendar.readthedocs.io/en/stable/reference/api/icalendar.cal.calendar.html

Demonstrates how to create a new Calendar object with a specified name using the `Calendar.new()` class method.

```python
>>> from icalendar import Calendar
>>> calendar = Calendar.new(name="My Calendar")
>>> print(calendar.calendar_name)
My Calendar
```