Install & Compatibility
Where this runs
tested against v1.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.052s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.046s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
this_dir
✓ from locate import this_dir
✗ import locate; locate.this_dir()
While `locate.this_dir()` might work, it's generally best practice to directly import `this_dir` as the primary public interface. Versions prior to 1.1.2 could trigger `Pylance(reportPrivateImportUsage)` warnings if not directly imported due to `this_dir` not being explicitly listed in `__all__`.
chdir
✓ from locate import chdir
The `chdir` function is designed to be used as a context manager for temporarily changing the current working directory.
This quickstart demonstrates how to use `this_dir()` to get the path of the executing script and how to use the `chdir` context manager to temporarily change the current working directory. The `chdir` context manager ensures the directory is restored automatically upon exiting the `with` block.
import os
from locate import this_dir, chdir
# Get the directory of the current script
current_script_dir = this_dir()
print(f"Current script directory: {current_script_dir}")
# Using the chdir context manager
original_cwd = os.getcwd()
print(f"Original CWD: {original_cwd}")
with chdir(current_script_dir):
print(f"CWD inside context: {os.getcwd()}")
# Perform operations relative to current_script_dir
print(f"CWD after context: {os.getcwd()}") # Should revert to original_cwd
Debug
Known issues
breakingThe 1.1.1 release notes mention a 'deprecation contract from 4.0.0 to 2.0.0'. While ambiguous, this suggests a revised approach to deprecations, potentially leading to breaking changes or feature removals in future major versions (e.g., 2.0.0). Users should review release notes for versions >= 2.0.0 carefully.fixMonitor future major release notes for changes. Pin dependencies to avoid unexpected breaking changes.
affects: <=1.1.1 (for future compatibility)
gotchaWhen using Pylance in VSCode with `locate` versions prior to 1.1.2, you might encounter a `reportPrivateImportUsage` warning if you import `this_dir` via `import locate` and then use `locate.this_dir`. This was due to `this_dir` not being explicitly listed in `__all__`.fixUpgrade to `locate>=1.1.2` or use `from locate import this_dir` for direct import.
affects: <1.1.2
gotchaThe 1.0.0 release introduced `force_relative_location_imports`. Misunderstanding or misusing Python's relative import mechanisms, especially in scripts not run as part of a package or when manipulating `sys.path`, can lead to `ModuleNotFoundError` or unexpected import behavior. This library aims to simplify location, but core Python import rules still apply.fixEnsure a solid understanding of Python's import system, especially when dealing with scripts executed directly vs. as part of a package. Use `python -m my_package.my_module` for package-aware execution.
affects: >=1.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'locate'
The 'locate' library is not installed in the current Python environment or there is a typo in the import statement.
fixInstall the library using pip: `pip install locate`
AttributeError: module 'locate' has no attribute 'this_directory'
The user attempted to call a non-existent or misspelled method 'this_directory' instead of the correct method 'this_dir()'.
fixCorrect the method call to `locate.this_dir()`.
TypeError: locate.relative() missing 1 required positional argument: 'path'
The `locate.relative()` function was called without providing the required 'path' argument.
fixProvide the 'path' argument to the `locate.relative()` function, for example: `locate.relative('my_file.txt')`. Upgrade
Version history
1.1.1latest on PyPI · released Dec 15, 2022
Audit
Dependencies
No dependency data recorded yet.