{"id":10320,"library":"types-caldav","title":"Typing Stubs for caldav","description":"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.","status":"active","version":"1.3.0.20250516","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type hints","caldav","typeshed"],"install":[{"cmd":"pip install types-caldav","lang":"bash","label":"Install `types-caldav`"},{"cmd":"pip install caldav types-caldav","lang":"bash","label":"Install `caldav` runtime library alongside stubs"}],"dependencies":[{"reason":"Provides 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.","package":"caldav","optional":true}],"imports":[{"wrong":"from caldav-stubs import Principal","symbol":"Principal","correct":"from caldav_stubs import Principal"}],"quickstart":{"code":"import caldav\nfrom caldav import Principal, Calendar\nimport os\n\n# These details should ideally come from environment variables for production\n# For quickstart, placeholders are used. Replace with actual values.\nURL = os.environ.get('CALDAV_URL', 'http://localhost:5232/caldav.php/')\nUSERNAME = os.environ.get('CALDAV_USERNAME', 'user')\nPASSWORD = os.environ.get('CALDAV_PASSWORD', 'password')\n\nif URL == 'http://localhost:5232/caldav.php/' or not USERNAME or not PASSWORD:\n    print(\"Warning: Using default or empty CalDAV credentials. Set CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD environment variables for a real connection.\")\n\ntry:\n    # Connect to the CalDAV server. types-caldav provides type hints for 'client' and its methods.\n    client = caldav.DAVClient(url=URL, username=USERNAME, password=PASSWORD)\n    principal: Principal = client.principal()\n    print(f\"Successfully connected as principal: {principal.url}\")\n\n    # Get calendars associated with the principal.\n    # types-caldav ensures 'calendars' is typed as list[Calendar].\n    calendars: list[Calendar] = principal.calendars()\n    print(f\"Found {len(calendars)} calendars:\")\n    for calendar in calendars:\n        print(f\"  - {calendar.name} (URL: {calendar.url})\")\n\nexcept ImportError:\n    print(\"Error: The 'caldav' library is not installed. Please run 'pip install caldav types-caldav'.\")\nexcept caldav.lib.error.DAVError as e:\n    print(f\"CalDAV connection error: {e}\")\n    print(\"Please verify your CalDAV server URL, username, and password.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\n# The presence of 'types-caldav' allows type checkers like MyPy to validate\n# the types of 'client', 'principal', and 'calendars' in this code.","lang":"python","description":"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."},"warnings":[{"fix":"Always use `import caldav` or `from caldav import ...` for runtime code. `types-caldav` works in the background with your type checker.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you intend to run `caldav` code, you must install both the runtime library and its stubs: `pip install caldav types-caldav`.","message":"Installing `types-caldav` alone does not provide the `caldav` library for runtime execution. It only provides type hints for it.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Version mismatches between the `caldav` library and `types-caldav` stubs can lead to inaccurate type checking results.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.3.0.20250516':59 'analysi':25 'caldav':4,7,16,35,67,73 'code':33 'current':56 'detect':27 'enabl':18 'error':31 'high':46 'high-qual':45 'hint':11,72 'librari':17 'like':20 'mani':51 'mypi':21 'offer':44 'packag':54 'part':38 'perform':23 'popular':52 'project':42 'provid':8 'python':53 'qualiti':47 'relat':30 'releas':61 'static':9,24 'stub':2,13,49,68,70 'tool':19 'track':62 'type':1,6,10,12,29,48,69,71 'type-rel':28 'types-caldav':5 'typesh':41,65,74 'updat':63 'use':34 'version':57","created_at":"2026-04-17T01:23:30.834554+00:00","updated_at":"2026-04-17T01:23:30.834554+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'caldav_stubs'"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.3.0.20250516","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/caldav.md","pypi":"https://pypi.org/project/types-caldav/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}