Skip to content

dbx_patch

source package dbx_patch

Classes

Functions

source check_patch_status() → StatusResult

Check the status of all patches without applying them.

Returns

source remove_all_patches() → RemovePatchesResult

Remove all applied patches and restore original behavior.

Returns

source verify_editable_installs() → VerifyResult

Verify that editable installs are properly configured and can be imported.

Returns

source install_sitecustomize(force: bool = True, restart_python: bool = True) → bool

Install sitecustomize.py to auto-apply patches on Python startup.

This is the RECOMMENDED way to use dbx-patch because

  1. Patches are applied BEFORE sys_path_init runs
  2. Import hooks are patched BEFORE they're installed
  3. No need to manually call patch_dbx() in every notebook
  4. Works automatically for all Python processes on the cluster

Parameters

  • force : bool — If True, overwrite existing sitecustomize.py

  • restart_python : bool — If True, automatically restart Python using dbutils.library.restartPython()

Returns

  • bool — True if installation succeeded, False otherwise

Example

Run once per cluster (e.g., in init script or first notebook):

from dbx_patch.install_sitecustomize import install_sitecustomize install_sitecustomize()

Python will restart automatically if running in Databricks

After restart, editable installs will work automatically!

source uninstall_sitecustomize() → bool

Remove the auto-apply sitecustomize.py.

Returns

  • bool — True if uninstallation succeeded, False otherwise

source check_sitecustomize_status() → SitecustomizeStatus

Check if sitecustomize.py is installed and active.

Returns

source patch_dbx(force_refresh: bool = False) → ApplyPatchesResult

Apply all DBX patches for editable install support.

This is the main entry point that

  1. Processes .pth files to populate sys.path with editable install paths
  2. Patches sys_path_init to auto-process .pth files during initialization
  3. Patches WsfsImportHook to allow imports from editable paths
  4. Patches PythonPathHook to preserve editable paths
  5. Patches AutoreloadDiscoverabilityHook to allow editable imports

This method is optimized to avoid import loops and ensures patches are applied in the correct order with proper error handling.

Parameters

  • force_refresh : bool — If True, force re-detection of editable paths

Returns

Example 

from dbx_patch import patch_dbx
patch_dbx()

# All patches applied, editable installs now work!

source patch_and_install(force: bool = False, restart_python: bool = True) → dict[str, Any]

Apply patches AND install sitecustomize.py for automatic patching on startup.

This is the recommended all-in-one method that

  1. Applies all patches immediately (via patch_dbx)
  2. Installs sitecustomize.py for automatic patching on future Python restarts
  3. Optionally restarts Python to activate sitecustomize.py

Parameters

  • force : bool — If True, overwrite existing sitecustomize.py

  • restart_python : bool — If True, automatically restart Python via dbutils

Returns

  • dict[str, Any] — Dictionary with 'patch_result' and 'install_result' keys

Example 

from dbx_patch import patch_and_install
patch_and_install()

# Patches applied AND sitecustomize.py installed
# Python will restart automatically if in Databricks

source dataclass ApplyPatchesResult(sys_path_init_patch: PatchResult | None, pth_processing: PthProcessingResult | None, wsfs_hook_patch: PatchResult | None, wsfs_path_finder_patch: PatchResult | None, python_path_hook_patch: PatchResult | None, autoreload_hook_patch: PatchResult | None, overall_success: bool, editable_paths: list[str])

Results from applying all patches.

source dataclass PatchResult(success: bool, already_patched: bool, function_found: bool = True, hook_found: bool = True, editable_paths_count: int = 0, editable_paths: list[str] = field(default_factory=list), error: str | None = None)

Generic patch operation result.

source dataclass PthProcessingResult(site_dirs_scanned: int, pth_files_found: int, paths_extracted: list[str], egg_link_paths: list[str], metadata_paths: list[str], paths_added: int, total_editable_paths: int)

Results from processing .pth files.

source dataclass RemovePatchesResult(sys_path_init_unpatched: bool, wsfs_hook_unpatched: bool, wsfs_path_finder_unpatched: bool, python_path_hook_unpatched: bool, autoreload_hook_unpatched: bool, success: bool)

Results from removing all patches.

source dataclass SitecustomizeStatus(installed: bool, path: str | None, is_dbx_patch: bool)

Status of sitecustomize.py installation.

source dataclass StatusResult(sys_path_init_patched: bool, wsfs_hook_patched: bool, wsfs_path_finder_patched: bool, python_path_hook_patched: bool, autoreload_hook_patched: bool, editable_paths_count: int, pth_files_processed: bool)

Current patch status.

source dataclass VerifyResult(editable_paths: list[str], paths_in_sys_path: list[str], wsfs_hook_patched: bool, wsfs_path_finder_patched: bool, python_path_hook_patched: bool, autoreload_hook_patched: bool, importable_packages: list[str], status: str)

Results from verifying editable install configuration.