# pycalendar/icalendar architecture

> Architecture diagram of the GitHub repository pycalendar/icalendar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pycalendar/icalendar
- Repository: https://github.com/pycalendar/icalendar

## Overview

icalendar is a Python RFC 5545 library for creating, inspecting, modifying, parsing, and generating calendar data. Its principal workflow is to parse calendar text into components and typed properties, let callers work with the calendar model, then serialize it again. It also supports xCal XML and multiple timezone providers. The graph reflects documented capabilities and source-index references; unsampled modules are represented only where their role is clear, and their runtime links are left unverified where necessary.

Main entry points: [`src/icalendar/cal/component.py`](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/cal/component.py) (Component model), [`src/icalendar/parser/parameter.py`](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/parameter.py) (Parameter parser), [`src/icalendar/prop/dt/datetime.py`](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/prop/dt/datetime.py) (Date-time values), [`src/icalendar/parser/xcal/property.py`](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/property.py) (xCal properties)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calendar["Calendar model"]
  node_calendar_api["Calendar API<br/>[calendar.py]"]
  node_component["Component model<br/>[component.py]"]
end

subgraph group_formats["Calendar formats"]
  node_ics_component_parser["iCalendar parser<br/>[component.py]"]
  node_ics_contentline["Content lines<br/>[content_line.py]"]
  node_xcal_property["xCal properties<br/>[property.py]"]
  node_xcal_parser["xCal parser state<br/>[base.py]"]
  node_xcal_adapter["XML adapter<br/>[adapter.py]"]
  node_xcal_wrapper["xCal wrapper<br/>[wrapper.py]"]
end

subgraph group_types["Properties and parameters"]
  node_parameters["Parameter parser<br/>[parameter.py]"]
  node_property_factory["Property factory<br/>[factory.py]"]
  node_datetime_value["Date-time values<br/>[datetime.py]"]
  node_text_value["Text values<br/>[text.py]"]
  node_property_parameters["Parameter access<br/>[param.py]"]
end

subgraph group_timezones["Timezone support"]
  node_timezone_proxy["Timezone proxy<br/>[tzp.py]"]
  node_timezone_providers["Timezone providers"]
end

subgraph group_shared["Shared utilities"]
  node_caseless_dict["Case-insensitive map<br/>[caselessdict.py]"]
  node_parser_tools["Encoding helpers<br/>[parser_tools.py]"]
  node_tools["Date-time tools<br/>[tools.py]"]
  node_compatibility["Compatibility helpers<br/>[compatibility.py]"]
  node_enums["Calendar enums<br/>[enums.py]"]
end

node_caller(("Python caller"))

node_caller -.->|"uses calendar API"| node_calendar_api
node_calendar_api -.->|"manages components"| node_component
node_caller -.->|"inspects and modifies"| node_component
node_component -->|"parses iCalendar"| node_ics_component_parser
node_component -->|"parses xCal"| node_xcal_property
node_ics_component_parser -->|"reads content lines"| node_ics_contentline
node_ics_component_parser -->|"uses parameters"| node_parameters
node_ics_component_parser -->|"builds components"| node_component
node_component -->|"uses property types"| node_property_factory
node_xcal_property -->|"consumes XML elements"| node_xcal_parser
node_xcal_property -->|"adapts elements"| node_xcal_adapter
node_xcal_property -->|"uses parameters"| node_parameters
node_xcal_wrapper -->|"wraps properties"| node_xcal_property
node_xcal_wrapper -->|"uses adapter"| node_xcal_adapter
node_ics_contentline -->|"parses parameters"| node_parameters
node_parameters -->|"provides parameter values"| node_property_parameters
node_property_factory -->|"creates typed values"| node_datetime_value
node_property_factory -->|"creates typed values"| node_text_value
node_datetime_value -->|"localizes date-times"| node_timezone_proxy
node_timezone_proxy -->|"selects provider"| node_timezone_providers
node_timezone_proxy -->|"uses date-time tools"| node_tools
node_component -->|"uses case-insensitive map"| node_caseless_dict
node_component -->|"uses encoding helpers"| node_parser_tools
node_datetime_value -->|"decodes values"| node_parser_tools
node_datetime_value -->|"uses compatibility types"| node_compatibility
node_datetime_value -->|"uses parameter access"| node_property_parameters
node_parameters -->|"uses case-insensitive map"| node_caseless_dict
node_parameters -->|"uses compatibility types"| node_compatibility
node_parameters -->|"uses calendar enums"| node_enums

click node_calendar_api "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/cal/calendar.py"
click node_component "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/cal/component.py"
click node_ics_component_parser "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/ical/component.py"
click node_ics_contentline "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/content_line.py"
click node_xcal_property "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/property.py"
click node_xcal_parser "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/base.py"
click node_xcal_adapter "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/adapter.py"
click node_xcal_wrapper "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/wrapper.py"
click node_parameters "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/parameter.py"
click node_property_factory "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/prop/factory.py"
click node_datetime_value "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/prop/dt/datetime.py"
click node_text_value "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/prop/text.py"
click node_property_parameters "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/param.py"
click node_timezone_proxy "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/timezone/tzp.py"
click node_timezone_providers "https://github.com/pycalendar/icalendar/tree/main/src/icalendar/timezone"
click node_caseless_dict "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/caselessdict.py"
click node_parser_tools "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser_tools.py"
click node_tools "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/tools.py"
click node_compatibility "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/compatibility.py"
click node_enums "https://github.com/pycalendar/icalendar/blob/main/src/icalendar/enums.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_calendar_api,node_component toneBlue
class node_ics_component_parser,node_ics_contentline,node_xcal_property,node_xcal_parser,node_xcal_adapter,node_xcal_wrapper toneAmber
class node_parameters,node_property_factory,node_datetime_value,node_text_value,node_property_parameters toneMint
class node_timezone_proxy,node_timezone_providers toneRose
class node_caseless_dict,node_parser_tools,node_tools,node_compatibility,node_enums,node_caller toneIndigo
```

## Components

### Calendar model

- [Calendar API](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/cal/calendar.py): `src/icalendar/cal/calendar.py`
- [Component model](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/cal/component.py): `src/icalendar/cal/component.py`

### Calendar formats

- [iCalendar parser](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/ical/component.py): `src/icalendar/parser/ical/component.py`
- [Content lines](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/content_line.py): `src/icalendar/parser/content_line.py`
- [xCal properties](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/property.py): `src/icalendar/parser/xcal/property.py`
- [xCal parser state](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/base.py): `src/icalendar/parser/xcal/base.py`
- [XML adapter](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/adapter.py): `src/icalendar/parser/xcal/adapter.py`
- [xCal wrapper](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/xcal/wrapper.py): `src/icalendar/parser/xcal/wrapper.py`

### Properties and parameters

- [Parameter parser](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser/parameter.py): `src/icalendar/parser/parameter.py`
- [Property factory](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/prop/factory.py): `src/icalendar/prop/factory.py`
- [Date-time values](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/prop/dt/datetime.py): `src/icalendar/prop/dt/datetime.py`
- [Text values](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/prop/text.py): `src/icalendar/prop/text.py`
- [Parameter access](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/param.py): `src/icalendar/param.py`

### Timezone support

- [Timezone proxy](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/timezone/tzp.py): `src/icalendar/timezone/tzp.py`
- [Timezone providers](https://github.com/pycalendar/icalendar/tree/main/src/icalendar/timezone): `src/icalendar/timezone`

### Shared utilities

- [Case-insensitive map](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/caselessdict.py): `src/icalendar/caselessdict.py`
- [Encoding helpers](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/parser_tools.py): `src/icalendar/parser_tools.py`
- [Date-time tools](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/tools.py): `src/icalendar/tools.py`
- [Compatibility helpers](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/compatibility.py): `src/icalendar/compatibility.py`
- [Calendar enums](https://github.com/pycalendar/icalendar/blob/main/src/icalendar/enums.py): `src/icalendar/enums.py`

### Other components

- **Python caller**

## Connections

- Python caller → Calendar API: uses calendar API
- Calendar API → Component model: manages components
- Python caller → Component model: inspects and modifies
- Component model → iCalendar parser: parses iCalendar (evidence: `src/icalendar/cal/component.py`)
- Component model → xCal properties: parses xCal (evidence: `src/icalendar/cal/component.py`)
- iCalendar parser → Content lines: reads content lines (evidence: `src/icalendar/parser/ical/component.py`)
- iCalendar parser → Parameter parser: uses parameters (evidence: `src/icalendar/parser/ical/component.py`)
- iCalendar parser → Component model: builds components (evidence: `src/icalendar/parser/ical/component.py`)
- Component model → Property factory: uses property types (evidence: `src/icalendar/cal/component.py`)
- xCal properties → xCal parser state: consumes XML elements (evidence: `src/icalendar/parser/xcal/property.py`)
- xCal properties → XML adapter: adapts elements (evidence: `src/icalendar/parser/xcal/property.py`)
- xCal properties → Parameter parser: uses parameters (evidence: `src/icalendar/parser/xcal/property.py`)
- xCal wrapper → xCal properties: wraps properties (evidence: `src/icalendar/parser/xcal/wrapper.py`)
- xCal wrapper → XML adapter: uses adapter (evidence: `src/icalendar/parser/xcal/wrapper.py`)
- Content lines → Parameter parser: parses parameters (evidence: `src/icalendar/parser/content_line.py`)
- Parameter parser → Parameter access: provides parameter values (evidence: `src/icalendar/parser/parameter.py`)
- Property factory → Date-time values: creates typed values
- Property factory → Text values: creates typed values (evidence: `src/icalendar/prop/__init__.py`)
- Date-time values → Timezone proxy: localizes date-times (evidence: `src/icalendar/prop/dt/datetime.py`)
- Timezone proxy → Timezone providers: selects provider (evidence: `src/icalendar/timezone/tzp.py`)
- Timezone proxy → Date-time tools: uses date-time tools (evidence: `src/icalendar/timezone/tzp.py`)
- Component model → Case-insensitive map: uses case-insensitive map (evidence: `src/icalendar/cal/component.py`)
- Component model → Encoding helpers: uses encoding helpers (evidence: `src/icalendar/cal/component.py`)
- Date-time values → Encoding helpers: decodes values (evidence: `src/icalendar/prop/dt/datetime.py`)
- Date-time values → Compatibility helpers: uses compatibility types (evidence: `src/icalendar/prop/dt/datetime.py`)
- Date-time values → Parameter access: uses parameter access (evidence: `src/icalendar/prop/dt/datetime.py`)
- Parameter parser → Case-insensitive map: uses case-insensitive map (evidence: `src/icalendar/parser/parameter.py`)
- Parameter parser → Compatibility helpers: uses compatibility types (evidence: `src/icalendar/parser/parameter.py`)
- Parameter parser → Calendar enums: uses calendar enums (evidence: `src/icalendar/parser/parameter.py`)
