Typing Stubs for caldav

1.3.0.20250516 · active · verified Fri Apr 17

types-caldav provides static type hints (typing stubs) for the `caldav` library, enabling tools like MyPy to perform static analysis and detect type-related errors in code using `caldav`. It is part of the `typeshed` project, which offers high-quality type stubs for many popular Python packages. The current version is 1.3.0.20250516, with releases tracking updates to `typeshed`'s `caldav` stubs.

Common errors

```
ModuleNotFoundError: No module named 'types_caldav'
```
cause You are trying to import a symbol directly from `types_caldav`. This is incorrect as `types-caldav` provides type stubs, not a runtime module.

fix Import symbols from the actual `caldav` library (e.g., `from caldav import Principal`). The `types-caldav` package is only for static analysis by type checkers.
```
ModuleNotFoundError: No module named 'caldav'
```
cause You have installed `types-caldav` but not the actual `caldav` runtime library, and your code attempts to use `caldav`.

fix Install the `caldav` library: `pip install caldav` (or `pip install caldav types-caldav` to get both).
```
mypy: error: Cannot find implementation or library stub for module 'caldav'
```
cause You are using `caldav` in your code, but MyPy cannot find its type information. This usually means `types-caldav` is not installed, or MyPy's configuration is not picking it up.

fix Install `types-caldav` using `pip install types-caldav`. Ensure your `mypy` configuration (e.g., `mypy.ini`) is correctly set up, though typically installing the stubs is sufficient.

Warnings

gotcha Do not attempt to import modules or classes directly from `types_caldav`. This package contains only static typing stubs, not runnable code. All runtime imports should come from the actual `caldav` library.
Fix: Always use `import caldav` or `from caldav import ...` for runtime code. `types-caldav` works in the background with your type checker.
gotcha Installing `types-caldav` alone does not provide the `caldav` library for runtime execution. It only provides type hints for it.
Fix: If you intend to run `caldav` code, you must install both the runtime library and its stubs: `pip install caldav types-caldav`.
gotcha Version mismatches between the `caldav` library and `types-caldav` stubs can lead to inaccurate type checking results.
Fix: While `types-caldav` aims to track the latest stable `caldav` API via `typeshed`, very old or very new pre-release versions of `caldav` might not have perfectly corresponding stubs. Keep both `caldav` and `types-caldav` updated, or consult `typeshed` for specific `caldav` version support.

Install

pip install types-caldav Install `types-caldav`
pip install caldav types-caldav Install `caldav` runtime library alongside stubs

Imports

Principal
wrong:
```
from types_caldav import Principal
```
correct:
```
from caldav import Principal
```
Typing stubs like `types-caldav` provide type information for the `caldav` library at static analysis time (e.g., by MyPy) and are not intended for direct runtime import. You should import symbols directly from the `caldav` library.
Calendar
wrong:
```
from types_caldav import Calendar
```
correct:
```
from caldav import Calendar
```
As with other symbols, import Calendar directly from the `caldav` library. `types-caldav` enhances the type checking for this import.

Quickstart

This quickstart demonstrates basic usage of the `caldav` library. While `types-caldav` itself doesn't execute code, its installation enables static type checkers (like MyPy) to validate the type annotations and method calls within this `caldav` code, catching potential issues before runtime. Ensure both `caldav` and `types-caldav` are installed.

import caldav
from caldav import Principal, Calendar
import os

# These details should ideally come from environment variables for production
# For quickstart, placeholders are used. Replace with actual values.
URL = os.environ.get('CALDAV_URL', 'http://localhost:5232/caldav.php/')
USERNAME = os.environ.get('CALDAV_USERNAME', 'user')
PASSWORD = os.environ.get('CALDAV_PASSWORD', 'password')

if URL == 'http://localhost:5232/caldav.php/' or not USERNAME or not PASSWORD:
    print("Warning: Using default or empty CalDAV credentials. Set CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD environment variables for a real connection.")

try:
    # Connect to the CalDAV server. types-caldav provides type hints for 'client' and its methods.
    client = caldav.DAVClient(url=URL, username=USERNAME, password=PASSWORD)
    principal: Principal = client.principal()
    print(f"Successfully connected as principal: {principal.url}")

    # Get calendars associated with the principal.
    # types-caldav ensures 'calendars' is typed as list[Calendar].
    calendars: list[Calendar] = principal.calendars()
    print(f"Found {len(calendars)} calendars:")
    for calendar in calendars:
        print(f"  - {calendar.name} (URL: {calendar.url})")

except ImportError:
    print("Error: The 'caldav' library is not installed. Please run 'pip install caldav types-caldav'.")
except caldav.lib.error.DAVError as e:
    print(f"CalDAV connection error: {e}")
    print("Please verify your CalDAV server URL, username, and password.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

# The presence of 'types-caldav' allows type checkers like MyPy to validate
# the types of 'client', 'principal', and 'calendars' in this code.

view raw JSON →