WebDAV4 Client Library

Common errors

• ModuleNotFoundError: No module named 'webdav'

  cause Attempting to import the old package name, `webdav`, which was renamed to `webdav4` in version 0.10.0.
  fix Run `pip install webdav4` and change all `import webdav` statements to `import webdav4` (or specific submodules like `from webdav4.client import WebdavClient`).

• webdav4.exceptions.WebdavError: 401 Unauthorized

  cause Incorrect or missing authentication credentials (username/password), or the WebDAV server requires a different authentication method not correctly provided.
  fix Double-check the `username` and `password` values passed to `WebdavFS` or `WebdavClient`. Ensure the URL is correct and includes the proper path to the WebDAV resource. Some complex setups might require specific `auth` parameters for `WebdavClient`.

• ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate

  cause The WebDAV server is using an SSL certificate that cannot be verified by your system's trusted CAs, typically a self-signed certificate.
  fix If connecting to a server with a self-signed or untrusted certificate for development/testing, add `verify=False` to the `WebdavClient` or `WebdavFS` constructor, e.g., `WebdavFS(url=..., username=..., password=..., verify=False)`.

• FileNotFoundError: /path/to/nonexistent/file (or directory)

  cause The specified file or directory path does not exist on the WebDAV server, or there's a case-sensitivity mismatch.
  fix Verify the exact path and case sensitivity of the file/directory on the WebDAV server. Use methods like `fs.ls('/')` to inspect available paths and ensure the target exists before attempting operations like `open`, `cat`, or `rm`.

Warnings

• breaking The package name was changed from `webdav` to `webdav4` starting with version 0.10.0. Projects using `import webdav` will fail with a `ModuleNotFoundError`.
  Fix: Uninstall the old package (`pip uninstall webdav` if installed), install the new one (`pip install webdav4`), and update all import statements to use `webdav4` (e.g., `from webdav4.client import WebdavClient`).
• breaking The constructor signatures for `WebdavClient` and `WebdavFS` underwent significant changes in version 0.10.0. Specifically, `WebdavClient` now uses `base_url` instead of `url`, and the handling of authentication arguments has been refactored.
  Fix: Review the latest documentation for `WebdavClient` and `WebdavFS` constructor arguments. For `WebdavFS`, pass the full URL to `url` and credentials directly as `username` and `password`. For `WebdavClient`, use `base_url` and `username`/`password`.
• gotcha Connecting to WebDAV servers with self-signed SSL certificates or untrusted Certificate Authorities (CAs) will cause `ssl.SSLCertVerificationError` by default due to strict certificate validation.
  Fix: To bypass certificate verification (use with caution and only for development/testing), pass `verify=False` to the `WebdavClient` or `WebdavFS` constructor, e.g., `WebdavFS(url=..., username=..., password=..., verify=False)`.
• gotcha When using `fsspec` directly to create a filesystem, ensure you use the `webdav` or `webdavs` protocol handler. The `url` parameter for direct `WebdavFS` instantiation expects `http://` or `https://` URLs, but `fsspec.open` expects `webdav://` or `webdavs://`.
  Fix: For direct `WebdavFS` instantiation, use `WebdavFS(url='https://example.com/webdav/')`. For `fsspec.filesystem` or `fsspec.open`, use `fsspec.filesystem('webdav', url='webdavs://example.com/webdav/')` or `fsspec.open('webdavs://example.com/webdav/path/to/file', ...)`. Note that `fsspec.filesystem` often expects an `url` argument, but it's used for the *fsspec* URL, not the base_url.

Install

• pip install webdav4 Install webdav4

Imports

• WebdavClient
  wrong:

  from webdav.client import WebdavClient

  correct:

  from webdav4.client import WebdavClient

  The library was renamed from `webdav` to `webdav4` in version 0.10.0. The old package name is no longer maintained and will result in `ModuleNotFoundError`.
• WebdavFS
  wrong:

  from webdav.fs import WebdavFS

  correct:

  from webdav4.fs import WebdavFS

  The library was renamed from `webdav` to `webdav4` in version 0.10.0. The old package name is no longer maintained and will result in `ModuleNotFoundError`.

Quickstart

This quickstart demonstrates how to initialize `WebdavFS`, list directory contents, create a new directory, and write/read a file. Remember to replace placeholder credentials with your actual WebDAV server details or set them as environment variables. SSL verification might need to be disabled for servers with self-signed certificates.

import os
from webdav4.fs import WebdavFS

# Replace with your WebDAV server details or set as environment variables
WEBDAV_URL = os.environ.get('WEBDAV_URL', 'http://localhost:8000/webdav/')
WEBDAV_USER = os.environ.get('WEBDAV_USER', 'user')
WEBDAV_PASS = os.environ.get('WEBDAV_PASS', 'password')

if not all([WEBDAV_URL, WEBDAV_USER, WEBDAV_PASS]):
    print("Please set WEBDAV_URL, WEBDAV_USER, WEBDAV_PASS environment variables or update the script.")
    exit(1)

try:
    # Initialize WebdavFS
    # For self-signed certificates or HTTP, you might need to add verify=False
    fs = WebdavFS(
        url=WEBDAV_URL,
        username=WEBDAV_USER,
        password=WEBDAV_PASS,
        # verify=False # Uncomment if you have SSL certificate issues
    )

    print(f"Connecting to WebDAV server: {WEBDAV_URL}")

    # List contents of the root directory
    print(f"Listing contents of '/':")
    for item in fs.ls('/', detail=True):
        print(f"  - {item['name']} (Type: {item['type']}, Size: {item.get('size', 'N/A')})")

    # Example: Create a directory
    test_dir_name = 'my_test_dir_webdav4'
    if not fs.exists(test_dir_name):
        fs.mkdir(test_dir_name)
        print(f"Successfully created directory: {test_dir_name}")
    else:
        print(f"Directory '{test_dir_name}' already exists.")

    # Example: Write and read a file
    test_file_path = f'{test_dir_name}/hello.txt'
    file_content = 'Hello, WebDAV4!'

    with fs.open(test_file_path, 'wb') as f:
        f.write(file_content.encode('utf-8'))
    print(f"Wrote content to {test_file_path}")

    with fs.open(test_file_path, 'rb') as f:
        read_content = f.read().decode('utf-8')
    print(f"Read content from {test_file_path}: '{read_content}'")

    # Clean up (optional)
    # fs.rm(test_file_path)
    # print(f"Removed file: {test_file_path}")
    # fs.rmdir(test_dir_name)
    # print(f"Removed directory: {test_dir_name}")

except Exception as e:
    print(f"\nAn error occurred: {e}")
    print("Please ensure the WebDAV server is running and accessible, ")
    print("and that WEBDAV_URL, WEBDAV_USER, WEBDAV_PASS environment variables are set correctly.")
    print("If you are facing SSL issues, try adding `verify=False` to the WebdavFS constructor.")