Requests-File

Requests-File plugs into the Python requests library’s transport-adapter system so that a Session mounted with FileAdapter() can serve file:// URLs alongside normal HTTP(S) requests. It translates local filesystem access into a Response object: file contents become the response body, a Content-Length header is set when possible, and common IOError conditions are mapped onto familiar HTTP status codes (403 for permission errors, 404 for missing files, 400 for anything else).

The library is intentionally tiny — a single module wrapping os/io calls behind the Requests adapter interface — and is most often pulled in as a small compatibility shim by tools that already use requests and want to accept local file paths and remote URLs through the same code path (Selenium bindings and several URL-fetching CLIs use it this way). Development has slowed to occasional maintenance releases; the maintainer moved the canonical repository to Codeberg, though the GitHub mirror used here still reflects the released history.

What You Get

• FileAdapter class implementing requests.adapters.BaseAdapter, mountable via session.mount('file://', FileAdapter())
• Automatic translation of EACCES/ENOENT/other IOErrors into 403/404/400 HTTP status codes
• Optional Content-Length header population based on the file’s size on disk
• Cross-platform path handling, including Windows drive-letter URLs (file:///C:/path)

Common Use Cases

• Letting a requests-based client accept both http(s):// and file:// inputs through one unified interface
• Testing HTTP client code against local fixture files without spinning up a server
• Supporting local-file fallback in CLIs and libraries that fetch resources by URL
• Browser-automation and scraping tools (e.g. Selenium-adjacent tooling) that need to load local pages via requests

Under The Hood

Architecture - The entire library is one module, requests_file.py, defining FileAdapter(BaseAdapter). Its send() method parses the incoming PreparedRequest’s URL with urlparse, reconstructs an OS-appropriate filesystem path (including handling Windows drive letters encoded as /C:/... or legacy /C|/...), opens the file with io.open, and attaches the raw file handle to a requests.Response object so the rest of the Requests API (.text, .content, streaming) works unmodified. close() is a no-op since there is no real network connection to tear down.

Tech Stack - Pure Python standard library plus a single runtime dependency, requests>=1.0.0; packaged with setuptools + setuptools_scm for git-tag-based versioning (pyproject.toml), no compiled extensions or heavy dependencies.

Code Quality - tests/test_requests_file.py (197 lines) covers the main behaviors: successful reads, missing files, permission errors, Windows-style paths, and header behavior. The code itself is a single small file with clear docstrings and no notable complexity, though it still carries Python-2-era compatibility shims (try/except ImportError around BytesIO) reflecting its age.

API Design - The API surface is exactly one class with one meaningful constructor flag (set_content_length), following the exact adapter-mounting convention Requests users already know (session.mount(scheme, adapter)), so there is effectively zero learning curve for anyone already using requests.