WIP: Patch open, os and os.path builtins

[pjbull]

Right now, libs that use open directly, fspath or just assume paths are strings and can be manipulated don't work with CloudPath objects. (Related issues: #315, #73, #128)

Totally WIP and not sure that we want to introduce and support this, but it may increase compatibility significantly to have the option at least for users to patch the builtin functions.

The biggest limitations are:

• Libs that do any string manipulation manually still will not work (e.g. path = dir + os.sep + file)
• Libs that pass local paths off to compiled code to do IO will still not work
• There are probably lots of other ways that other code can do funky things with paths, so even these patches may not make things work

Other potential todos for this PR:

• Patch the standard lib glob module as well
• Add integration test suite that shows the patches working with libs that did not work previously (pandas has all kinds of formats, rasterio may be interesting, xarray has come up, Pillow may be a common use case)
• Add env var for patching os functions
• override os.fspath to allow returning CloudPath
• Document these methods
• Add full test suite (can we leverage what CPython does for these functions?)
• Document that in Jupyter notebooks you have to do open = patch_open() since open exists as a local in the notebook namespace
• Remove testing script

Curious for your thoughts @jayqi !

---

Experimental instructions

• pip install git+https://github.com/drivendataorg/cloudpathlib@patch-builtins
• Set the environment variable CLOUDPATHLIB_PATCH_OPEN=True before any import call to cloudpathlib
• Experiment with your code that uses open or third-party libraries that use open.
• Report the results in open(cloud_path) acts on cached local file instead of cloud file #128

[github-actions]

🚀 Deployed on https://deploy-preview-322--gallant-agnesi-5f7bb3.netlify.app

[github-actions]

🚀 Deployed on https://deploy-preview-322--gallant-agnesi-5f7bb3.netlify.app

[Copilot]

Pull Request Overview

This PR implements experimental patching of Python builtins (open, os, os.path, and glob) to improve third-party library compatibility with CloudPath objects. The changes allow users to override default Python filesystem functions so they work transparently with CloudPath instances.

• Implements comprehensive patching system for open, os functions, os.path functions, and glob module
• Adds environment variable configuration for automatic patching on import
• Provides context manager support for scoped patching and global patching functions

Reviewed Changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
cloudpathlib/patches.py	Core patching implementation with wrapper functions and context managers
tests/test_patching.py	Comprehensive test suite covering all patching functionality
docs/docs/patching_builtins.ipynb	Documentation notebook with examples and usage patterns
docs/docs/script/patching_builtins.py	Python script version of documentation examples
docs/mkdocs.yml	Documentation configuration update to include patching guide
cloudpathlib/__init__.py	Module exports and environment variable handling for automatic patching
cloudpathlib/cloudpath.py	Support for variadic constructor arguments and improved error handling
cloudpathlib/client.py	CloudPath factory method updated to support variadic arguments
cloudpathlib/exceptions.py	New exception types for patching and file operations
cloudpathlib/http/httppath.py	Constructor updated to support variadic arguments
cloudpathlib/http/httpclient.py	Added _is_file_or_dir method implementation
cloudpathlib/local/localclient.py	Added _is_file_or_dir method implementation
Makefile	Debug test configuration update

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.}

[pjbull]

@jayqi ok, I think that this is finally ready to ship if test suite passes! Let me know if you want to do a review—it's pretty beefy so could do synchronous if easier.

[pjbull]

A few tweaks before shipping

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.8%. Comparing base (1200550) to head (bb1a701).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
cloudpathlib/patches.py	94.0%	11 Missing ⚠️
cloudpathlib/__init__.py	70.0%	3 Missing ⚠️
cloudpathlib/cloudpath.py	80.0%	2 Missing ⚠️
cloudpathlib/local/localclient.py	83.3%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master    #322     +/-   ##
========================================
- Coverage    93.8%   93.8%   -0.1%     
========================================
  Files          26      27      +1     
  Lines        1949    2164    +215     
========================================
+ Hits         1830    2030    +200     
- Misses        119     134     +15     

Files with missing lines	Coverage Δ
cloudpathlib/client.py	88.1% <100.0%> (ø)
cloudpathlib/exceptions.py	100.0% <100.0%> (ø)
cloudpathlib/http/httpclient.py	92.8% <100.0%> (+1.1%)	⬆️
cloudpathlib/http/httppath.py	98.8% <100.0%> (ø)
cloudpathlib/local/localclient.py	89.7% <83.3%> (-0.4%)	⬇️
cloudpathlib/cloudpath.py	94.4% <80.0%> (-0.5%)	⬇️
cloudpathlib/__init__.py	84.6% <70.0%> (-9.2%)	⬇️
cloudpathlib/patches.py	94.0% <94.0%> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.