scitex_core.path

File path and directory utilities for scitex-core.

This module provides comprehensive path manipulation, file/directory search, symbolic link management, and path normalization utilities.

scitex_core.path.find_dir(root_dir, pattern='*')[source]

Find directories matching a pattern.

Parameters:

root_dir (str) – Root directory to start search
pattern (str or list of str, optional) – Pattern(s) to match directory names. Default is “*” (all).

Returns:

List of matching directory paths

Return type:

list of str

Examples

>>> from scitex_core.path import find_dir
>>> dirs = find_dir("/home/user", "test_*")
>>> dirs = find_dir("/home/user", ["src", "lib"])

scitex_core.path.find_file(root_dir, pattern='*')[source]

Find files matching a pattern.

Parameters:

root_dir (str) – Root directory to start search
pattern (str or list of str, optional) – Pattern(s) to match file names. Default is “*” (all).

Returns:

List of matching file paths

Return type:

list of str

Examples

>>> from scitex_core.path import find_file
>>> files = find_file("/home/user", "*.py")
>>> files = find_file("/home/user", ["*.txt", "*.md"])

scitex_core.path.find_git_root(start_path='.')[source]

Find the root directory of a git repository.

Parameters:: start_path (str, optional) – Starting directory for search. Default is current directory.
Returns:: Path to git repository root, or None if not in a git repository
Return type:: str or None

Examples

>>> from scitex_core.path import find_git_root
>>> root = find_git_root()
>>> print(root)  # e.g., '/home/user/my-project'

Notes

This function searches for a .git directory by walking up the directory tree. It does not require the gitpython package.

scitex_core.path.this_path(ipython_fake_path='/tmp/ipython_fake.py')[source]

Get the absolute path of the calling script.

Parameters:: ipython_fake_path (str, optional) – Fallback path to use when running in IPython/Jupyter. Default is “/tmp/ipython_fake.py”
Returns:: Absolute path to the calling script
Return type:: str

Examples

>>> from scitex_core.path import this_path
>>> # In a script at /home/user/scripts/my_script.py:
>>> script_path = this_path()
>>> print(script_path)  # '/home/user/scripts/my_script.py'

>>> # Use it to find files relative to the script
>>> import os
>>> script_dir = os.path.dirname(this_path())
>>> config_path = os.path.join(script_dir, "config.yaml")

Notes

Uses inspect.stack() to get the caller’s filename
Handles IPython/Jupyter environments by returning fake path
Returns the caller’s file path, not this module’s path

scitex_core.path.get_this_path(ipython_fake_path='/tmp/ipython_fake.py')

Get the absolute path of the calling script.

Parameters:: ipython_fake_path (str, optional) – Fallback path to use when running in IPython/Jupyter. Default is “/tmp/ipython_fake.py”
Returns:: Absolute path to the calling script
Return type:: str

Examples

>>> from scitex_core.path import this_path
>>> # In a script at /home/user/scripts/my_script.py:
>>> script_path = this_path()
>>> print(script_path)  # '/home/user/scripts/my_script.py'

>>> # Use it to find files relative to the script
>>> import os
>>> script_dir = os.path.dirname(this_path())
>>> config_path = os.path.join(script_dir, "config.yaml")

Notes

Uses inspect.stack() to get the caller’s filename
Handles IPython/Jupyter environments by returning fake path
Returns the caller’s file path, not this module’s path

scitex_core.path.clean(path_string)[source]

Clean and normalize a file system path string.

Performs the following operations: - Converts Path objects to strings - Replaces spaces with underscores - Normalizes ../ and ./ references - Removes duplicate slashes - Preserves trailing slash for directories

Parameters:: path_string (str or Path) – File path to clean
Returns:: Normalized path string
Return type:: str

Examples

>>> from scitex_core.path import clean
>>> clean('/home/user/./folder/../file.txt')
'/home/user/file.txt'

>>> clean('path/./to//file.txt')
'path/to/file.txt'

>>> clean('path with spaces')
'path_with_spaces'

>>> clean('directory/')
'directory/'

Notes

Empty strings return empty string
Trailing slashes are preserved to indicate directories
Spaces are replaced with underscores for filesystem safety

scitex_core.path.symlink(src, dst, overwrite=False, target_is_directory=None, relative=False)[source]

Create a symbolic link pointing to src named dst.

Parameters:

src (str or Path) – Source path (target of the symlink)
dst (str or Path) – Destination path (the symlink to create)
overwrite (bool, optional) – If True, remove existing dst before creating symlink
target_is_directory (bool, optional) – On Windows, specify if target is directory (auto-detected if None)
relative (bool, optional) – If True, create relative symlink instead of absolute

Returns:

Path object of the created symlink

Return type:

Path

Raises:

FileExistsError – If dst exists and overwrite=False
OSError – If symlink creation fails

Examples

>>> from scitex_core.path import symlink
>>> # Create absolute symlink
>>> symlink("/path/to/source", "/path/to/link")

>>> # Create relative symlink
>>> symlink("../source", "link", relative=True)

>>> # Overwrite existing symlink
>>> symlink("/path/to/new_source", "/path/to/link", overwrite=True)

Notes

Allows creating symlinks to non-existent targets (valid in Unix/Linux)
Automatically creates parent directories if needed
On Windows, may require administrator privileges

scitex_core.path.is_symlink(path)[source]

Check if a path is a symbolic link.

Parameters:: path (str or Path) – Path to check
Returns:: True if path is a symlink, False otherwise
Return type:: bool

Examples

>>> from scitex_core.path import is_symlink
>>> is_symlink("/path/to/link")
False

scitex_core.path.readlink(path)[source]

Return the path to which the symbolic link points.

Parameters:: path (str or Path) – Symlink path to read
Returns:: Path object pointing to the symlink target
Return type:: Path
Raises:: OSError – If path is not a symlink

Examples

>>> from scitex_core.path import readlink
>>> target = readlink("/path/to/link")
>>> print(target)

scitex_core.path.resolve_symlinks(path)[source]

Resolve all symbolic links in a path.

Parameters:: path (str or Path) – Path potentially containing symlinks
Returns:: Fully resolved absolute path
Return type:: Path

Examples

>>> from scitex_core.path import resolve_symlinks
>>> resolved = resolve_symlinks("/path/with/symlinks")
>>> print(resolved)

scitex_core.path.create_relative_symlink(src, dst, overwrite=False)[source]

Create a relative symbolic link.

This is a convenience wrapper around symlink() with relative=True.

Parameters:

src (str or Path) – Source path (target of the symlink)
dst (str or Path) – Destination path (the symlink to create)
overwrite (bool, optional) – If True, remove existing dst before creating symlink

Returns:

Path object of the created symlink

Return type:

Path

Examples

>>> from scitex_core.path import create_relative_symlink
>>> # Create relative symlink from current dir to parent dir file
>>> create_relative_symlink("../data/file.txt", "link_to_file")

scitex_core.path.unlink_symlink(path, missing_ok=True)[source]

Remove a symbolic link.

Parameters:

path (str or Path) – Symlink to remove
missing_ok (bool, optional) – If True, don’t raise error if symlink doesn’t exist

Raises:

FileNotFoundError – If symlink doesn’t exist and missing_ok=False
OSError – If path is not a symlink

Return type:

None

Examples

>>> from scitex_core.path import unlink_symlink
>>> unlink_symlink("/path/to/link")

scitex_core.path.list_symlinks(directory, recursive=False)[source]

List all symbolic links in a directory.

Parameters:

directory (str or Path) – Directory to search
recursive (bool, optional) – If True, search recursively

Returns:

List of Path objects for all symlinks found

Return type:

list of Path

Examples

>>> from scitex_core.path import list_symlinks, readlink
>>> symlinks = list_symlinks("/path/to/dir")
>>> for link in symlinks:
...     print(f"{link} -> {readlink(link)}")

scitex_core.path.fix_broken_symlinks(directory, recursive=False, remove=False, new_target=None)[source]

Find and optionally fix broken symbolic links.

Parameters:

directory (str or Path) – Directory to search
recursive (bool, optional) – If True, search recursively
remove (bool, optional) – If True, remove broken symlinks
new_target (str or Path, optional) – If provided, repoint broken symlinks to this target

Returns:

Dictionary with ‘found’, ‘fixed’, and ‘removed’ lists of paths

Return type:

dict

Examples

>>> from scitex_core.path import fix_broken_symlinks
>>> # Find broken symlinks
>>> result = fix_broken_symlinks("/path/to/dir")
>>> print(f"Found {len(result['found'])} broken symlinks")

>>> # Remove broken symlinks
>>> result = fix_broken_symlinks("/path/to/dir", remove=True)