{"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":"en","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":[{"note":"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.","wrong":"from types_caldav import Principal","symbol":"Principal","correct":"from caldav import Principal"},{"note":"As with other symbols, import Calendar directly from the `caldav` library. `types-caldav` enhances the type checking for this import.","wrong":"from types_caldav import Calendar","symbol":"Calendar","correct":"from caldav import Calendar"}],"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,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'types_caldav'"},{"fix":"Install the `caldav` library: `pip install caldav` (or `pip install caldav types-caldav` to get both).","cause":"You have installed `types-caldav` but not the actual `caldav` runtime library, and your code attempts to use `caldav`.","error":"ModuleNotFoundError: No module named 'caldav'"},{"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.","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.","error":"mypy: error: Cannot find implementation or library stub for module 'caldav'"}]}