icalendar

Documentation

• Fixed duplicate vInt.min and vInt.max descriptions in the API reference that caused the Read the Docs build to fail.

Removals and deprecations

• Deprecated icalendar.parser.string.foldline as a private function for icalendar version 8. @IoannaGiag (Issue #1011)

• Deprecated icalendar.parser.string.escape_char, icalendar.parser.string.unescape_char, icalendar.parser.string.escape_string, and icalendar.parser.string.unescape_string using the standard deprecate_for_version_8 wrapper as per issue #1405. (Issue #1405)

New features

• Created an ~icalendar.prop.recur.frequency.vFrequency.ical_value property for the ~icalendar.prop.recur.frequency.vFrequency component, mirroring the existing pattern on ~icalendar.prop.recur.weekday.vWeekday. @mvanhorn (Issue #876)

• Created an ~icalendar.prop.geo.vGeo.ical_value property for the ~icalendar.prop.geo.vGeo component. @IoannaGiag (Issue #876)

• Added type hints to component methods. @Priyanshu-pulak (Issue #938)

• Added test coverage for icalendar.compatibility.deprecate_for_version_8. AI disclosure: I used GPT-5 Codex to help draft and refine the test and pull request text. I reviewed the output and validated the change locally. @iccccccccccccc (Issue #1407)

• The Alarm.uid accessor now falls back to vendor-specific UID properties (the existing X-ALARMUID and the newly added X-EVOLUTION-ALARM-UID) when no canonical UID is present, so alarms exported by Evolution/GNOME Calendar expose a usable identifier. single_string_property now accepts an ordered list of fallback keys so further vendor aliases can be added later. AI disclosure: I used GPT-5 Codex (via the Codex CLI) to draft and refine this change and its tests; I reviewed and validated the output locally. @mvanhorn (Issue #1421)

• The rdates and exdates properties are now writable: assigning a list replaces the RDATE/EXDATE values, del (or assigning an empty list or None) clears them, and assigning the value the getter returns round-trips. Prepared with the assistance of an AI coding agent (Anthropic's Claude). @gaoflow (Issue #1442)

Bug fixes

• Strictly validate ~icalendar.prop.dt.datetime.vDatetime values in ~icalendar.prop.dt.datetime.vDatetime.from_ical and reject malformed input. This also improves handling of values with a TZID prefix, per 5545#section-3.3.5, Form #3. @uwezkhan (Issue #1361)

• Preserve an explicit VALUE parameter (for example RDATE;VALUE=PERIOD or TRIGGER;VALUE=DATE-TIME) when converting from jCal. Previously Component.from_jcal dropped the value type, which is encoded in the jCal type field rather than as a parameter. Prepared with the assistance of an AI coding agent (Anthropic's Claude Opus 4). @gaoflow @lcampanella98 (Issue #1426)

• For a newline-free string that the operating system can't use as a file path—for example, one containing an embedded null byte or one that is too long—treat it as calendar data, instead of propagating an OSError from Component.from_ical. Such input now raises a consistent ValueError across platforms. The string-versus-path boundary is now covered by tests. @uwezkhan (Issue #1436)

• Accept the (dt, None) form that rdates/exdates return for a single date when adding RDATE or EXDATE, so event.add("RDATE", (dt, None)) no longer raises TypeError and the value round-trips. Prepared with the assistance of an AI coding agent (Anthropic's Claude Opus 4). @gaoflow @texttheater (Issue #1439)

• Anchored the value validation regular expressions with \Z instead of $ in ~icalendar.prop.recur.weekday.vWeekday, vDuration.from_ical, ~icalendar.prop.dt.time.vTime and ~icalendar.prop.dt.utc_offset.vUTCOffset. $ matches just before a final \n, so a value with a trailing line break was accepted; for vWeekday the newline survived in the str value and was re-emitted into RECUR output. @alhudz

• For iCalendar files that have thousands of bare line breaks, reduce the content line parse time by a quadratic order of magnitude when reading a component with Component.from_ical. @alhudz

• Parse a CATEGORIES value that contains an unescaped colon correctly. TEXT values do not escape :, so a category such as CATEGORIES:CONFIDENTIAL,http://example.com/tag was truncated to a single //example.com/tag because the value boundary was found with the last colon on the line instead of the first one outside the parameters. @alhudz

• Parse and serialize jCal iteratively so that deeply nested components no longer raise an uncaught RecursionError. Component.from_jcal and Component.to_jcal now handle arbitrary nesting depth, matching the iterative iCal parser and serializer. @arshsmith

• Preserve literal percent escapes in parameter values. The parameter parser used %2C/%3A/%3B/%5C as internal markers for backslash-escaped delimiters, so a value that already contained those sequences (e.g. ALTREP="http://x/a%2Cb") was silently decoded to http://x/a,b. The internal transport encoding now escapes % itself, leaving real percent-encoded values untouched. @alhudz

• Raise ~icalendar.error.InvalidCalendar instead of leaking OverflowError when a DURATION value is too large for datetime.timedelta, for example, P999999999999999999W. Parsing a whole calendar now records such a value as an error, like any other invalid property, rather than aborting the parse. @arshsmith

• Reject non-ASCII digits in ~icalendar.prop.recur.month.vMonth (BYMONTH). str.isdigit is True for digits like the Arabic-Indic ١٢, which was silently accepted and normalized to month 12, while characters such as ² cleared the same guard and then leaked a raw int() error. vMonth.from_ical now rejects both. @alhudz

• Reject non-finite FLOAT values in vFloat.from_ical() and vGeo.from_ical(). Inputs such as nan, inf or an overflowing magnitude like 1e999 were silently accepted, producing NaN/Infinity tokens in Component.to_json output that are not valid JSON. @alhudz

• Strictly validate ~icalendar.prop.dt.date.vDate and ~icalendar.prop.dt.time.vTime values in their from_ical methods and reject malformed input, matching the strictness added to ~icalendar.prop.dt.datetime.vDatetime. Trailing data and int() quirks (underscores, whitespace, signs) are no longer silently accepted, per 5545#section-3.3.4 and 5545#section-3.3.12. This change was prepared with AI assistance (Anthropic Claude, Opus model, via Claude Code) used to research the relevant RFC grammar and draft the validation and tests, all reviewed and verified locally. @alhudz

Documentation

• Switch docs/how-to/usage.rst from the deprecated .. code:: pycon directive to .. code-block:: pycon for consistency with the rest of the documentation. @mvanhorn (Issue #626)

• Added type hint for encoding parameter in ~icalendar.parser_tools.data_encode. @cybs-joe (Issue #938)

• Converted docstring of ~icalendar.cal.component.Component.add to Google style. @mvanhorn (Issue #1072)

• Fixed broken links and removed :py prefix in icalendar.cal.calendar.Calendar documentation. @lcampanella98 (Issue #1158)

• Fixed broken link and removed :py prefix in the ~icalendar.parser.property.unescape_backslash docstring. @vincere-mori (Issue #1158)

• Fixed broken documentation links in icalendar.alarms and icalendar.cal.alarm. @lcampanella98 (Issue #1158)

• Fix unqualified cross-references in Event.start and Event.start docstrings. @Esneider1107 (Issue #1158)

• Fixed broken links in icalendar.cal.free_busy documentation by using fully qualified icalendar.cal.component.Component attribute targets. @tsai135 (Issue #1158)

• Qualify ambiguous cross-references and remove remaining :py prefixed roles. @wahajahmed010 (Issue #1158)

• Fixed broken documentation links in icalendar.cal.availability. @lcampanella98 (Issue #1158)

• Replaced the RFC quotation in the docstring for vBoolean with a Pythonic description, including parsing behavior, a conformance reference, and a working example. @tsai135 (Issue #1244)

• Improved the documentation for attr.url_property by converting raw RFC text into a comprehensive Python docstring with usage examples and explicit RFC cross-references. Assisting tool: Gemini 1.5. @samrodri911 (Issue #1244)

• Improved the ~icalendar.cal.component.Component.LAST_MODIFIED docstring to a clearer Pythonic docstring. Assisting tool: Claude Haiku 4.5 @valemm13 (Issue #1244)

• Tidied the auto-generated property docstrings by removing the redundant accepted values sentence and formatting return and error details as Sphinx sections. @mvanhorn (Issue #1259)

• Fix Read the Docs administrative instructions in maintenance documentation by removing the obsolete step to check the default branch and adding a step to manually trigger the "latest" version. @stevepiercy (Issue #1397)

• Clarified that Calendar.new automatically sets not only required, but recommended properties too. @scop (Issue #1459)

• Add how to report security issues. @stevepiercy (Issue #1463)

• Added NixOS installation instructions to the documentation. @MichaelFehdrau0205

• Added instructions to change-log in Contribute documentation for how to avoid a filename conflict when adding a change log entry. @stevepiercy

• Collect only documentation files for doctest. @stevepiercy

• Documented Calendar.from_ical as a direct ~icalendar.cal.calendar.Calendar API member so Sphinx can link to it from the custom components guide. Prepared with AI assistance. @xjn2005

Internal changes

• Added tests for FreeBusy.duration coverage. @kyriakikrimitza (Issue #698)

• Refactored test_error_tolerant_parsing.py to use .ics fixture files. @lcampanella98 (Issue #1081)

• Added .pre-commit-config.yaml configuration and documentation to automatically record AI prompts in commit messages with ai-prompt-auto-commit. @AniruthKarthik (Issue #1320)

• Support keeping a linked issue open in the pull request template when the pull request fixes only a part of the original issue. @stevepiercy (Issue #1394)

• Trigger the creation of a comment with links to Read the Docs of the changed files to review in a pull request preview build. @stevepiercy (Issue #1396)

• Add gh-profiler workflow to help triage AI-generated contributions. @SashankBhamidi (Issue #1484)

• Added validation test for FreeBusy.duration. @kyriakikrimitza

• Remove redundant and deprecated pull request preview feature on Read the Docs. We now use the RTD GitHub app, making this file redundant to pull request preview builds. Additionally the call to the old GitHub Action was deprecated on 2025-07-01, per its README.md. @stevepiercy

Other tasks

• Added type hints to all methods in the module ~icalendar.error. @Priyanshu-pulak (Issue #938)

Bug fixes

• Comparing components with Component.__eq__ is no longer exponential in the subcomponent nesting depth, removing a denial-of-service vector where a deeply nested component could take minutes to compare. See GHSA-cv84-9p8j-fj68. @tidusec

Bug fixes

• Replaced the recursive Component.__repr__ implementation with an iterative stack-based walk so that deeply nested calendars no longer raise RecursionError when formatted via repr(), str(), or f-strings. The output format is unchanged for normally-shaped calendars. @gistrec (Issue #1370)

Documentation

• Update maintenance documentation. Fix the version switcher on "stable" on Read the Docs. @stevepiercy (Issue #1352)

New features

• Created an ~icalendar.prop.dt.period.vPeriod.ical_value property for the ~icalendar.prop.dt.period.vPeriod component. @ZairKSM (Issue #876)

• Created a ~icalendar.prop.recur.weekday.vWeekday.ical_value property for the ~icalendar.prop.recur.weekday.vWeekday component, mirroring the existing pattern on ~icalendar.prop.boolean.vBoolean. @mvanhorn (Issue #1360)

Bug fixes

• Strictly validate BINARY property values in vBinary.from_ical() and reject malformed Base64 input instead of silently accepting invalid characters. @uwezkhan (Issue #1349)

Documentation

• Replace the RFC quotations in the docstrings for Alarm.REPEAT and Alarm.DURATION with Pythonic descriptions, including parameter notes, conformance references, and worked examples. @tmchow (Issue #1244)

• Edited contributor documentation for how to add a change log entry, and maintenance documentation for how to process news fragments. @stevepiercy (Issue #1256)

• Updated release process documentation. @niccokunzmann @stevepiercy @SashankBhamidi (Issue #1293)

Dependency changes

• Added towncrier to development dependencies. @stevepiercy (Issue #1256)

Internal changes

• Switched from manual change log management to towncrier to automate the process. @stevepiercy (Issue #1256)

• Bump PyPy from 3.10 to 3.11 for testing. @stevepiercy (Issue #1383)

Minor changes

• Deprecate icalendar.parser.escape_string and icalendar.parser.unescape_string for icalendar version 8. Use _escape_string and _unescape_string internally. 1011

• Added behavioral tests for ~icalendar.cal.lazy.LazyCalendar covering serialization round-trips, .todos, .journals, forward timezone references, and with_uid() substring false-positives. 1050

• Added edge case tests for ~icalendar.prop.conference.Conference parameter normalization covering string passthrough, empty list filtering, and None omission. 925

• Make icalendar an explicit editable install for clarity. 1268

• Do not run some tests until a pull request is approved. 1246

• Mark skipped CI tasks as skipped instead of running them. 1286

• Created an ~icalendar.prop.boolean.vBoolean.ical_value property for the ~icalendar.prop.boolean.vBoolean component. 876

• Created an ~icalendar.prop.float.vFloat.ical_value property for the ~icalendar.prop.float.vFloat component. 876

• Created an ~icalendar.prop.integer.vInt.ical_value property for the ~icalendar.prop.integer.vInt component. 876

• Created an ~icalendar.prop.binary.vBinary.ical_value property for the ~icalendar.prop.binary.vBinary component. 876

• Put the link check as the last documentation CI task, allowing the documentation build and Vale to run first and fail faster. 1295

• Extended ~icalendar.timezone.tzp.TZP.localize to support localizing both datetime.datetime and datetime.time objects, returning timezone-aware datetime.time objects for the latter. 1142

• Add type hints to tests directory functions. 938

• Update to Contributor Covenant 3.0 Code of Conduct, hosted at https://pycal.org/code-of-conduct/.

New features

• Added ~icalendar.cal.lazy.LazyCalendar for lazy parsing of subcomponents. 158, 1050

• Updated icalendar.prop.dt.time.vTime.from_ical to support parsing time values with TZID parameters, returning timezone-aware datetime.time objects. 1142

• Added subcomponents parameter to Component.new, Event.new, Todo.new, and Availability.new. 1065

• Switch to uv for development. 1102

Bug fixes

• Allow lenient parsing of content lines with optional whitespace around property and parameter delimiters (for example, REFRESH - INTERVAL; VALUE = DURATION:PT48H) when parsing calendars with strict=False. 351

• X-properties with a VALUE parameter are now parsed using the correct type instead of falling back to ~icalendar.prop.unknown.vUnknown. 1238

• Test that the DURATION property catches datetime.timedelta objects without vProperty wrappers. 884

• Fixed ~icalendar.attr.get_end_property to avoid allowing the creating of VEVENT components with negative durations. Only VTODO components are allowed to have negative durations. 999

• GitHub Actions: conditional tests now show as "skipped" instead of "pending". 1264

• Fixed Component.__eq__ method not being commutative when comparing subcomponents. 1224

• Verified that the VALUE parameter of jCal components is used for the type of the component property. 1237

• Fix ~icalendar.parser.string.escape_char handling of bytes input by converting with icalendar.parser_tools.to_unicode before escaping. 1226

• Fixed RecursionError in walk(), property_items(), and to_ical() by using iterative implementations for component traversal and property extraction. 1348

Documentation

• Convert docstring of ~icalendar.param.string_parameter to Google style. 1072, 1316

• Run sphinx-build with -W to turn warnings into errors. 1306

• Added sphinx-llms-txt extension to generate llms.txt and llms-full.txt files for AI/LLM documentation consumption. 1302

• Fixed CI Vale check reporting and resolved Vale errors. 1277

• Include Makefile in documentation workflow path filters so documentation CI runs when Makefile logic changes, and keep Vale failures visible in CI output. 1277

• Document how to install icalendar on Alpine Linux. 1290

• Add documentation for usage of the Sphinx extension sphinx-icalendar. 1268

• Add Repology badge and distribution installation instructions to install documentation. 1119

• Updated references to ~icalendar.prop.uri.vUri and ~icalendar.enums.RELTYPE classes in attr.py. 1158

• Convert docstrings in attr.py and cal/calendar.py to Google Style format. 1072

• Explained import shortcuts in ../explanation/api-design documentation. 1161

• Added tutorial for creating a calendar with events with attendees. 1262

• Added recognition of NLnet Foundation for its funding and Open Collective for donations to the documentation footer. 1214

• Documented vText properties according to 5545#section-3.3.11. 742

• Convert docstrings in icalendar.caselessdict to Google Style format with Parameters, Returns, Raises, and Example sections as appropriate. 1072

• Fix broken docstring for ~icalendar.cal.component.Component.add_component link in ~icalendar.cal.availability.Availability.available. 1158

• Revise AI policy, per NLnet advice. See discussion under pycal.org issue #24.

• Add documentation for how to use uv for development. 1102

• Reorganize Design documentation. 1292

• Improve docstring for categories_property, which renders to HTML in Calendar.categories, Event.categories, Journal.categories, and Todo.categories. 1244

• Fixed Python object cross-references in icalendar.cal.component.Component._infer_value_type. 1158, 1344

Minor changes

• Show colorful required code changes in the CI output to help contributors solve the formatting issues. 1216

• Use ruff 0.15.0 for code formatting in tox.ini. 1215

New features

• Added Event.RECURRENCE_ID, Todo.RECURRENCE_ID, and Journal.RECURRENCE_ID properties, including support in their new() constructors. 1231

Bug fixes

• Fixed ~icalendar.timezone.tzid.tzids_from_tzinfo not recognizing dateutil.tz.win.tzwin objects on Windows. UTC datetimes using dateutil.tz.gettz("UTC") now correctly serialize with the Z suffix instead of TZID=Coordinated Universal Time. 1056

• Fixed Calendar.get_missing_tzids raising KeyError when a VTIMEZONE exists for a timezone not referenced by any event TZID, for example, when added by the x-wr-timezone conversion. 1124

• Fixed Calendar.get_missing_tzids and Calendar.add_missing_timezones generating a spurious VTIMEZONE for UTC. 5545#section-3.2.19 requires UTC datetimes to use the Z suffix; no VTIMEZONE component is needed or permitted. 1124

• Fixed Parameters.update_tzid_from incorrectly setting TZID=UTC on UTC datetimes. 5545#section-3.2.19 requires UTC datetimes to use the Z suffix without a TZID parameter. 1124

• Renamed the public functions escape_char and unescape_char to implicit private methods _escape_char and _unescape_char Fixed regression from 1008 by restoring ~icalendar.parser.string.escape_char and ~icalendar.parser.string.unescape_char as public functions. The public functions ~icalendar.parser.string.escape_char and ~icalendar.parser.string.unescape_char are now deprecated with warnings for external users. 1241

Documentation

• Add icalendar as a local workspace dependency to the docs dependency group in pyproject.toml to fix dependency resolution issues with uv lock during documentation builds. 1253 1254

• Use sphinx-icalendar to add syntax highlighting to iCalendar text

Minor changes

• Show required code changes in the CI output to help contributors solve the formatting issues. 1216

• Use ruff 0.15.0 for code formatting in tox.ini. 1215

New features

• Enabled Calendar.from_ical to read calendars from files. 756

• Added Calendar.journals property to retrieve all journal components. 1230

Documentation

• Removed methods of str, int, and other classes and methods in the Python standard library from the documentation.

Minor changes

• Setting ~cal.calendar.Calendar.calendar_name now also writes X-WR-CALNAME, and setting ~cal.calendar.Calendar.description now also writes X-WR-CALDESC, for improved client compatibility. 918

Bug fixes

• Make typing_extensions a dependency. 1202

Documentation

• Fixed the version switcher on Read the Docs, and documented the process for a major release. 1194

• Added usage examples for reading calendars from files and URL. 756

• Add type hints and convert docstrings to Google Style in cli.py. 938

Minor changes

• Created an ~cal.todo.Todo.example method for the ~cal.todo.Todo component. 743

• Created an ~cal.alarm.Alarm.example method for the ~cal.alarm.Alarm component. 743

• Move property classes from icalendar.prop into their own files with sub-packages icalendar.prop.recur and icalendar.prop.dt. 987

• Move classes and functions in icalendar.parser into their own files. 987

• Clarified custom component (X-* and IANA-registered) parsing behavior through enhanced documentation and comprehensive how-to guide. Custom components are automatically handled by the library with no special configuration required. 432

• Reorganized custom component tests into a dedicated test_custom_components.py file with expanded test coverage for Component.from_ical, Calendar.from_ical, and ~icalendar.cal.component_factory.ComponentFactory usage. 433

• The typing-extensions dependency on Python < 3.13 is now optional, part of the test extra.

• The icalendar.tools.is_pytz_dt return value is now hinted as TypeGuard[datetime], not TypeIs[datetime], since returning False should not allow narrowing it as non-datetime.

• Regroup dependencies in, and remove obsolete ones, from pyproject.toml. 906

• Add type hints to internal helper functions. 938

• Add type hints to prop value classes (vBoolean, vFloat, vUri, vBinary, vInline). 938

• Add type hints to remaining prop value classes (vText, vCalAddress, vCategory, vGeo, vN, vOrg, vAdr, vBroken, vUid, Conference, Image). 938

• Added type hints and overloads to Calendar.from_ical and Component.from_ical to support multiple=True/False return types. 1129

• CI: Print a link to Vale documentation when the spell checker fails.

• Remove bootstrap.py and buildout.cfg files as they are old build configurations. 1171

• Enforce ruff formatting and linting across the entire codebase, with CI check to prevent regressions. 672, 1171, 1172, 1173, 1174, 1175, 1176, 1177, 1178, 1179, 1180, and 1181

• Fix type annotations, typos, and validation logic in prop module: corrected return type hints in parse_jcal_value methods, fixed to_ical() return type in vDDDTypes, updated ClassVar type hint in TypesFactory, removed dead code, fixed "abbrevation" typo in vWeekday, and corrected validation logic in vMonth. 1185

• Rename ~icalendar.prop.vBrokenProperty to ~icalendar.prop.vBroken to match naming convention. ~icalendar.prop.vBroken now stores the actual exception object in parse_error instead of a string, and raises ~icalendar.error.BrokenCalendarProperty when accessing attributes like .dt that the expected type would have. 1087

Breaking changes

• Drop support for Python 3.8 and 3.9. 977

• DURATION_REGEX moved from icalendar.prop to icalendar.prop.dt.duration. 987

• WEEKDAY_RULE moved from icalendar.prop to icalendar.prop.recur.weekday. 987

• Removed tzid_from_dt and tzid_from_tzinfo from icalendar.prop as they exist in icalendar.timezone. 987

• Component.decoded now returns a string instead of bytes for text properties.

• Remove constants FOLD, NAME, NEWLINE, QUNSAFE_CHAR, QUOTABLE, UFOLD, and UNSAFE_CHAR from icalendar.parser's export. 987

New features

• Added recursive parameter to Component.copy to control copying of subcomponents and properties. 899

• Event components now have error-tolerant property parsing. Properties with parsing errors fall back to ~icalendar.prop.vBroken, preserving the raw value and allowing access to other valid properties. Errors are recorded in component.errors. Partially addresses 158

• Added ~icalendar.prop.AdrFields and ~icalendar.prop.NFields named tuples for structured access to vCard ADR and N property fields. The fields attribute and from_ical() return value of ~icalendar.prop.vAdr and ~icalendar.prop.vN now return these typed named tuples, enabling access like adr.fields.street and n.fields.family. Since named tuples are tuple subclasses, existing code using tuple indexing or unpacking remains compatible. Added name and units properties to ~icalendar.prop.vOrg for convenient access to the organization name and organizational units. Added ical_value property to all three classes. 1060

• Added with_uid method to Component to filter subcomponents by UID. 950

• Enforce linting of code with Ruff in CI. 672

Bug fixes

• Fixed Calendar.new to automatically generate a UID when not provided, matching the documented behavior. Previously, the documentation stated that uid would be set to a new uuid.uuid4 if None, but the implementation did not generate it. 1066

• Fixed import failure in Pyodide/WebAssembly environments by using lazy initialization for timezone data in the zoneinfo provider. The library can now be imported in environments without timezone data (for example, Cloudflare Workers, PyScript, and JupyterLite). 1073

• Fixed CaselessDict.__eq__ to return NotImplemented when comparing with non-dict types instead of raising AttributeError. 1016

• Fixed decoding of categories. 279

• Link timedelta to datetime.timedelta in the Python standard library documentation. 951

• Fix round-trip parsing of ~icalendar.prop.vCategory (CATEGORIES property) when category values contain commas. Categories like 'Meeting, John' now correctly survive round trips between Component.to_ical and Component.from_ical instead of being split into multiple categories. Added ~icalendar.parser.property.split_on_unescaped_comma helper function. 127

• Fixed semicolon escaping in vCard structured properties (ADR, N, ORG). Semicolons are now correctly treated as field separators per 6350, not escaped as in iCalendar TEXT values. Added ~icalendar.parser.property.split_on_unescaped_comma helper function and ~icalendar.prop.adr.vAdr, ~icalendar.prop.n.vN, ~icalendar.prop.org.vOrg property types. 137

• Fix Image.from_property_value to raise TypeError instead of AttributeError when value.params isn't valid (most notably, isn't dict-like). 909

Documentation

• Improved docstrings and formatting for the ~icalendar.alarms.AlarmTime class. 1072

• Added how-to guide for handling parsing errors with ~icalendar.prop.vBroken and the component.errors attribute. 1085

• Updated 11 function docstrings in icalendar.parser to follow the Google Style guide, improving API documentation clarity and consistency. 1072

• Applied Google-style docstrings to icalendar.tools utility functions with Args, Returns, and Example sections. 1072

• Simplify contributors and add supporters in credits. 1035

• Add a section in the change log for Documentation. 1043

• Fixed multiple more than one target found for cross-reference warnings, and stopped using sphinx.ext.autosectionlabel, in documentation. 952

• Add funding.json manifest for funding information. 1047

• Resolved Cannot resolve forward reference in type annotations warning in documentation. Added SPHINX_APIDOC_OPTIONS to make apidoc command, excluding __all__ items from being duplicated in the documentation, and rebuilt the API documentation source files. 952

• Document how to create and read attendee information in events. 130

• Add usage examples. 443

• Improve documentation contribution guide by adding chapters for small edits, builds and checks, and a style guide. Added details for Vale usage, Diátaxis framework, narrative and API documentation, and fixing all spelling errors. 991

• Document dictionary and property accessors. 124

• Moved content from the README into documentation to reduce maintenance and point to the authoritative source of information. 1006

• Added "Code conventions" section to the Development contributing guide. 1004

• Use Google style docstrings in ~icalendar.parser_tools 1017

• Document compatibility of icalendar with RFCs. 1147

• Added Upgrade guide. 997

• Fixed links in jCal usage documentation.

• Enable sphinx-issues extension. 1091

• Replaced "Arguments" and "Args" with "Parameters". 1076

• Added documentation of how to set up a development environment with git. 906

• Documented how to install and use pre-commit. 996

• Added a new rule to our docstring style guide to escape docstrings, and added a new section for type hints in the code conventions section. 1080

• Documented __init__ methods. 1079

• Moved "Edit this page" link to above the page table of contents. 1106

• Added Good First Issue link and fixed Up For Grabs link in Contribute guide. 1095

• Updated CONTRIBUTING.rst to explicitly state not to use Args sections in docstrings. 1076

• Document vInt.__new__ method parameters in class docstring with 5545 examples. 1118

• Improved make vale command to provide guidance on failure or success. 1137

• Add sphinx_copybutton configuration to exclude line numbers, prompts, and console output when copying code blocks.

• Change Sphinx configuration to convert -- to en dash -, --- to em dash —, and ... to ellipsis …, but doesn't transform quote marks as they should be preserved. This restores cleaner and consistent rendering of docstrings in the API Reference. See smartquotes_action.

• Fix incorrect return type annotation in Component.from_ical. 1141

• Fixed broken links in docs/how-to/usage.rst documentation. Part of 1158

• Enhanced the first-time contributors section, in hopes that fewer contributors ask permission before starting work. 1165

• Changed Sphinx configuration to inherit from CaselessDict, displaying all of its class members in the in-page navigation. Fixed broken cross-component links in Availability.new(). 994

• Configured Sphinx to append the docstring from the __init__ method into its class docstring. 1156

Minor changes

Created an example() method for the Todo component. #743

Created an example() method for the Alarm component. #743

Move property classes from icalendar.prop into their own files with sub-packages icalendar.prop.recur and icalendar.prop.dt . #987

Move classes and functions in icalendar.parser into their own files. #987

Clarified custom component (X-* and IANA-registered) parsing behavior through enhanced documentation and comprehensive how-to guide. Custom components are automatically handled by the library with no special configuration required. #432

Reorganized custom component tests into a dedicated test_custom_components.py file with expanded test coverage for Component.from_ical , Calendar.from_ical , and ComponentFactory usage. #433

The typing-extensions dependency on Python < 3.13 is now optional, part of the test extra.

The icalendar.tools.is_pytz_dt() return value is now hinted as TypeGuard[datetime] , not TypeIs[datetime] , since returning False should not allow narrowing it as non-datetime.

Regroup dependencies in, and remove obsolete ones, from pyproject.toml . #906

Add type hints to internal helper functions. #938

Add type hints to prop value classes (vBoolean, vFloat, vUri, vBinary, vInline). #938

Add type hints to remaining prop value classes (vText, vCalAddress, vCategory, vGeo, vN, vOrg, vAdr, vBroken, vUid, Conference, Image). #938

Added type hints and overloads to Calendar.from_ical and Component.from_ical to support multiple=True/False return types. #1129

CI: Print a link to Vale documentation when the spell checker fails.

Remove bootstrap.py and buildout.cfg files as they are old build configurations. #1171

Enforce ruff formatting and linting across the entire codebase, with CI check to prevent regressions. #672 , #1171 , #1172 , #1173 , #1174 , #1175 , #1176 , #1177 , #1178 , #1179 , #1180 , and #1181

Fix type annotations, typos, and validation logic in prop module: corrected return type hints in parse_jcal_value methods, fixed to_ical() return type in vDDDTypes, updated ClassVar type hint in TypesFactory, removed dead code, fixed "abbrevation" typo in vWeekday, and corrected validation logic in vMonth. #1185

Rename vBrokenProperty to vBroken to match naming convention. vBroken now stores the actual exception object in parse_error instead of a string, and raises BrokenCalendarProperty when accessing attributes like .dt that the expected type would have. #1087

Breaking changes

Drop support for Python 3.8 and 3.9. #977

DURATION_REGEX moved from icalendar.prop to icalendar.prop.dt.duration . #987

WEEKDAY_RULE moved from icalendar.prop to icalendar.prop.recur.weekday . #987

Removed tzid_from_dt and tzid_from_tzinfo from icalendar.prop as they exist in icalendar.timezone . #987

Component.decoded() now returns a string instead of bytes for text properties.

Remove constants FOLD , NAME , NEWLINE , QUNSAFE_CHAR , QUOTABLE , UFOLD , and UNSAFE_CHAR from icalendar.parser 's export. #987

New features

Added recursive parameter to Component.copy() to control copying of subcomponents and properties. #899

Event components now have error-tolerant property parsing. Properties with parsing errors fall back to vBroken , preserving the raw value and allowing access to other valid properties. Errors are recorded in component.errors . Partially addresses #158

Added AdrFields and NFields named tuples for structured access to vCard ADR and N property fields. The fields attribute and from_ical() return value of vAdr and vN now return these typed named tuples, enabling access like adr.fields.street and n.fields.family . Since named tuples are tuple subclasses, existing code using tuple indexing or unpacking remains compatible. Added name and units properties to vOrg for convenient access to the organization name and organizational units. Added ical_value property to all three classes. #1060

Added with_uid method to Component to filter subcomponents by UID. #950

Enforce linting of code with Ruff in CI. #672

Bug fixes

Fixed Calendar.new to automatically generate a UID when not provided, matching the documented behavior. Previously, the documentation stated that uid would be set to a new uuid.uuid4() if None , but the implementation did not generate it. #1066

Fixed import failure in Pyodide/WebAssembly environments by using lazy initialization for timezone data in the zoneinfo provider. The library can now be imported in environments without timezone data (e.g., Cloudflare Workers, PyScript, JupyterLite). #1073

Fixed icalendar.caselessdict.CaselessDict.eq() to return NotImplemented when comparing with non-dict types instead of raising AttributeError . #1016

Fixed decoding of categories. #279

Link timedelta to datetime.timedelta in the Python standard library documentation. #951

Fix round-trip parsing of vCategory (CATEGORIES property) when category values contain commas. Categories like 'Meeting, John' now correctly survive round trips between Component.to_ical and Component.from_ical instead of being split into multiple categories. Added split_on_unescaped_comma() helper function. #127

Fixed semicolon escaping in vCard structured properties (ADR, N, ORG). Semicolons are now correctly treated as field separators per RFC 6350 , not escaped as in iCalendar TEXT values. Added split_on_unescaped_semicolon() helper function and vAdr , vN , vOrg property types. #137

Fix Image.from_property_value to raise TypeError instead of AttributeError when value.params isn't valid (most notably, isn't dict-like). #909

Documentation

Improved docstrings and formatting for the AlarmTime class. #1072

Added how-to guide for handling parsing errors with vBroken and the component.errors attribute. #1085

Updated 11 function docstrings in icalendar.parser to follow the Google Style guide, improving API documentation clarity and consistency. #1072

Applied Google-style docstrings to icalendar.tools utility functions with Args, Returns, and Example sections. #1072

Simplify contributors and add supporters in credits. #1035

Add a section in the change log for Documentation. #1043

Fixed multiple more than one target found for cross-reference warnings, and stopped using sphinx.ext.autosectionlabel , in documentation. #952

Add funding.json manifest for funding information. #1047

Resolved Cannot resolve forward reference in type annotations warning in documentation. Added SPHINX_APIDOC_OPTIONS to make apidoc command, excluding all items from being duplicated in the documentation, and rebuilt the API documentation source files. #952

Document how to create and read attendee information in events. #130

Add usage examples. #443

Improve documentation contribution guide by adding chapters for small edits, builds and checks, and a style guide. Added details for Vale usage, Diátaxis framework, narrative and API documentation, and fixing all spelling errors. #991

Document dictionary and property accessors. #124

Moved content from the README into documentation to reduce maintenance and point to the authoritative source of information. #1006

Added "Code conventions" section to the Development contributing guide. #1004

Use Google style docstrings in parser_tools #1017

Document compatibility of icalendar with RFCs. #1147

Added Upgrade guide. #997

Fixed links in jCal usage documentation.

Enable sphinx-issues extension. #1091

Replaced "Arguments" and "Args" with "Parameters". #1076

Added documentation of how to set up a development environment with git. #906

Documented how to install and use pre-commit. #996

Added a new rule to our docstring style guide to escape docstrings, and added a new section for type hints in the code conventions section. #1080

Documented init methods. #1079

Moved "Edit this page" link to above the page table of contents. #1106

Added Good First Issue link and fixed Up For Grabs link in Contribute guide. #1095

Updated CONTRIBUTING.rst to explicitly state not to use Args sections in docstrings. #1076

Document vInt.new method parameters in class docstring with RFC 5545 examples. #1118

Improved make vale command to provide guidance on failure or success. #1137

Add sphinx_copybutton configuration to exclude line numbers, prompts, and console output when copying code blocks.

Change Sphinx configuration to convert -- to en dash - , --- to em dash — , and ... to ellipsis … , but doesn't transform quote marks as they should be preserved. This restores cleaner and consistent rendering of docstrings in the API Reference . See smartquotes_action .

Fix incorrect return type annotation in Component.from_ical . #1141

Fixed broken links in docs/how-to/usage.rst documentation. Part of #1158

Enhanced the first-time contributors section, in hopes that fewer contributors ask permission before starting work. #1165

Changed Sphinx configuration to inherit from CaselessDict , displaying all of its class members in the in-page navigation. Fixed broken cross-component links in Availability.new() . #994

Configured Sphinx to append the docstring from the init method into its class docstring. #1156

Minor changes

• Add static [project.urls] to pyproject.toml for GitHub dependency graph compatibility. 1035

• Created an ~cal.todo.Todo.example method for the ~cal.todo.Todo component. 743

• Add type hints to icalendar.caselessdict file. 938

• For releases, added a step to update the version switcher for documentation.

New features

• Added contributor list format and sorting instructions.

Bug fixes

• Fix double-unescaping in vText.from_ical and vCategory.from_ical by removing unescape_char(). 1008

Minor changes

• Convert changelog section labels to reStructuredText subheadings for improved Read the Docs navigation. 982

• Move sections in Table of Content of Reference guide.

• Improve icalendar.prop.vDatetime documentation. 946

• CLI now writes output files using UTF-8 explicitly instead of relying on the system default. 1005

New features

• Add compatibility to 9253:

  • Add new property types ~icalendar.prop.uid.vUid and ~icalendar.prop.xml_reference.vXmlReference

  • Add properties to all components: Component.concepts, Component.links, Component.refids, Component.related_to

  • Add new values to ~icalendar.enums.RELTYPE

  • Add LABEL, GAP, and VALUE parameters to property values affected by 9253

• Allow setting default values in Parameters

• Allow None as an argument to Parameters

• Add ical_value to several property values. 876

• Add PyData Theme version switcher to documentation. 825

• Test compatibility with Python 3.14. 973

• Added documentation of Vale usage for icalender documentation style guide. 815

• Added funding link to pyproject.toml. 800

• Added documentation of docstring format. 747

• Add TypeAlias icalendar.VPROPERTY as a type for all properties.

• Allow access to icalendar.TypesFactory via icalendar.TypesFactory.instance

• Classes in icalendar.prop can all be initialized with parameters now.

• Allow passing icalendar.vDDDTypes as arguments to icalendar.vDDDLists

• Add support for datetime.timezone identification.

• Add tzid.is_utc to check if a timezone is UTC.

• Add support for JCal parsing and serialization. 978

  • Add icalendar.JCalParsingError exception for jCal parsing.

  • Add icalendar.Parameters.tzid and icalendar.Parameters.is_utc for timezone handling.

  • Add icalendar.vUnknown which is the default now for unknown properties and the same as icalendar.vText

  • Add ComponentFactory.get_component_class that also creates a new component class when it does not exist.

  • Add ComponentFactory.add_component_class to have a unified interface to add component classes.

  • Add Component.to_json, Component.to_jcal, and Component.from_jcal methods so all components can be serialized and parsed.

  • Classes in icalendar.prop receive the following updates:

    • Add to_jcal and from_jcal for serialization.

    • Add default_value class attribute for the default VALUE parameter.

    • Add VALUE parameter property.

    • Add examples() class method that returns examples for testing.

• Added documentation of how to fuzz icalendar. 905

• Added first-time contributors section to Contributing. 934

• Revised check of which files trigger a documentation build on Read the Docs. 848

• Created a separate path to contribute to documentation. 929

• Added a code of conduct. 907

• Added redirects of moved files and 404 not found page to catch any other obsolete URLs. 959

• Added artificial intelligence (AI) policy. 933

Bug fixes

• Correct name of AVAILABLE component.

• Fix ical serialization of icalendar.vTime

• Make sure a component's conferences property adds VALUE=URI if the conference is created as a URI.

• Fix CLI deprecated argparse.FileType usage and remove PendingDeprecationWarning. 1005.

Minor changes

• Split up cal.py into different files as sub-package.

• Format more source code with ruff.

• Exclude type checking block from test coverage.

• Add private icalendar.compatibility module to merge functionality for older Python versions into one place.

• Add type annotation to from_ical().

• Fix enum documentation.

• DTSTAMP, LAST_MODIFIED, and CREATED can now be set to None to delete the value.

• Enhanced Calendar.new() to support organization and language parameters for automatic PRODID generation.

• Added duration setter to Event class for more intuitive event creation.

• Added validate() method to Calendar class for explicit validation of required properties and components.

• Add improved setters for start, duration, and end properties with explicit locking mechanisms to provide more flexible property manipulation while maintaining RFC 5545 compliance. The implementation includes comprehensive test coverage to ensure proper behavior and backward compatibility.

• Add new() method to vCalAddress class for consistent API usage. The method supports all RFC 5545 parameters including CN, CUTYPE, DELEGATED-FROM, DELEGATED-TO, DIR, LANGUAGE, PARTSTAT, ROLE, RSVP, and SENT-BY, with automatic mailto: prefix handling. See 870.

• Refactor set_duration methods in Event and Todo classes to eliminate code duplication by extracting common logic into shared set_duration_with_locking() function in icalendar.attr. See 886.

• Consolidate duplicate logic patterns between Event and Todo classes by extracting shared functions in icalendar.attr for property setters, validation logic, and property access. This eliminates approximately 150 lines of duplicate code while maintaining 100% backward compatibility and RFC 5545 compliance. See 891.

• Accept and ignore non-standard empty RDATE fields when parsing ICS files.

• Improve contributing documentation by adding a change log requirement, adding a pull request template, adding clear CI enforcement warnings, and updating README.rst. See 890.

• Make coverage submission optional for CI.

• Bump actions/setup-python version from 5 to 6 for CI.

• Add comment explaining tzdata dependency purpose to prevent confusion. See 900.

• Fix duplicate blank issue template by adding config.yml to disable GitHub's default blank option. See 777.

• Add PEP 561 py.typed marker to enable type checking support. The package now distributes inline type annotations for mypy and other type checkers. See 395.

• Bump github/codeql-action from 3 to 4 in CI fuzzing workflow.

• Add docstring for vDatetime. See 742.

• Update LICENSE file heading formatting.

• Document icalendar.version module.

• Use CONTRIBUTING.md in favour of .rst file.

• Add type hints to icalendar.tools module.

• Fix more examples link failed in README.md by renewing its link. See 958.

• Fix Contributing, Changelog, License links failed in README.md by renewing its link. See 959.

• Fix more examples link in README.md. See 958.

• Add CODEOWNERS file for automatic pull request review assignment. See 945.

Breaking changes

• Correctly throw a TypeError for wrong types during property creation where a ValueError was thrown before.

• Move types_factory into Component.types_factory

• Move components_factory into Component.get_component_class

• Move icalendar.cal.IncompleteComponent error into icalendar.error.

• Remove icalendar.UIDGenerator. Use Python's built-in uuid library instead.

New features

• Add new() to icalendar.Calendar to set required attributes. See 569.

• Add new() to Alarm, Event, Todo, FreeBusy, Component, and Journal components. See 843.

• Add value to Parameters to access the VALUE parameter.

• Add Availability and Available components from 7953. See 654 and 864.

• Add stamp, last_modified, created, CREATED, busy_type, class, comments, contacts, location, organizer, priority, and url properties to components that use them.

• Add availabilities attribtue to Calendar.

• Add status, transparency, and attendees properties. See 841.

• Add uid property that is '' by default and set automatically with new(). See 315.

• Make icalendar compatible with RFC 7986.

• Add url, source, refresh_interval, conferences, and images properties to components.

• Add td property to vDDDTypes to make it compatible with timedelta value types.

• Add documentation for how to install icalendar on Fedora. See 704.

• Add documentation linkchecker to make and CI configuration. See 854.

• Add support for Vale as spell and style checker.

• For make livehtml watch all files in src/icalendar, but ignore .typed and contents of the tests and fuzzing directories. See 931.

• Restructure documentation, following Diátaxis framework. See 820 which included the following tasks.

  • Start building API Reference documentation.

  • Add Vale with Microsoft Writing Guide style checker.

  • Add Makefile to automate all documentation builds with a single command for each.

  • Write documentation of how to build documentation.

  • Move "History" into "Credits".

  • Add a Glossary of terms.

  • Add version module to API reference.

  • Exclude private Python methods and test modules from the API reference.

  • Fix display of credits to use reStructuredText.

  • Fix the documentation version display.

  • Show older versions of documentation on Read the Docs.

  • Fix the PyPI icon.

  • Add a Security Policy.

  • Consolidate Contributing files into the how-to Contributing guide.

  • Move the change log into the Reference guide.

  • Remove all rights reserved from the License file and remove from documentation, leaving it in the repository root.

  • Move Maintenance into the Contribute guide.

  • Move icalendar contributors into the Contribute guide.

  • Merge about the project into Credits.

  • Split api.rst into separate modules.

  • Move "icalendar utility" into a how-to guide for command line interface.

  • Move "icalendar package" into a how-to usage guide and API reference guide.

  • Split installation into how-to guides for usage and contributing.

  • Redesigned home page to reflect the new structure and point readers to the proper location.

  • Fix various Sphinx build warnings and errors.

  • Use text for lexer of ical files.

  • Update README.rst to align with new documentation structure.

  • Add documentation builds to continuous integration.

  • Review pull requests that involve source docstrings, continuous integration, or documentation, and provide suggestions and corrections.

• Add spell checking to documentation. See 853.

• Add link check to docs test. See 854.

• Document installation of icalendar on Fedora. See 704.

• Miscellaneous documentation follow-up fixes. See 919.

Bug fixes

• Fix Todo.end to return start for date-only DTSTART (not start + 1 day). Events keep existing behavior. See 898.

• Fix AssertionError when converting VTIMEZONE components with only DAYLIGHT subcomponent (no STANDARD) to pytz timezones. The code now handles cases where a timezone definition contains only DST transitions by calculating the DST offset from TZOFFSETFROM and TZOFFSETTO. Test case contributed by @niccokunzmann in 379. See 321.

• Normalize Conference parameter lists (FEATURE/LABEL/LANGUAGE) to comma-separated values. See 908.

• Fix read from stdin issue - See 821.

• Fix invalid calendar: Parsing a date with TZID results in a datetime to not loose the timezone. See 187.

• Fix timezone placement in add_missing_timezones(): VTIMEZONE components now appear before VEVENT and other components that reference them. See 844.

• Fixed Todo.duration and Event.duration to return DURATION property when set, even without DTSTART. See 867.

• Fix VALUE parameter handling: datetime.date objects now correctly set VALUE=DATE parameter when added to properties like EXDATE, RDATE, and DTSTART. The VALUE parameter is also properly used when parsing iCalendar data. See 349.

• Fix URL-encoded characters being incorrectly unescaped during content line parsing. The parser now properly handles backslash escaping and double-quoted sections without corrupting URL-encoded values like %3A (colon) in DESCRIPTION fields. Added unescape_backslash() function to separate 5545 backslash escaping from URL encoding. Optimized implementation using regex for single-pass processing. Added type hints to Contentline.parts() method and comprehensive unit tests. See 355.

• make livehtml now reloads with code changes. See 931.

• Added tests for tools, vFloat, vBinary, vGeo, and vTodo to improve unit test coverage. 698

Minor changes

• Add PyData Theme version switcher to documentation. See 825.

Bug fixes

• Remove forced quoting from parameters with space and single quote. See 836.

Minor changes

• Deprecate icalendar.UIDGenerator. See 816.

New features

• Add the uid property to Alarm, Event, Calendar, Todo, and Journal components. See 740.

Bug fixes

• Fix component equality where timezones differ for the datetimes but the times are actually equal. See 828.

• Test that we can add an RRULE as a string. See 301.

• Test that we support dateutil timezones as outlined in 336.

• Build documentation on Read the Docs with the version identifier. See 826.

Minor changes

• Use ruff to format the source code.

• Update project metadata to use License-Expression.

• Use tzp.localize(dt, None) to remove the timezone from a datetime.

• Remove the HTML documentation when building with tox to force rebuild.

• Switch to PyData Sphinx Theme for documentation. See 803.

New features

• Add getters rrules, rdates, and exdates for unified and simple access to these properties. See `Discussion 662`_.

• Add attributes to the calendar for properties NAME, DESCRIPTION, and COLOR. See 655.

• Add a color attribute to Event, Todo, and Journal components. See 655.

• Add sequence attribute to Event, Todo, and Journal components. See 802.

• Add categories attribute to Calendar, Event, Todo, and Journal components. See 655.

• Add compatibility to 6868. See 652.

• Add freebusy property to the Calendar to get this type of subcomponents easier.

• Add parameters from 5545 to properties ALTREP, CN, CUTYPE, DELEGATED_FROM, DELEGATED_TO, DIR, FBTYPE, LANGUAGE, MEMBER, PARTSTAT, RANGE, RELATED, ROLE, RSVP, SENT_BY, TZID, and RELTYPE. See 798.

• New properties from 7986 can occur multiple times in VCALENDAR. See 808.

Bug fixes

• Fix STANDARD and DAYLIGHT components that have a date as DTSTART. See 218

• Move import at the end of icalendar.parser into a function to mitigate import errors, see 781.

• ALTREP, DELEGATED-FROM, DELEGATED-TO, DIR, MEMBER, and SENT-BY require double quotes. These are now always added.

• Classify CATEGORIES as multiple in VEVENT. See 808.

Bug fixes

• Fix to permit TZID forward references to VTIMEZONEs

• Stabelize timezone id lookup, see 780.

Minor changes

• Add funding link to Tidelift.

• Link to related package.

• Shorten first example in documentation.

• Add name and email properties to vCalAddress.

• Add type hint for property params in icalendar.prop.

• Set default value for params as params={} in mulitple constructors in icalendar.prop to improve usability.

• Improve object initialization performance in icalendar.prop.

• Add type hint for params in multiple constructors in icalendar.prop.

Bug fixes

• Restrict timezones tested, see 763

Minor changes

• Add a weekday attribute to icalendar.prop.vWeekday components. See 749.

• Document icalendar.prop.vRecur property. See 758.

• Print failure of doctest to aid debugging.

• Improve documentation of icalendar.prop.vGeo

• Fix tests, improve code readability, fix typing. See 766 and 765.

Breaking changes

• The relative attribute of vWeekday components has the correct sign now. See 749.

New features

• Add Security Policy

• Python types in documentation now link to their documentation pages using intersphinx.

Minor changes

• Add end, start, duration, DTSTART, DUE, and DURATION attributes to Todo components. See `Discussion 662`_.

• Add DTSTART, TZOFFSETTO and TZOFFSETFROM properties to TimezoneStandard and TimezoneDaylight. See `Discussion 662`_.

• Format test code with Ruff. See 672.

• Document the Debian package. See 701.

• Document vDatetime.from_ical

• Allow passing a datetime.date to TZP.localize_utc and TZP.localize methods.

• Document component classes with description from 5545.

• Merge "File Structure" and "Overview" sections in the docs. See 626.

• Update code blocks in usage.rst with the correct lexer.

• Tidy up the docstring for icalendar.prop.vPeriod.

• Improve typing and fix typing issues

New features

• Add VALARM properties for 9074. See 657

• Test compatibility with Python 3.13

• Add Timezone.from_tzinfo() and Timezone.from_tzid() to create a Timezone component from a datetime.tzinfo timezone. See 722.

• Add icalendar.prop.tzid_from_tzinfo.

• Add icalendar.alarms module to calculate alarm times. See 716.

• Add Event.alarms and Todo.alarms to access alarm calculation.

• Add Component.DTSTAMP and Component.LAST_MODIFIED properties for datetime in UTC.

• Add Component.is_thunderbird() to check if the component uses custom properties by Thunderbird.

• Add X_MOZ_SNOOZE_TIME and X_MOZ_LASTACK properties to Event and Todo.

• Add Alarm.ACKNOWLEDGED, Alarm.TRIGGER, Alarm.REPEAT, and Alarm.DURATION properties as well as Alarm.triggers to calculate alarm triggers.

• Add __doc__ string documentation for vDate, vBoolean, vCalAddress, vDuration, vFloat, vGeo, vInt, vPeriod, vTime, vUTCOffset and vUri. See 742.

• Add DTSTART, TZOFFSETTO, and TZOFFSETFROM to TimezoneStandard and TimezoneDaylight

• Use example methods of components without arguments.

• Add events, timezones, and todos property to Calendar for nicer access.

• To calculate which timezones are in use and add them to the Calendar when needed these methods are added: get_used_tzids, get_missing_tzids, and add_missing_timezones().

• Identify the TZID of more timezones from dateutil.

• Identify totally unknown timezones using a UTC offset lookup tree generated in icalendar.timezone.equivalent_timezone_ids and stored in icalendar.timezone.equivalent_timezone_ids.

• Add icalendar.timezone.tzid to identify a timezone's TZID.

Bug fixes

• Add icalendar.timezone to the documentation.

New features

• Added end, start, duration, DTSTART, DUE, and DURATION attributes to Event components. See Discussion 662.

• Added end, start, duration, and DTSTART attributes to Journal components. See Discussion 662.

Bug fixes

• Fix a few __all__ variables.

• Added missing docs folder to distribution packages. See 712.

Minor changes

• Add __all__ variable to each modules in icalendar package

• Improve test coverage.

• Adapt test_with_doctest.py to correctly run on Windows.

• Measure branch coverage when running tests.

• Export Component base class for typing

New features

• Use pyproject.toml file instead of setup.py

Bug fixes

• Fix link to stable release of tox in documentation.

• Fix a bad bytes replace in unescape_char.

• Handle ValueError in vBinary.from_ical.

• Ignore the BOM character in incorrectly encoded ics files.

Minor changes

• Test that all code works with both pytz and zoneinfo.

• Add message to GitHub release, pointing to the changelog

• Make coverage report submission optional for pull requests

• Parallelize coverage

• Rename master branch to main, see Issue

• Update docs/usage.rst to use zoneinfo instead of pytz.

• Added missing public classes and functions to API documentation.

• Improved namespace management in the icalendar directory.

• Add Python version badge and badge for test coverage

• Remove 4.x badge

• Update list of tox environments

• Use Coveralls' GitHub Action

• Check distribution in CI

Breaking changes

• Use zoneinfo for icalendar objects created from strings, see 609.

  This is an tested extension of the functionality, not a restriction: If you create icalendar objects with pytz timezones in your code, icalendar will continue to work in the same way. Your code is not affected.

  zoneinfo will be used for those objects that icalendar creates itself. This happens for example when parsing an .ics file, strings or bytes with from_ical().

  If you rely on icalendar providing timezones from pytz, you can add one line to your code to get the behavior of versions below 6:

  import icalendar
  icalendar.use_pytz()

• Replaced pkg_resources.get_distribution with importlib.metadata in docs/conf.py to allow building docs on Python 3.12.

• Remove is_broken property. Use errors instead to check if a component had suppressed parsing errors. See 424.

• Remove untested and broken LocalTimezone and FixedOffset tzinfo sub-classes, see 67

• Remove Python 3.7 as compatible. icalendar is compatible with Python versions 3.8 - 3.12, and PyPy3.

• Remove pytz as a dependency of icalendar. If you require pytz, add it to your dependency list or install it additionally with:

  pip install icalendar==6.* pytz

New features

• Check code quality with Ruff, optional report

• Test compatibility with Python 3.12

• Add function icalendar.use_pytz().

• Allows selecting components with walk(select=func) where func takes a component and returns True or False.

• Add compatibility to 7529, adding vMonth and vSkip

• Add sphinx-autobuild for livehtml Makefile target.

• Add pull request preview on Read the Docs, building only on changes to documentation-related files.

• Add link to pull request preview builds in the pull request description only when there are changes to documentation-related files.

• Add documentation of live HTML preview of documentation and clean up of install.rst.

• Add sphinx-copybutton to allow copying code blocks with a single click of a button.

Bug fixes

• Change documentation to represent compatibility with Python 3.8 - 3.12, and PyPy3.

• Rename RFC 2445 to RFC 5545, see Issue 278