### Install aiowebdav

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Install the aiowebdav package using pip. This command is used for initial setup.

```bash
pip install aiowebdav
```

--------------------------------

### Run WebDAV Server with Docker

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Start a WebDAV server for testing purposes using a Docker container. Ensure Docker is installed and running.

```shell
docker pull bytemark/webdav
docker run -d --name webdav -e AUTH_TYPE=Basic -e USERNAME=alice -e PASSWORD=secret1234 -v conf:/usr/local/apache2/conf -p 8585:80 bytemark/webdav
```

--------------------------------

### Get Free Space with client.free

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Issues a PROPFIND request for quota-available-bytes to get server free space. Raises MethodNotSupported if the server does not advertise quota properties.

```python
import asyncio
from aiowebdav.client import Client
from aiowebdav.exceptions import MethodNotSupported

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        try:
            free_bytes = await client.free()
            print(f"Free space: {free_bytes / 1024 / 1024:.1f} MB")
            # Free space: 20480.0 MB
        except MethodNotSupported as e:
            print(f"Server does not support free space query: {e}")

asyncio.run(main())
```

--------------------------------

### Client Setup and Basic Configuration

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Demonstrates how to initialize the `Client` with basic username/password authentication and use it as an async context manager. It also shows how to disable SSL certificate verification.

```APIDOC
## Client Setup and Basic Configuration

`Client(options)` is the main entry point. It accepts a dictionary of connection settings and creates an `aiohttp.ClientSession` internally. The client supports async context manager usage for automatic session cleanup.

```python
import asyncio
from aiowebdav.client import Client
from aiowebdav.exceptions import WebDavException

# Basic username/password authentication
options = {
    'webdav_hostname': 'https://webdav.example.com',
    'webdav_login':    'alice',
    'webdav_password': 'secret1234',
}

async def main():
    async with Client(options) as client:
        client.verify = False  # disable SSL certificate verification
        is_valid = client.valid()
        print(is_valid)  # True

asyncio.run(main())
```
```

--------------------------------

### Get Resource Metadata with client.info

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Performs a PROPFIND to get metadata like creation date, size, and ETag for a specified remote resource. Raises RemoteResourceNotFound if the path does not exist.

```python
import asyncio
from aiowebdav.client import Client
from aiowebdav.exceptions import RemoteResourceNotFound

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        try:
            meta = await client.info('documents/report.pdf')
            print(meta)
            # {
            #   'created':      '2024-01-15T10:30:00Z',
            #   'name':         'report.pdf',
            #   'size':         '204800',
            #   'modified':     'Mon, 15 Jan 2024 10:30:00 GMT',
            #   'etag':         '"abc123"',
            #   'content_type': 'application/pdf'
            # }
        except RemoteResourceNotFound as e:
            print(f"Not found: {e}")

asyncio.run(main())
```

--------------------------------

### Basic Client Setup with Username/Password

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Set up the aiowebdav client with basic hostname, login, and password. The client supports async context manager usage for automatic session cleanup. Disable SSL certificate verification if needed.

```python
import asyncio
from aiowebdav.client import Client
from aiowebdav.exceptions import WebDavException

# Basic username/password authentication
options = {
    'webdav_hostname': 'https://webdav.example.com',
    'webdav_login':    'alice',
    'webdav_password': 'secret1234',
}

async def main():
    async with Client(options) as client:
        client.verify = False  # disable SSL certificate verification
        is_valid = client.valid()
        print(is_valid)  # True

asyncio.run(main())
```

--------------------------------

### client.info — Get Resource Metadata

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Performs a PROPFIND and returns a dictionary with metadata for the specified remote resource.

```APIDOC
## client.info — Get Resource Metadata

Performs a `PROPFIND` and returns a dictionary with keys `created`, `name`, `size`, `modified`, `etag`, and `content_type` for the specified remote resource. Raises `RemoteResourceNotFound` if the path does not exist.

### Method
GET (implicitly via PROPFIND)

### Endpoint
Not applicable (method call on client object)

### Parameters
#### Path Parameters
- **remote_path** (str) - Required - The path to the remote resource.

### Request Example
```python
meta = await client.info('documents/report.pdf')
```

### Response
- **metadata** (dict) - A dictionary containing resource metadata:
  - **created** (str) - Creation timestamp.
  - **name** (str) - Resource name.
  - **size** (str) - Resource size in bytes.
  - **modified** (str) - Last modification timestamp.
  - **etag** (str) - Entity tag.
  - **content_type** (str) - MIME type of the resource.
```

--------------------------------

### client.free — Get Free Space

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Issues a PROPFIND request for 'quota-available-bytes' and returns the available free space on the server in bytes as an integer. Raises MethodNotSupported if the server does not advertise quota properties.

```APIDOC
## client.free — Get Free Space

Issues a `PROPFIND` request for `quota-available-bytes` and returns the available free space on the server in bytes as an integer. Raises `MethodNotSupported` if the server does not advertise quota properties.

### Method
GET (implicitly via PROPFIND)

### Endpoint
Not applicable (method call on client object)

### Parameters
None

### Request Example
```python
free_bytes = await client.free()
```

### Response
- **free_bytes** (int) - The available free space in bytes.
```

--------------------------------

### Get Resource Information

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Asynchronously retrieve information about a specific resource (file or directory) on the WebDAV server. This method returns details about the resource.

```python
# Get information about the resource

await client.info("dir1/file1")
await client.info("dir1/")
```

--------------------------------

### Get Resource

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Retrieves a resource object representing a specific file or directory on the remote server.

```APIDOC
## Get Resource

Retrieves a resource object representing a specific file or directory on the remote server.

### Method

```python
client.resource(remote_path: str) -> Resource
```

### Parameters

- **remote_path** (str) - The path of the resource on the remote server.

### Returns

- (Resource) - A resource object that can be used for further operations.
```

--------------------------------

### Get Resource Object with aiowebdav

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Obtain a resource object representing a remote file or directory using the client.resource method.

```python
res1 = client.resource("dir1/file1")
```

--------------------------------

### Override Default WebDAV Methods

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Configure the client to use alternative WebDAV methods for specific actions, such as using 'GET' for 'check'. This is useful if the server has non-standard method support.

```python
from aiowebdav.client import Client

options = {
 'webdav_hostname': "https://webdav.server.ru",
 'webdav_login': "login",
 'webdav_password': "password",
 'webdav_override_methods': {
  'check': 'GET'
 }

}
client = Client(options)
```

--------------------------------

### Basic Client Initialization and Mkdir

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Demonstrates initializing the WebDAV client with options and executing a 'mkdir' request. SSL certificate verification can be disabled.

```python
import asyncio
from aiowebdav.client import Client

options = {
 'webdav_hostname': "https://webdav.server.ru",
 'webdav_login': "login",
 'webdav_password': "password",
 "disable_check": True
}

async def main():
    client = Client(options)
    client.verify = False  # To not check SSL certificates (Default = True)
    await client.execute_request("mkdir", 'directory_name')
asyncio.run(main())
```

--------------------------------

### Configure WebDAV Client with Options

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Initialize the WebDAV client with essential configuration options including hostname, login, and password for authentication.

```python
from aiowebdav.client import Client

options = {
 'webdav_hostname': "https://webdav.server.ru",
 'webdav_login': "login",
 'webdav_password': "password"
}
client = Client(options)
```

--------------------------------

### Pull (Get Missing Files)

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Synchronizes local files with remote files, downloading only those that are missing or have changed on the remote.

```APIDOC
## Pull (Get Missing Files)

Synchronizes local files with remote files, downloading only those that are missing or have changed on the remote.

### Method

```python
await client.pull(remote_directory: str, local_directory: str)
```

### Parameters

- **remote_directory** (str) - The source directory on the remote server.
- **local_directory** (str) - The destination directory on the local system.
```

--------------------------------

### Client Advanced Configuration Options

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Illustrates advanced configuration options for the `Client`, including token authentication, custom root paths, timeouts, proxy settings, speed limits, and method overrides.

```APIDOC
## Client — Advanced Configuration Options

`Client` accepts a rich set of optional keys in the options dictionary to configure timeouts, proxies, SSL contexts, token auth, method overrides, chunk size, and speed limits.

```python
import asyncio
import ssl
from aiowebdav.client import Client

ssl_ctx = ssl.create_default_context()

options = {
    'webdav_hostname':         'https://webdav.example.com',
    'webdav_login':            'alice',
    'webdav_password':         'secret1234',
    # OAuth2 bearer token (replaces login/password auth)
    # 'webdav_token':          'my-oauth2-token',
    'webdav_root':             '/dav/',          # custom root path on server
    'webdav_timeout':          60,               # seconds (int or float)
    'webdav_ssl':              ssl_ctx,          # ssl.SSLContext instance
    'webdav_proxy':            'http://proxy.corp:8080',
    'webdav_proxy_auth':       'proxy-token',
    'recv_speed':              3_000_000,        # bytes/sec download cap
    'send_speed':              3_000_000,        # bytes/sec upload cap
    'chunk_size':              131072,           # download/upload chunk size
    'verbose':                 True,
    'disable_check':           False,            # set True if server lacks HEAD
    'webdav_override_methods': {'check': 'GET'}, # override per-action HTTP verb
}

async def main():
    async with Client(options) as client:
        print(client.webdav.hostname)  # 'https://webdav.example.com'
        print(client.webdav.root)      # '/dav'

asyncio.run(main())
```
```

--------------------------------

### Create Directory with client.mkdir

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Sends MKCOL to create a directory. Set recursive=True to create missing parent directories automatically. Returns True on success. Missing parents raise RemoteParentNotFound without recursive=True.

```python
import asyncio
from aiowebdav.client import Client
from aiowebdav.exceptions import RemoteParentNotFound

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        # Create a single directory (parent must exist)
        await client.mkdir('backups')

        # Create nested directories (parents created automatically)
        await client.mkdir('projects/2024/reports', recursive=True)

        # Without recursive=True, missing parent raises an error
        try:
            await client.mkdir('a/b/c/d')
        except RemoteParentNotFound as e:
            print(e)  # Remote parent for: /a/b/c/d/ not found

asyncio.run(main())
```

--------------------------------

### Client Configuration

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Demonstrates how to configure the aiowebdav client with various options like hostname, authentication, method overrides, timeouts, proxy settings, SSL contexts, speed limits, verbose mode, check disabling, and chunk size.

```APIDOC
## Client Configuration

### Description
Configure the aiowebdav client with various options.

### Options
- `webdav_hostname` (string): Required. Host name or IP address of the WebDAV server.
- `webdav_login` (string): Optional. Username for authentication.
- `webdav_password` (string): Optional. Password for authentication.
- `disable_check` (bool): Optional. Disable the default resource checking. Defaults to False.
- `webdav_override_methods` (dict): Optional. Override default WebDAV methods for actions (e.g., {'check': 'GET'}).
- `webdav_timeout` (int): Optional. Request timeout in seconds. Defaults to 30.
- `webdav_proxy` (string): Optional. URL for a proxy server.
- `webdav_proxy_auth` (string): Optional. Authentication string for the proxy server.
- `webdav_ssl` (string): Optional. Path to SSL context for secure connections.
- `recv_speed` (int): Optional. Rate limit for data download speed in Bytes per second.
- `send_speed` (int): Optional. Rate limit for data upload speed in Bytes per second.
- `verbose` (bool): Optional. Enable or disable verbose mode. Defaults to False.
- `chunk_size` (int): Optional. Chunk size for content downloading. Defaults to 65536.

### Request Example
```python
from aiowebdav.client import Client

options = {
 'webdav_hostname': "https://webdav.server.ru",
 'webdav_login': "login",
 'webdav_password': "password",
 'webdav_timeout': 30,
 'webdav_proxy': "http://127.0.0.1:8080",
 'webdav_proxy_auth': "xxx",
 'webdav_ssl': 'sslcontext',
 'recv_speed' : 3000000,
 'send_speed' : 3000000,
 'verbose'    : True,
 'disable_check': True,
 'chunk_size': 65536,
 'webdav_override_methods': {
  'check': 'GET'
 }
}
client = Client(options)
```
```

--------------------------------

### Execute Low-Level HTTP Request with aiowebdav

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Demonstrates the low-level `execute_request` method for creating directories and sending custom PROPFIND requests. Requires `asyncio` and `aiowebdav.client.Client`. The `disable_check` flag can be useful for non-standard servers.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234',
                       'disable_check': True}) as client:
        # Low-level: create a directory using the raw action name
        response = await client.execute_request(action='mkdir', path='new_folder/')
        print(response.status)  # 201

        # Low-level: send a custom PROPFIND with extra headers
        response = await client.execute_request(
            action='list',
            path='documents/',
            headers_ext=['Depth: 0']
        )
        body = await response.read()
        print(body[:80])  # raw XML response bytes

asyncio.run(main())
```

--------------------------------

### Download File or Directory with Progress Callback

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Use `client.download` to download files or directories. An optional `progress` callback can monitor download progress.

```python
import asyncio
from aiowebdav.client import Client

def on_progress(current, total, filename):
    if total:
        pct = current / total * 100
        print(f"\r{filename}: {pct:.1f}%", end='', flush=True)

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        # Download a single file with progress
        await client.download(
            remote_path='documents/report.pdf',
            local_path='/tmp/report.pdf',
            progress=on_progress,
            progress_args=('report.pdf',)
        )
        print()  # newline after progress

        # Download an entire directory recursively
        await client.download(
            remote_path='documents/',
            local_path='/tmp/documents/'
        )

asyncio.run(main())
```

--------------------------------

### Run Unit Tests

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Execute the project's unit tests using the unittest module. Ensure the WebDAV container is running before executing.

```shell
python -m unittest discover -s tests
```

--------------------------------

### Create a Directory

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Asynchronously create a new directory on the WebDAV server. This method takes the path for the new directory.

```python
# Create directory

await client.mkdir("dir1/dir2")
```

--------------------------------

### client.mkdir — Create Directory

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Sends MKCOL to create a directory. Can create parent directories automatically if recursive is True. Returns True on success.

```APIDOC
## client.mkdir — Create Directory

Sends `MKCOL` to create a directory. Set `recursive=True` to create all missing parent directories automatically. Returns `True` on success. Raises `RemoteParentNotFound` if `recursive` is False and a parent directory does not exist.

### Method
MKCOL

### Endpoint
Not applicable (method call on client object)

### Parameters
#### Path Parameters
- **remote_path** (str) - Required - The path for the new directory.
#### Query Parameters
- **recursive** (bool) - Optional - If True, create parent directories as needed. Defaults to False.

### Request Example
```python
await client.mkdir('backups')
await client.mkdir('projects/2024/reports', recursive=True)
```

### Response
- **success** (bool) - True if the directory was created successfully.
```

--------------------------------

### Object-Oriented Resource Operations with aiowebdav

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Demonstrates various operations on a remote resource using the aiowebdav Resource object. Ensure the client is properly initialized with connection details.

```python
import asyncio
from io import BytesIO
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        res = client.resource('documents/report.pdf')

        # Check existence
        exists = await res.check()
        print(f"Exists: {exists}")  # True

        # Get metadata
        info = await res.info()
        print(info['size'], info['modified'])

        # Rename in its current directory
        await res.rename('final_report.pdf')

        # Move to a different path
        await res.move('archive/final_report.pdf')

        # Copy to another location, returns new Resource
        copy_res = await res.copy('backups/final_report.pdf')
        print(copy_res)  # resource /backups/final_report.pdf

        # Download to a file
        await res.write('/tmp/final_report.pdf')

        # Download into an in-memory buffer
        buf = BytesIO()
        await res.write_to(buf)

        # Upload from a file path (read = upload)
        await res.read('/tmp/new_version.pdf')

        # Upload from a buffer (read_from = upload from buffer)
        buf.seek(0)
        await res.read_from(buf)

        # Get a specific subset of metadata
        partial = await res.info(params=['name', 'size'])
        print(partial)  # {'name': 'final_report.pdf', 'size': '204800'}

        # Set a custom property via Resource
        await res.set_property(
            option={'namespace': 'https://myapp.example.com/', 'name': 'reviewed'},
            value='true'
        )

        # Delete the resource
        await res.clean()

asyncio.run(main())
```

--------------------------------

### mkdir

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Creates a new directory on the WebDAV server.

```APIDOC
## mkdir

### Description
Creates a new directory on the WebDAV server at the specified path.

### Method
`mkdir(path: str)`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path for the new directory to be created.

### Request Example
```python
await client.mkdir("dir1/dir2")
```
```

--------------------------------

### List Resources in a Directory

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Asynchronously list resources within a directory. Optionally, retrieve detailed information for each resource by setting `get_info=True`.

```python
# Get a list of resources

files1 = await client.list()
files2 = await client.list("dir1")
files3 = await client.list("dir1", get_info=True) # returns a list of dictionaries with files details
```

--------------------------------

### Configure Speed Limits and Verbose Mode

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Set data transfer speed limits for downloads and uploads, and enable verbose mode for detailed logging. Defaults are unlimited speed and verbose off.

```python
options = {
 ...
 'recv_speed' : 3000000,
 'send_speed' : 3000000,
 'verbose'    : True
}
client = Client(options)
```

--------------------------------

### Download Resource with aiowebdav

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Use the download method to retrieve resources from the remote server to a local path. Supports downloading files and directories.

```python
await client.download(remote_path="dir1/file1", local_path="~/Downloads/file1")
await client.download(remote_path="dir1/dir2/", local_path="~/Downloads/dir2/")
```

--------------------------------

### client.sync

Source: https://context7.com/synodriver/aiowebdav/llms.txt

`await client.sync(remote_directory, local_directory)` performs a full bidirectional sync by calling `pull` then `push` in sequence — first downloading remote changes locally, then uploading local changes to the server.

```APIDOC
## client.sync — Bidirectional Synchronization

`await client.sync(remote_directory, local_directory)` performs a full bidirectional sync by calling `pull` then `push` in sequence — first downloading remote changes locally, then uploading local changes to the server.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        await client.sync(
            remote_directory='team/shared/',
            local_directory='/home/alice/shared/'
        )
        print("Bidirectional sync complete")

asyncio.run(main())
```
```

--------------------------------

### free

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Checks the amount of free space available on the WebDAV server.

```APIDOC
## free

### Description
Checks and returns the amount of free space available on the WebDAV server.

### Method
`free()`

### Response
#### Success Response
- **free_size** (int) - The amount of free space in bytes.
```

--------------------------------

### Advanced Client Configuration Options

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Configure the aiowebdav client with advanced options like custom root path, timeouts, SSL contexts, proxy support, speed limits, and method overrides. Authentication can also be done via OAuth2 bearer token.

```python
import asyncio
import ssl
from aiowebdav.client import Client

ssl_ctx = ssl.create_default_context()

options = {
    'webdav_hostname':         'https://webdav.example.com',
    'webdav_login':            'alice',
    'webdav_password':         'secret1234',
    # OAuth2 bearer token (replaces login/password auth)
    # 'webdav_token':          'my-oauth2-token',
    'webdav_root':             '/dav/',          # custom root path on server
    'webdav_timeout':          60,               # seconds (int or float)
    'webdav_ssl':              ssl_ctx,          # ssl.SSLContext instance
    'webdav_proxy':            'http://proxy.corp:8080',
    'webdav_proxy_auth':       'proxy-token',
    'recv_speed':              3_000_000,        # bytes/sec download cap
    'send_speed':              3_000_000,        # bytes/sec upload cap
    'chunk_size':              131072,           # download/upload chunk size
    'verbose':                 True,
    'disable_check':           False,            # set True if server lacks HEAD
    'webdav_override_methods': {'check': 'GET'}, # override per-action HTTP verb
}

async def main():
    async with Client(options) as client:
        print(client.webdav.hostname)  # 'https://webdav.example.com'
        print(client.webdav.root)      # '/dav'

asyncio.run(main())
```

--------------------------------

### client.get_property / client.set_property / client.set_property_batch

Source: https://context7.com/synodriver/aiowebdav/llms.txt

`await client.get_property(remote_path, option)` retrieves a named XML property from a resource. `await client.set_property(remote_path, option)` sets a single property. `await client.set_property_batch(remote_path, option)` sets multiple properties in one `PROPPATCH` request.

```APIDOC
## client.get_property / client.set_property — Custom WebDAV Properties

`await client.get_property(remote_path, option)` retrieves a named XML property from a resource. `await client.set_property(remote_path, option)` sets a single property. `await client.set_property_batch(remote_path, option)` sets multiple properties in one `PROPPATCH` request.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        # Set a custom metadata property
        await client.set_property(
            remote_path='documents/report.pdf',
            option={'namespace': 'https://myapp.example.com/', 'name': 'author', 'value': 'Alice'}
        )

        # Read it back
        value = await client.get_property(
            remote_path='documents/report.pdf',
            option={'namespace': 'https://myapp.example.com/', 'name': 'author'}
        )
        print(value)  # Alice

        # Set multiple properties at once
        await client.set_property_batch(
            remote_path='documents/report.pdf',
            option=[
                {'namespace': 'https://myapp.example.com/', 'name': 'author',  'value': 'Alice'},
                {'namespace': 'https://myapp.example.com/', 'name': 'version', 'value': '2'},
            ]
        )

asyncio.run(main())
```
```

--------------------------------

### Upload Single File with Force Directory Creation

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Use `client.upload_file` to upload a single local file. Set `force=True` to automatically create any missing parent directories on the remote server.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        # force=True creates remote parent directories as needed
        await client.upload_file(
            remote_path='deep/nested/path/report.pdf',
            local_path='/tmp/report.pdf',
            force=True
        )
        print("Uploaded with auto-created parents")

asyncio.run(main())
```

--------------------------------

### Configure Proxy Settings

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Specify proxy server details for connecting to the WebDAV server. This includes the proxy URL and optional authentication.

```python
from aiowebdav.client import Client

options = {
 'webdav_hostname': "https://webdav.server.ru",
 'webdav_login': "w_login",
 'webdav_password': "w_password",
 'webdav_proxy': "http://127.0.0.1:8080",
 'webdav_proxy_auth': "xxx",
}
client = Client(options)
```

--------------------------------

### Copy Resource with aiowebdav

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Use the copy method to duplicate resources from one path to another. Supports copying files and directories.

```python
await client.copy(remote_path_from="dir1/file1", remote_path_to="dir2/file1")
await client.copy(remote_path_from="dir2", remote_path_to="dir3")
```

--------------------------------

### Check Free Space on Server

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Asynchronously check the available free space on the WebDAV server. This returns the free space size.

```python
# Check free space

free_size = await client.free()
```

--------------------------------

### client.publish / client.unpublish

Source: https://context7.com/synodriver/aiowebdav/llms.txt

`await client.publish(path)` and `await client.unpublish(path)` send `PROPPATCH` requests to toggle the public sharing state of a resource (supported by some servers such as Yandex Disk).

```APIDOC
## client.publish / client.unpublish — Publish Resources

`await client.publish(path)` and `await client.unpublish(path)` send `PROPPATCH` requests to toggle the public sharing state of a resource (supported by some servers such as Yandex Disk).

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'https://webdav.yandex.ru',
                       'webdav_login': 'user', 'webdav_password': 'pass'}) as client:
        # Make a file publicly accessible
        await client.publish('documents/public_report.pdf')

        # Revoke public access
        await client.unpublish('documents/public_report.pdf')

asyncio.run(main())
```
```

--------------------------------

### Move Resource with aiowebdav

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Use the move method to relocate resources from one path to another. Supports moving files and directories.

```python
await client.move(remote_path_from="dir1/file1", remote_path_to="dir2/file1")
await client.move(remote_path_from="dir2", remote_path_to="dir3")
```

--------------------------------

### Resource Object Operations

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Demonstrates various operations that can be performed on a `Resource` object, such as checking existence, retrieving metadata, renaming, moving, copying, downloading, uploading, and deleting.

```APIDOC
## Resource Object Operations

This section details the methods available on a `Resource` object obtained via `client.resource(remote_path)`.

### `check()`

Checks if the remote resource exists.

- **Returns**: `True` if the resource exists, `False` otherwise.

### `info(params=None)`

Retrieves metadata for the resource.

- **Parameters**:
  - `params` (list, optional): A list of property names (e.g., ['name', 'size']) to retrieve. If None, all available properties are fetched.
- **Returns**: A dictionary containing the resource's metadata.

### `rename(new_name)`

Renames the resource within its current directory.

- **Parameters**:
  - `new_name` (str): The new name for the resource.

### `move(new_path)`

Moves the resource to a new path.

- **Parameters**:
  - `new_path` (str): The destination path for the resource.
- **Returns**: A new `Resource` object representing the moved resource.

### `copy(new_path)`

Copies the resource to a new location.

- **Parameters**:
  - `new_path` (str): The destination path for the copy.
- **Returns**: A new `Resource` object representing the copied resource.

### `write(local_path)`

Downloads the remote resource to a local file path.

- **Parameters**:
  - `local_path` (str): The path to the local file where the content will be written.

### `write_to(buffer)`

Downloads the remote resource into an in-memory buffer.

- **Parameters**:
  - `buffer` (io.BytesIO): The buffer to write the content into.

### `read(local_path)`

Uploads content from a local file path to the remote resource.

- **Parameters**:
  - `local_path` (str): The path to the local file to upload.

### `read_from(buffer)`

Uploads content from an in-memory buffer to the remote resource.

- **Parameters**:
  - `buffer` (io.BytesIO): The buffer containing the content to upload.

### `set_property(option, value)`

Sets a custom property on the resource.

- **Parameters**:
  - `option` (dict): A dictionary specifying the property namespace and name (e.g., `{'namespace': 'https://myapp.example.com/', 'name': 'reviewed'}`).
  - `value` (str): The value to set for the property.

### `clean()`

Deletes the remote resource.
```

--------------------------------

### Upload File or Directory with client.upload

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Use `client.upload` to upload a local file or recursively upload a directory. Supports an optional progress callback for tracking upload status.

```python
import asyncio
from aiowebdav.client import Client

def on_progress(current, total, label):
    if total:
        print(f"\r{label} {current}/{total} bytes", end='', flush=True)

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        # Upload a file with progress tracking
        await client.upload(
            remote_path='backups/data.zip',
            local_path='/home/alice/data.zip',
            progress=on_progress,
            progress_args=('data.zip',)
        )
        print()

        # Upload an entire local folder recursively
        await client.upload(
            remote_path='projects/myapp/',
            local_path='/home/alice/myapp/'
        )

asyncio.run(main())
```

--------------------------------

### Handling WebDAV Exceptions with aiowebdav

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Illustrates how to catch specific WebDAV exceptions for robust error handling during file operations. Import necessary exceptions from aiowebdav.exceptions.

```python
import asyncio
from aiowebdav.client import Client
from aiowebdav.exceptions import (
    WebDavException,
    NoConnection,
    ConnectionException,
    RemoteResourceNotFound,
    RemoteParentNotFound,
    LocalResourceNotFound,
    MethodNotSupported,
    ResponseErrorCode,
    NotEnoughSpace,
    ResourceLocked,
    OptionNotValid,
)

async def main():
    options = {'webdav_hostname': 'http://localhost:8585',
               'webdav_login': 'alice', 'webdav_password': 'secret1234'}

    async with Client(options) as client:
        try:
            await client.upload_file(
                remote_path='uploads/data.csv',
                local_path='/tmp/data.csv'
            )
        except NoConnection as e:
            print(f"Cannot reach server: {e}")
        except NotEnoughSpace:
            print("Server disk is full")
        except ResourceLocked as e:
            print(f"Resource is locked: {e}")
        except RemoteParentNotFound as e:
            print(f"Parent directory missing: {e}")
        except RemoteResourceNotFound as e:
            print(f"Resource not found: {e}")
        except LocalResourceNotFound as e:
            print(f"Local file missing: {e}")
        except MethodNotSupported as e:
            print(f"Server does not support this method: {e}")
        except ResponseErrorCode as e:
            print(f"HTTP error {e.code} from {e.url}: {e.message}")
        except OptionNotValid as e:
            print(f"Bad option: {e}")
        except WebDavException as e:
            print(f"Generic WebDAV error: {e}")

asyncio.run(main())
```

--------------------------------

### Check if Resource is Directory with client.is_dir

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Uses PROPFIND with Depth: 0 to determine if a resource is a directory or a file. Raises RemoteResourceNotFound if the path does not exist.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        print(await client.is_dir('documents/'))      # True
        print(await client.is_dir('documents/report.pdf'))  # False

asyncio.run(main())
```

--------------------------------

### list

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Lists resources within a specified directory.

```APIDOC
## list

### Description
Lists the resources (files and directories) within a specified directory on the WebDAV server.

### Method
`list(path: str = None, get_info: bool = False)`

### Parameters
#### Path Parameters
- **path** (string) - Optional - The path to the directory to list. If not provided, lists the root directory.
#### Query Parameters
- **get_info** (boolean) - Optional - If True, returns a list of dictionaries with detailed information about each resource. Defaults to False.

### Request Example
```python
files1 = await client.list()
files2 = await client.list("dir1")
files3 = await client.list("dir1", get_info=True)
```
```

--------------------------------

### Copy Remote Resource with aiowebdav Client

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Use `client.copy` to copy files or directories. For directories, `depth` controls recursive copying (default is 1).

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        # Copy a file
        await client.copy(
            remote_path_from='documents/report.pdf',
            remote_path_to='backups/report_backup.pdf'
        )

        # Copy a directory tree (depth controls nesting)
        await client.copy(
            remote_path_from='documents/',
            remote_path_to='documents_copy/',
            depth=10
        )

asyncio.run(main())
```

--------------------------------

### client.download_from

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Streams a remote file directly into a writable buffer object, supporting both synchronous IO and asynchronous write buffers. Ideal for in-memory processing.

```APIDOC
## client.download_from — Download into a Buffer

`await client.download_from(buff, remote_path, progress=None, progress_args=())` streams a remote file into any writable buffer object (supports both sync `IO` and async `AsyncWriteBuffer`). Useful for in-memory processing without writing to disk.

### Method
GET

### Endpoint
[remote_path]

### Parameters
#### Path Parameters
- **buff** (writable buffer) - Required - The buffer object to write the downloaded content into.
- **remote_path** (string) - Required - The path of the remote file to download.
#### Query Parameters
- **progress** (callable) - Optional - A callback function to report download progress. It receives `(current_bytes, total_bytes, *progress_args)`.
- **progress_args** (tuple) - Optional - Additional arguments to pass to the `progress` callback.

### Request Example
```python
import asyncio
from io import BytesIO
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        buffer = BytesIO()
        await client.download_from(
            buff=buffer,
            remote_path='documents/config.json'
        )
        buffer.seek(0)
        content = buffer.read()
        print(content.decode())  # {"key": "value", ...}

asyncio.run(main())
```

### Response
#### Success Response (200 OK)
File content is streamed into the provided buffer.
```

--------------------------------

### Upload from Buffer with client.upload_to

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Use `client.upload_to` to upload data directly from a file-like buffer object to a remote path. The parent directory must exist on the server.

```python
import asyncio
from io import BytesIO
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        data = b'{"status": "ok", "version": "1.0"}'
        buffer = BytesIO(data)

        await client.upload_to(
            buff=buffer,
            remote_path='config/status.json'
        )
        print("Uploaded from buffer")

asyncio.run(main())
```

--------------------------------

### Publish Resource with aiowebdav

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Use the publish method to generate a public link for a resource. Returns the generated URL.

```python
link = await client.publish("dir1/file1")
link = await client.publish("dir2")
```

--------------------------------

### client.download

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Downloads a file or recursively downloads an entire directory from the WebDAV server to a local path. Supports an optional progress callback.

```APIDOC
## client.download — Download a File or Directory

`await client.download(remote_path, local_path, progress=None, progress_args=())` downloads a file or recursively downloads an entire directory. An optional `progress` callback receives `(current_bytes, total_bytes, *progress_args)` for each chunk.

### Method
GET

### Endpoint
[remote_path]

### Parameters
#### Path Parameters
- **remote_path** (string) - Required - The path of the remote resource to download.
- **local_path** (string) - Required - The local path where the resource will be saved.
#### Query Parameters
- **progress** (callable) - Optional - A callback function to report download progress. It receives `(current_bytes, total_bytes, *progress_args)`.
- **progress_args** (tuple) - Optional - Additional arguments to pass to the `progress` callback.

### Request Example
```python
# Download a single file with progress
await client.download(
    remote_path='documents/report.pdf',
    local_path='/tmp/report.pdf',
    progress=on_progress,
    progress_args=('report.pdf',)
)

# Download an entire directory recursively
await client.download(
    remote_path='documents/',
    local_path='/tmp/documents/'
)
```

### Response
#### Success Response (200 OK)
File or directory contents are downloaded to the specified local path.
```

--------------------------------

### Move or Rename Remote Resource with aiowebdav Client

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Use `client.move` to move or rename files/directories. Set `overwrite=True` to replace existing destination resources.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        # Rename a file in place
        await client.move(
            remote_path_from='documents/draft.txt',
            remote_path_to='documents/final.txt'
        )

        # Move a directory to a new location, overwriting if it exists
        await client.move(
            remote_path_from='temp/',
            remote_path_to='archive/temp/',
            overwrite=True
        )

asyncio.run(main())
```

--------------------------------

### Bidirectional Synchronization with client.sync

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Perform a full bidirectional sync by calling `pull` then `push` sequentially. This ensures both local and remote directories are up-to-date.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'http://localhost:8585',
                       'webdav_login': 'alice', 'webdav_password': 'secret1234'}) as client:
        await client.sync(
            remote_directory='team/shared/',
            local_directory='/home/alice/shared/'
        )
        print("Bidirectional sync complete")

asyncio.run(main())
```

--------------------------------

### Publish and Unpublish Resources with client.publish/unpublish

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Toggle the public sharing state of a resource using `client.publish` to make it accessible or `client.unpublish` to revoke access. This method sends `PROPPATCH` requests.

```python
import asyncio
from aiowebdav.client import Client

async def main():
    async with Client({'webdav_hostname': 'https://webdav.yandex.ru',
                       'webdav_login': 'user', 'webdav_password': 'pass'}) as client:
        # Make a file publicly accessible
        await client.publish('documents/public_report.pdf')

        # Revoke public access
        await client.unpublish('documents/public_report.pdf')

asyncio.run(main())
```

--------------------------------

### Asynchronous Upload with Callback

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Initiate an asynchronous upload operation using upload_async, passing parameters and a callback function via a dictionary.

```python
kwargs = {
 'remote_path': "dir1/file1",
 'local_path':  "~/Downloads/file1",
 'callback':    callback
}
client.upload_async(**kwargs)

kwargs = {
 'remote_path': "dir1/dir2/",
 'local_path':  "~/Downloads/dir2/",
 'callback':    callback
}
client.upload_async(**kwargs)
```

--------------------------------

### client.list — List Directory Contents

Source: https://context7.com/synodriver/aiowebdav/llms.txt

Lists a remote directory. Can return plain filenames or detailed info dictionaries. Supports recursive listing.

```APIDOC
## client.list — List Directory Contents

Lists a remote directory. When `get_info=False` (default) it returns a list of filenames; when `get_info=True` it returns a list of info dictionaries. Set `recursive=True` to list all nested contents using `Depth: infinity`.

### Method
GET (implicitly via PROPFIND)

### Endpoint
Not applicable (method call on client object)

### Parameters
#### Path Parameters
- **remote_path** (str) - Required - The path to the remote directory.
#### Query Parameters
- **get_info** (bool) - Optional - If True, returns detailed info dictionaries. Defaults to False.
- **recursive** (bool) - Optional - If True, lists contents recursively. Defaults to False.

### Request Example
```python
names = await client.list('documents/')
details = await client.list('documents/', get_info=True)
all_files = await client.list('/', recursive=True)
```

### Response
- **list** (list) - A list of strings (filenames) or dictionaries (resource info) depending on the `get_info` parameter.
```

--------------------------------

### Configure Chunk Size for Downloads

Source: https://github.com/synodriver/aiowebdav/blob/aiowebdav/README.md

Set the chunk size for downloading content. The default chunk size is 65536 bytes.

```python
options = {
 ...
 'chunk_size': 65536
}
client = Client(options)
```