|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +PyWebDAV3 is a Python 3 implementation of a WebDAV server and library supporting WebDAV levels 1 and 2 (including LOCK/UNLOCK). The project provides both a standalone server (`davserver`) and a library for integrating WebDAV capabilities into applications. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +The codebase is organized into two main packages: |
| 12 | + |
| 13 | +### pywebdav/lib/ - Core WebDAV Library |
| 14 | +- **WebDAVServer.py**: Main DAV request handler class (`DAVRequestHandler`) that inherits from `AuthServer.AuthRequestHandler` and `LockManager`. Implements HTTP methods (GET, HEAD, PUT, OPTIONS, PROPFIND, PROPPATCH, MKCOL, REPORT, LOCK, UNLOCK). |
| 15 | +- **AuthServer.py**: Provides HTTP Basic Authentication layer on top of standard HTTP server. |
| 16 | +- **iface.py**: Abstract interface class (`dav_interface`) that defines the contract for backend data sources. Any custom backend must implement this interface to handle property retrieval, data access, and resource management. |
| 17 | +- **propfind.py, report.py, davcopy.py, davmove.py, delete.py**: Separate classes for each DAV method that handle XML parsing and response generation. |
| 18 | +- **locks.py**: `LockManager` class implementing WebDAV level 2 locking functionality. |
| 19 | +- **utils.py, status.py, errors.py, constants.py**: Utility functions and definitions. |
| 20 | + |
| 21 | +### pywebdav/server/ - Reference Server Implementation |
| 22 | +- **server.py**: Entry point for the standalone server. Includes `runserver()` function and command-line parsing. Installed as `davserver` console script. |
| 23 | +- **fshandler.py**: `FilesystemHandler` class implements the `dav_interface` for serving files from a local filesystem. This serves as the reference implementation for custom backends. |
| 24 | +- **fileauth.py**: `DAVAuthHandler` - authentication handler implementation. |
| 25 | +- **mysqlauth.py**: `MySQLAuthHandler` - optional MySQL-based authentication. |
| 26 | +- **daemonize.py**: Unix daemon support for server. |
| 27 | + |
| 28 | +### Key Architectural Pattern |
| 29 | +The WebDAVServer class requires an interface class (implementing `dav_interface`) to connect to actual data. This separation allows backends for filesystems, databases, or other storage. The interface class is instantiated by WebDAVServer and called for property retrieval, resource creation, data access, etc. XML parsing for each DAV method is factored into dedicated classes (propfind.py, etc.) which obtain data through the interface class. |
| 30 | + |
| 31 | +## Development Commands |
| 32 | + |
| 33 | +### Build and Package |
| 34 | +```bash |
| 35 | +python -m build # Build distribution packages (requires build module) |
| 36 | +twine check dist/* # Validate package format |
| 37 | +``` |
| 38 | + |
| 39 | +### Installation |
| 40 | +```bash |
| 41 | +pip install -e . # Development installation |
| 42 | +pip install PyWebDAV3 # Install from PyPI |
| 43 | +``` |
| 44 | + |
| 45 | +### Running the Server |
| 46 | +```bash |
| 47 | +davserver -D /tmp -n -J # Run server: -D=directory, -n=no auth, -J=no lock |
| 48 | +davserver -D /path -u user -p pass # Run with authentication |
| 49 | +davserver --help # Full options list |
| 50 | +``` |
| 51 | + |
| 52 | +Common options: |
| 53 | +- `-D/--directory`: Root directory to serve (default: /tmp) |
| 54 | +- `-H/--host`: Listen host (default: localhost) |
| 55 | +- `-P/--port`: Port number (default: 8008) |
| 56 | +- `-u/--user`, `-p/--password`: Authentication credentials |
| 57 | +- `-n/--noauth`: Disable authentication |
| 58 | +- `-J/--nolock`: Disable LOCK/UNLOCK (WebDAV level 2) |
| 59 | +- `-M/--nomime`: Disable mimetype sniffing |
| 60 | +- `-T/--noiter`: Disable iterator (fixes some corruption issues) |
| 61 | +- `-v/--verbose`: Verbose output |
| 62 | +- `-l/--loglevel`: Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| 63 | +- `-d/--daemon`: Daemon mode (start|stop|restart|status) |
| 64 | + |
| 65 | +### Testing |
| 66 | +```bash |
| 67 | +python test/test_litmus.py # Run litmus WebDAV compliance tests |
| 68 | +``` |
| 69 | + |
| 70 | +The test suite uses litmus 0.13, a C-based WebDAV server protocol compliance test suite originally by Joe Orton. The test harness (`test/test_litmus.py`) automatically: |
| 71 | +1. Extracts and compiles litmus from `test/litmus-0.13.tar.gz` on first run (`./configure && make`) |
| 72 | +2. Starts a temporary davserver instance on port 38028 |
| 73 | +3. Runs the full litmus test battery via `make check` |
| 74 | +4. Verifies both authenticated (user: test, pass: pass) and non-authenticated modes |
| 75 | + |
| 76 | +#### Litmus Test Suites |
| 77 | +Litmus comprises 5 separate test executables that each verify different WebDAV functionality: |
| 78 | + |
| 79 | +- **basic**: Core WebDAV level 1 operations |
| 80 | + - OPTIONS (DAV: header checking) |
| 81 | + - PUT, GET with byte-level comparison |
| 82 | + - MKCOL (collection creation) |
| 83 | + - DELETE (both collections and non-collections) |
| 84 | + - put_no_parent (error handling) |
| 85 | + |
| 86 | +- **copymove**: COPY and MOVE operations testing all combinations |
| 87 | + - Overwrite true/false |
| 88 | + - Destination exists/doesn't exist |
| 89 | + - Collection/non-collection resources |
| 90 | + - Depth: 0 COPY of collections |
| 91 | + |
| 92 | +- **props**: Property manipulation and querying (PROPFIND, PROPPATCH) |
| 93 | + - Set, delete, replace properties |
| 94 | + - Dead property persistence across COPY |
| 95 | + - Namespace handling |
| 96 | + - Unicode values in property values |
| 97 | + - PROPPATCH propertyupdate evaluation order |
| 98 | + |
| 99 | +- **locks**: WebDAV level 2 locking (LOCK, UNLOCK) |
| 100 | + - Lock/unlock operations |
| 101 | + - Exclusive vs shared locks |
| 102 | + - Lock discovery |
| 103 | + - Attempts to modify locked resources (as owner vs non-owner) |
| 104 | + - PROPPATCH on locked resources |
| 105 | + - Collection locking |
| 106 | + - If: header handling with lock-tokens and etags |
| 107 | + |
| 108 | +- **http**: HTTP protocol-level tests |
| 109 | + - Conditional requests |
| 110 | + - expect100 handling |
| 111 | + - Non-ASCII characters in URIs |
| 112 | + |
| 113 | +Each test adds an `X-Litmus-One` header to requests for debugging. After running, `debug.log` contains full network traces. Tests run against a temporary directory and require ability to create a `litmus` collection at the target URL. |
| 114 | + |
| 115 | +#### Manual Litmus Testing |
| 116 | +To run litmus tests manually for debugging: |
| 117 | +```bash |
| 118 | +cd test/litmus-0.13 |
| 119 | +sh ./configure && make # Compile litmus (one-time) |
| 120 | +davserver -D /tmp/davtest -n & # Start server in background |
| 121 | +make URL=http://localhost:8008/ check # Run all test suites |
| 122 | +make URL=http://localhost:8008/ CREDS="user pass" check # With auth |
| 123 | +./basic http://localhost:8008/ # Run single test suite |
| 124 | +./locks http://localhost:8008/ user pass # Single suite with credentials |
| 125 | +``` |
| 126 | +After tests complete, examine `debug.log` for full request/response traces. |
| 127 | + |
| 128 | +### CI/CD |
| 129 | +GitHub Actions workflow (`.github/workflows/python-package.yml`) runs on push/PR to master: |
| 130 | +- Tests Python 3.8, 3.9, 3.10 |
| 131 | +- Builds package and validates with twine |
| 132 | +- Runs litmus test suite |
| 133 | + |
| 134 | +## Version Management |
| 135 | +Uses `git-versioner` for version numbers from git tags. Version is read from `pywebdav.__version__` which is populated by the versioner. |
| 136 | + |
| 137 | +## Dependencies |
| 138 | +- `six`: Python 2/3 compatibility (maintained for legacy reasons) |
| 139 | +- `git-versioner`: Version management from git tags |
| 140 | + |
| 141 | +Optional: |
| 142 | +- MySQL support requires MySQLdb |
0 commit comments