Install & Compatibility
Where this runs
tested against v1.3.0.20250516 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.546s · 67.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.524s · 68MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Principal
✓ from caldav_stubs import Principal
✗ from caldav-stubs import Principal
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.
Upgrade
Version history
1.3.0.20250516latest on PyPI · released May 16, 2025
Audit
Dependencies
caldavoptionalProvides the runtime library for which types-caldav offers static type hints. While not a hard runtime dependency for `types-caldav` itself, the stubs are functionally useless without the `caldav` library.