tessl/pypi-caldav

CalDAV (RFC4791) client library for Python with comprehensive calendar server interaction capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Client Connection & Authentication

Name: tessl/pypi-caldav
Author: tessl

Core client functionality for connecting to CalDAV servers with comprehensive authentication support including Basic, Digest, Bearer token, and custom authentication methods.

Capabilities

DAVClient Creation

Creates the main CalDAV client for server communication with extensive configuration options for authentication, SSL, timeouts, and proxy settings.

class DAVClient:
    def __init__(self, url, proxy=None, username=None, password=None, auth=None, 
                 timeout=None, headers=None, ssl_verify_cert=True, ssl_cert=None, 
                 huge_tree=False, auth_type='auto'):
        """
        Initialize CalDAV client.
        
        Parameters:
        - url: str, CalDAV server URL
        - proxy: str, optional proxy URL
        - username: str, username for authentication
        - password: str, password for authentication  
        - auth: requests.auth.AuthBase, custom authentication object
        - timeout: int, request timeout in seconds
        - headers: dict, additional HTTP headers
        - ssl_verify_cert: bool, verify SSL certificates (default True)
        - ssl_cert: str, path to client SSL certificate
        - huge_tree: bool, enable parsing of large XML responses
        - auth_type: str, authentication method ('auto', 'basic', 'digest')
        """
    
    def __enter__(self):
        """Context manager entry - returns self."""
        
    def __exit__(self, exc_type, exc_val, exc_tb):
        """Context manager exit - closes session."""

Usage Examples:

# Basic authentication
client = caldav.DAVClient(
    url="https://calendar.example.com/caldav/",
    username="user@example.com", 
    password="password"
)

# Bearer token authentication
from caldav.requests import HTTPBearerAuth
client = caldav.DAVClient(
    url="https://calendar.example.com/caldav/",
    auth=HTTPBearerAuth("your-bearer-token")
)

# With SSL configuration
client = caldav.DAVClient(
    url="https://calendar.example.com/caldav/",
    username="user@example.com",
    password="password",
    ssl_verify_cert=False,  # Disable SSL verification for self-signed certs
    timeout=30
)

# With proxy and custom headers
client = caldav.DAVClient(
    url="https://calendar.example.com/caldav/",
    username="user@example.com", 
    password="password",
    proxy="http://proxy.company.com:8080",
    headers={"User-Agent": "My CalDAV App 1.0"}
)

Factory Function

Convenient factory function that creates DAVClient instances from configuration files, environment variables, or test settings.

def get_davclient(check_config_file=True, config_file=None, config_section=None, 
                  testconfig=False, environment=True, name=None, **config_data):
    """
    Factory function to create DAVClient from configuration.
    
    Parameters:
    - check_config_file: bool, whether to look for config files
    - config_file: str, specific config file path
    - config_section: str, section name in config file
    - testconfig: bool, use test configuration
    - environment: bool, read from environment variables
    - name: str, configuration name/profile
    - **config_data: additional configuration parameters
    
    Returns:
    DAVClient: Configured client instance
    
    Raises:
    DAVError: If no valid configuration found
    """

Usage Examples:

# Using environment variables
# Set: CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD
client = caldav.get_davclient()

# Using configuration file
# Create ~/.caldav_config.json with connection details
client = caldav.get_davclient()

# Using as context manager (recommended)
with caldav.get_davclient() as client:
    principal = client.principal()
    calendars = principal.calendars()

Principal Access

Retrieves the principal (user account) object for accessing calendar collections and user-specific functionality.

def principal(self, url=None):
    """
    Get the principal (user account) for this client.
    
    Parameters:
    - url: str, optional specific principal URL
    
    Returns:
    Principal: User's principal object
    """

Low-Level DAV Operations

Direct access to WebDAV and CalDAV protocol operations for advanced use cases and custom functionality.

def propfind(self, url, props=None, depth="0"):
    """
    Perform WebDAV PROPFIND request.
    
    Parameters:
    - url: str, target URL
    - props: list, properties to retrieve
    - depth: str, request depth ("0", "1", "infinity")
    
    Returns:
    DAVResponse: Response with property data
    """

def proppatch(self, url, body):
    """
    Perform WebDAV PROPPATCH request.
    
    Parameters:
    - url: str, target URL
    - body: str, XML body with property changes
    
    Returns:
    DAVResponse: Response object
    """

def report(self, url, query, depth="0"):
    """
    Perform WebDAV REPORT request.
    
    Parameters:
    - url: str, target URL
    - query: str, XML query body
    - depth: str, request depth
    
    Returns:
    DAVResponse: Response with report data
    """

def mkcol(self, url, body=None):
    """
    Create collection (WebDAV MKCOL).
    
    Parameters:
    - url: str, collection URL
    - body: str, optional XML body
    
    Returns:
    DAVResponse: Response object
    """

def mkcalendar(self, url, body=None):
    """
    Create calendar collection (CalDAV MKCALENDAR).
    
    Parameters:
    - url: str, calendar URL
    - body: str, optional XML body with calendar properties
    
    Returns:
    DAVResponse: Response object
    """

def put(self, url, body, headers=None):
    """
    HTTP PUT request.
    
    Parameters:
    - url: str, target URL
    - body: str, request body
    - headers: dict, additional headers
    
    Returns:
    DAVResponse: Response object
    """

def post(self, url, body, headers=None):
    """
    HTTP POST request.
    
    Parameters:
    - url: str, target URL
    - body: str, request body
    - headers: dict, additional headers
    
    Returns:
    DAVResponse: Response object
    """

def delete(self, url):
    """
    HTTP DELETE request.
    
    Parameters:
    - url: str, target URL
    
    Returns:
    DAVResponse: Response object
    """

def request(self, url, method="GET", body="", headers=None):
    """
    Generic HTTP request.
    
    Parameters:
    - url: str, target URL
    - method: str, HTTP method
    - body: str, request body
    - headers: dict, HTTP headers
    
    Returns:
    DAVResponse: Response object
    """

def options(self, url):
    """
    HTTP OPTIONS request to discover server capabilities.
    
    Parameters:
    - url: str, target URL
    
    Returns:
    DAVResponse: Response object with server capabilities
    """

def close(self):
    """
    Close the HTTP session and clean up resources.
    """

def check_dav_support(self):
    """
    Check if server supports WebDAV.
    
    Returns:
    bool: True if WebDAV is supported
    """

def check_cdav_support(self):
    """
    Check if server supports CalDAV.
    
    Returns:
    bool: True if CalDAV is supported
    """

def check_scheduling_support(self):
    """
    Check if server supports CalDAV scheduling extensions.
    
    Returns:
    bool: True if scheduling is supported
    """

def calendar(self, url=None, parent=None, name=None, id=None, **kwargs):
    """
    Get calendar object by URL or create new calendar reference.
    
    Parameters:
    - url: str, calendar URL
    - parent: DAVObject, parent object
    - name: str, calendar name
    - id: str, calendar ID
    
    Returns:
    Calendar: Calendar object
    """

Authentication Classes

Specialized authentication classes for different authentication methods and token types.

class HTTPBearerAuth:
    def __init__(self, password):
        """
        Bearer token authentication.
        
        Parameters:
        - password: str, bearer token
        """

Response Handling

Response wrapper that handles CalDAV server responses with automatic XML parsing and property extraction.

class DAVResponse:
    """Response from DAV request with XML parsing capabilities."""
    
    raw: str  # Raw response content
    reason: str  # HTTP reason phrase
    tree: Optional[Element]  # Parsed XML tree
    headers: CaseInsensitiveDict  # Response headers
    status: int  # HTTP status code
    davclient: DAVClient  # Associated client
    
    def find(self, path):
        """
        Find XML elements by path.
        
        Parameters:
        - path: str, XPath expression
        
        Returns:
        list: Matching XML elements
        """
    
    def expand_simple_props(self, props=None, multi_value_props=None):
        """
        Parse property values from XML response.
        
        Parameters:
        - props: list, properties to extract
        - multi_value_props: list, properties that can have multiple values
        
        Returns:
        dict: Property name/value pairs
        """

Configuration Management

class ConfigurationManager:
    """Manages CalDAV client configuration from files and environment."""
    
    def get_davclient_from_json(self, json_conf):
        """Create client from JSON configuration."""
    
    def get_davclient_from_config_file(self, filename):
        """Create client from configuration file."""
    
    def get_davclient_from_environment(self):
        """Create client from environment variables."""

Install with Tessl CLI