0
# Client Connection & Authentication
1

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

4
## Capabilities
5

6
### DAVClient Creation
7

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

10
```python { .api }
11
class DAVClient:
12
    def __init__(self, url, proxy=None, username=None, password=None, auth=None, 
13
                 timeout=None, headers=None, ssl_verify_cert=True, ssl_cert=None, 
14
                 huge_tree=False, auth_type='auto'):
15
        """
16
        Initialize CalDAV client.
17
        
18
        Parameters:
19
        - url: str, CalDAV server URL
20
        - proxy: str, optional proxy URL
21
        - username: str, username for authentication
22
        - password: str, password for authentication  
23
        - auth: requests.auth.AuthBase, custom authentication object
24
        - timeout: int, request timeout in seconds
25
        - headers: dict, additional HTTP headers
26
        - ssl_verify_cert: bool, verify SSL certificates (default True)
27
        - ssl_cert: str, path to client SSL certificate
28
        - huge_tree: bool, enable parsing of large XML responses
29
        - auth_type: str, authentication method ('auto', 'basic', 'digest')
30
        """
31
    
32
    def __enter__(self):
33
        """Context manager entry - returns self."""
34
        
35
    def __exit__(self, exc_type, exc_val, exc_tb):
36
        """Context manager exit - closes session."""
37
```
38

39
**Usage Examples:**
40

41
```python
42
# Basic authentication
43
client = caldav.DAVClient(
44
    url="https://calendar.example.com/caldav/",
45
    username="user@example.com", 
46
    password="password"
47
)
48

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

56
# With SSL configuration
57
client = caldav.DAVClient(
58
    url="https://calendar.example.com/caldav/",
59
    username="user@example.com",
60
    password="password",
61
    ssl_verify_cert=False,  # Disable SSL verification for self-signed certs
62
    timeout=30
63
)
64

65
# With proxy and custom headers
66
client = caldav.DAVClient(
67
    url="https://calendar.example.com/caldav/",
68
    username="user@example.com", 
69
    password="password",
70
    proxy="http://proxy.company.com:8080",
71
    headers={"User-Agent": "My CalDAV App 1.0"}
72
)
73
```
74

75
### Factory Function
76

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

79
```python { .api }
80
def get_davclient(check_config_file=True, config_file=None, config_section=None, 
81
                  testconfig=False, environment=True, name=None, **config_data):
82
    """
83
    Factory function to create DAVClient from configuration.
84
    
85
    Parameters:
86
    - check_config_file: bool, whether to look for config files
87
    - config_file: str, specific config file path
88
    - config_section: str, section name in config file
89
    - testconfig: bool, use test configuration
90
    - environment: bool, read from environment variables
91
    - name: str, configuration name/profile
92
    - **config_data: additional configuration parameters
93
    
94
    Returns:
95
    DAVClient: Configured client instance
96
    
97
    Raises:
98
    DAVError: If no valid configuration found
99
    """
100
```
101

102
**Usage Examples:**
103

104
```python
105
# Using environment variables
106
# Set: CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD
107
client = caldav.get_davclient()
108

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

113
# Using as context manager (recommended)
114
with caldav.get_davclient() as client:
115
    principal = client.principal()
116
    calendars = principal.calendars()
117
```
118

119
### Principal Access
120

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

123
```python { .api }
124
def principal(self, url=None):
125
    """
126
    Get the principal (user account) for this client.
127
    
128
    Parameters:
129
    - url: str, optional specific principal URL
130
    
131
    Returns:
132
    Principal: User's principal object
133
    """
134
```
135

136
### Low-Level DAV Operations
137

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

140
```python { .api }
141
def propfind(self, url, props=None, depth="0"):
142
    """
143
    Perform WebDAV PROPFIND request.
144
    
145
    Parameters:
146
    - url: str, target URL
147
    - props: list, properties to retrieve
148
    - depth: str, request depth ("0", "1", "infinity")
149
    
150
    Returns:
151
    DAVResponse: Response with property data
152
    """
153

154
def proppatch(self, url, body):
155
    """
156
    Perform WebDAV PROPPATCH request.
157
    
158
    Parameters:
159
    - url: str, target URL
160
    - body: str, XML body with property changes
161
    
162
    Returns:
163
    DAVResponse: Response object
164
    """
165

166
def report(self, url, query, depth="0"):
167
    """
168
    Perform WebDAV REPORT request.
169
    
170
    Parameters:
171
    - url: str, target URL
172
    - query: str, XML query body
173
    - depth: str, request depth
174
    
175
    Returns:
176
    DAVResponse: Response with report data
177
    """
178

179
def mkcol(self, url, body=None):
180
    """
181
    Create collection (WebDAV MKCOL).
182
    
183
    Parameters:
184
    - url: str, collection URL
185
    - body: str, optional XML body
186
    
187
    Returns:
188
    DAVResponse: Response object
189
    """
190

191
def mkcalendar(self, url, body=None):
192
    """
193
    Create calendar collection (CalDAV MKCALENDAR).
194
    
195
    Parameters:
196
    - url: str, calendar URL
197
    - body: str, optional XML body with calendar properties
198
    
199
    Returns:
200
    DAVResponse: Response object
201
    """
202

203
def put(self, url, body, headers=None):
204
    """
205
    HTTP PUT request.
206
    
207
    Parameters:
208
    - url: str, target URL
209
    - body: str, request body
210
    - headers: dict, additional headers
211
    
212
    Returns:
213
    DAVResponse: Response object
214
    """
215

216
def post(self, url, body, headers=None):
217
    """
218
    HTTP POST request.
219
    
220
    Parameters:
221
    - url: str, target URL
222
    - body: str, request body
223
    - headers: dict, additional headers
224
    
225
    Returns:
226
    DAVResponse: Response object
227
    """
228

229
def delete(self, url):
230
    """
231
    HTTP DELETE request.
232
    
233
    Parameters:
234
    - url: str, target URL
235
    
236
    Returns:
237
    DAVResponse: Response object
238
    """
239

240
def request(self, url, method="GET", body="", headers=None):
241
    """
242
    Generic HTTP request.
243
    
244
    Parameters:
245
    - url: str, target URL
246
    - method: str, HTTP method
247
    - body: str, request body
248
    - headers: dict, HTTP headers
249
    
250
    Returns:
251
    DAVResponse: Response object
252
    """
253

254
def options(self, url):
255
    """
256
    HTTP OPTIONS request to discover server capabilities.
257
    
258
    Parameters:
259
    - url: str, target URL
260
    
261
    Returns:
262
    DAVResponse: Response object with server capabilities
263
    """
264

265
def close(self):
266
    """
267
    Close the HTTP session and clean up resources.
268
    """
269

270
def check_dav_support(self):
271
    """
272
    Check if server supports WebDAV.
273
    
274
    Returns:
275
    bool: True if WebDAV is supported
276
    """
277

278
def check_cdav_support(self):
279
    """
280
    Check if server supports CalDAV.
281
    
282
    Returns:
283
    bool: True if CalDAV is supported
284
    """
285

286
def check_scheduling_support(self):
287
    """
288
    Check if server supports CalDAV scheduling extensions.
289
    
290
    Returns:
291
    bool: True if scheduling is supported
292
    """
293

294
def calendar(self, url=None, parent=None, name=None, id=None, **kwargs):
295
    """
296
    Get calendar object by URL or create new calendar reference.
297
    
298
    Parameters:
299
    - url: str, calendar URL
300
    - parent: DAVObject, parent object
301
    - name: str, calendar name
302
    - id: str, calendar ID
303
    
304
    Returns:
305
    Calendar: Calendar object
306
    """
307
```
308

309
### Authentication Classes
310

311
Specialized authentication classes for different authentication methods and token types.
312

313
```python { .api }
314
class HTTPBearerAuth:
315
    def __init__(self, password):
316
        """
317
        Bearer token authentication.
318
        
319
        Parameters:
320
        - password: str, bearer token
321
        """
322
```
323

324
### Response Handling
325

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

328
```python { .api }
329
class DAVResponse:
330
    """Response from DAV request with XML parsing capabilities."""
331
    
332
    raw: str  # Raw response content
333
    reason: str  # HTTP reason phrase
334
    tree: Optional[Element]  # Parsed XML tree
335
    headers: CaseInsensitiveDict  # Response headers
336
    status: int  # HTTP status code
337
    davclient: DAVClient  # Associated client
338
    
339
    def find(self, path):
340
        """
341
        Find XML elements by path.
342
        
343
        Parameters:
344
        - path: str, XPath expression
345
        
346
        Returns:
347
        list: Matching XML elements
348
        """
349
    
350
    def expand_simple_props(self, props=None, multi_value_props=None):
351
        """
352
        Parse property values from XML response.
353
        
354
        Parameters:
355
        - props: list, properties to extract
356
        - multi_value_props: list, properties that can have multiple values
357
        
358
        Returns:
359
        dict: Property name/value pairs
360
        """
361
```
362

363
## Configuration Management
364

365
```python { .api }
366
class ConfigurationManager:
367
    """Manages CalDAV client configuration from files and environment."""
368
    
369
    def get_davclient_from_json(self, json_conf):
370
        """Create client from JSON configuration."""
371
    
372
    def get_davclient_from_config_file(self, filename):
373
        """Create client from configuration file."""
374
    
375
    def get_davclient_from_environment(self):
376
        """Create client from environment variables."""
377
```