Typing Stubs for vobject

Common errors

• ModuleNotFoundError: No module named 'types_vobject'

  cause Attempting to import modules or classes directly from the `types_vobject` package (e.g., `from types_vobject import ...`).
  fix The `types-vobject` package contains only stub files (`.pyi`) for type checkers. All imports should be made from the `vobject` library itself (e.g., `import vobject` or `from vobject.base import Component`).

• error: Module 'vobject' has no attribute '...' (reportAttributeAccessIssue)

  cause This error from a type checker (like MyPy or Pyright) indicates that either the `vobject` library itself is not installed, or the installed `types-vobject` stubs are for a significantly different version of `vobject` than what's installed, or the type checker environment is not correctly configured to find the stubs.
  fix First, ensure `pip install vobject` is run. If `vobject` is installed, verify `vobject` and `types-vobject` versions are compatible. Finally, check your type checker's configuration (e.g., `mypy.ini`) to ensure it's correctly picking up the installed stubs in your virtual environment.

• error: Cannot find module named 'vobject' (reportMissingImports)

  cause This type checker error indicates that the `vobject` library itself (not just its stubs) is not installed in the Python environment that the type checker is inspecting.
  fix Run `pip install vobject`. Type stubs are only useful if the actual library they describe is also present.

Warnings

• gotcha Installing `types-vobject` provides only type annotations for static analysis; it does not add any new runtime objects, functions, or classes to your Python environment. You must install the actual `vobject` library (`pip install vobject`) to use its functionalities.
  Fix: Always install `vobject` (e.g., `pip install vobject`) alongside `types-vobject` if you intend to run the code.
• gotcha The type stubs provided by `types-vobject` are generated from a specific version of the `vobject` library. Using significantly different versions of `vobject` and `types-vobject` can lead to incorrect type checking results (e.g., missing attributes or incorrect signatures) or even runtime errors if type hints mislead you.
  Fix: Ensure your `vobject` and `types-vobject` versions are relatively close. If you encounter type checking issues, try upgrading both packages to their latest compatible versions or checking the `typeshed` repository for which `vobject` version the stubs target.

Install

• pip install types-vobject Install only stubs
• pip install vobject types-vobject Install library and stubs

Imports

• Component
  wrong:

  from types_vobject import Component

  correct:

  import vobject
  from vobject.base import Component

  `types-vobject` provides stubs, not runtime modules. Imports should always be from the `vobject` package.
• VEvent
  wrong:

  import types_vobject.base.VEvent

  correct:

  from vobject.base import VEvent

  Never import directly from `types_vobject`.

Quickstart

This quickstart demonstrates how to use the `vobject` library with type hints. It shows creating a simple VCALENDAR with an event, adding properties, and serializing it. With `types-vobject` installed, a type checker will provide autocompletion and error checking for `vobject` objects and methods.

import vobject
from vobject.base import Component, VEvent
from typing import cast, List

# Install 'vobject' and 'types-vobject' first:
# pip install vobject types-vobject

def create_simple_calendar() -> Component:
    """Creates a VCALENDAR with a single VEVENT using type hints."""
    # 'calendar' is inferred as vobject.base.Component
    calendar = vobject.newFromBehavior('vcalendar')

    # Add an event component
    event: Component = calendar.add('vevent')

    # Accessing the event via vevent_list is type-safe due to stubs
    event_list: List[VEvent] = calendar.vevent_list
    first_event = event_list[0] # first_event is inferred as VEvent

    first_event.add('dtstart').value = '20231027T100000'
    first_event.add('dtend').value = '20231027T110000'
    first_event.add('summary').value = 'Meeting with client'
    first_event.add('description').value = 'Discuss project roadmap and next steps.'

    return calendar

if __name__ == '__main__':
    my_calendar = create_simple_calendar()
    print(my_calendar.serialize())

    # Accessing properties with type safety
    first_event: VEvent = my_calendar.vevent_list[0]
    print(f"\nEvent Summary: {first_event.summary.value}")
    print(f"Event Description: {first_event.description.value}")
    print(f"Event Start: {first_event.dtstart.value}")