icalendar

The icalendar project uses a tiered maintenance structure consisting of Maintainers, Collaborators, and Code Owners to manage code quality, releases, and security.

Maintainers

Maintainers hold full administrative permissions across the project's ecosystem, including:

• GitHub: Admin access to the repository.
• PyPI: Maintainer or Owner access (requires 2FA).
• Read the Docs: Maintainer access.
• GitHub Workflows: Environments/Configure PyPI access to allow releases from tags.
• Code of Conduct: Owner or Manager access to the icalendar-coc@googlegroups.com Google Group.
• OSS Fuzz: Registered access to the issue tracker.
• Metadata: Must be listed in the maintainers section of pyproject.toml.

Collaborators

Collaborators have write access to the repository. Their responsibilities include:

• Merging pull requests (note: you cannot merge your own PRs).
• Initiating new releases.
• Becoming a Code Owner.

Code Owners

A Code Owner is a collaborator or maintainer responsible for specific parts of the codebase. When a pull request modifies code in their domain, they are automatically requested for review. Ownership is defined in the .github/CODEOWNERS file.

Properties that fail to parse are converted into vBroken instances. This allows you to preserve the raw value for inspection or round-trip serialization. You can identify a broken property using isinstance(property, vBroken).

vBroken instances provide the following metadata:

• property_name: The name of the property (e.g., 'DTSTART').
• expected_type: The type the parser expected.
• parse_error: The original Exception that occurred during parsing.

>>> from icalendar import Calendar
>>> from icalendar.prop import vBroken
>>> ical_str = b"""BEGIN:VCALENDAR\n... VERSION:2.0\n... PRODID:test\n... BEGIN:VEVENT\n... UID:test-123\n... DTSTART:INVALID-DATE\n... SUMMARY:Meeting\n... END:VEVENT\n... END:VCALENDAR"""
>>> cal = Calendar.from_ical(ical_str)
>>> event = cal.walk("VEVENT")[0]
>>> dtstart = event["DTSTART"]
>>> isinstance(dtstart, vBroken)
True
>>> str(dtstart)
'INVALID-DATE'
>>> dtstart.property_name
'DTSTART'
>>> dtstart.expected_type
'vDDDTypes'
>>> isinstance(dtstart.parse_error, Exception)
True

icalendar follows PEP 257 and adopts conventions from the Google Python Style Guide. A docstring should consist of a one-line summary, followed by an optional description, and then specific sections (usually ordered by inputs then outputs).

Key Rules:

• Summary: Must be a one-line summary of the object, terminated with a period.
• Description: If the summary is insufficient, provide an overall description (avoid implementation details) separated from the summary by a blank line.
• Sections: Use a section header followed by a colon (:) and an indented block of text. All items in a section should terminate with a period.
• Class Docstrings: Do not write docstrings for __init__ or __new__ methods. Instead, write the docstring for the class itself. Sphinx will automatically append __init__ docstrings to the class docstring.
• Escaping: To avoid double-escaping, use the raw r indicator before the leading docstring delimiter (e.g., r""").

"""Summary.

Longer description.
"""

The icalendar parser is error-tolerant. A single broken property does not prevent you from accessing other valid properties in the same component. Furthermore, broken properties preserve their raw values, ensuring that when you call Component.to_ical(), the invalid data is serialized back into the output exactly as it appeared in the input.

>>> from icalendar import Calendar
>>> ical_str = b"""BEGIN:VCALENDAR\n... VERSION:2.0\n... PRODID:test\n... BEGIN:VEVENT\n... UID:test-123\n... DTSTART:INVALID-DATE\n... DTEND:20250102T120000Z\n... SUMMARY:Meeting\n... END:VEVENT\n... END:VCALENDAR"""
>>> cal = Calendar.from_ical(ical_str)
>>> event = cal.walk("VEVENT")[0]
>>> # Accessing valid properties works
>>> event["DTEND"].dt.year
2025
>>> str(event["SUMMARY"])
'Meeting'
>>> # Round-trip serialization preserves the error
>>> output = cal.to_ical()
>>> b"DTSTART:INVALID-DATE" in output
True

Use the Parameters: section (do not use Args or Arguments) to document function inputs.

Formatting Rules:

1. Ordering:
   • Group parameters into Required and Optional.
   • Within each group, sort them alphabetically.
   • Required parameters must always appear before optional parameters.
   • Note: The order in the docstring must respect the order in the Python signature to avoid breaking changes, but the alphabetical sorting applies within the required/optional groups.
2. Content: Each parameter should include its name and a brief description.
3. Required Flag: For required attributes, include the term "Required." in the description, preferably immediately after the name.
4. Types: Use Python type hints in the function signature whenever possible; Sphinx will render them automatically. If type hints are missing, you must specify the type manually in the docstring.

def some_function(creq, breq, areq, bopt=2, aopt=1, copt=3) -> type_hints:
    """Summary.

    Longer description.

    Parameters:
        areq: Required. A string.
        breq: Required. A string.
        creq: Required. A string.
        aopt: An integer.
        bopt: An integer.
        copt: An integer.
    """
    pass