scitex_path

scitex-path: Scientific project path utilities (find, split, symlink, versioning).

scitex_path.clean(path_string)

Cleans and normalizes a file system path string.

Example

>>> 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'

Parameters:

path_string (str) – File path to clean

Returns:

Normalized path string

Return type:

str

scitex_path.create_relative_symlink(src, dst, overwrite=False)

Create a relative symbolic link.

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

Parameters:

• src (Union[str, Path]) – Source path (target of the symlink)

• dst (Union[str, Path]) – Destination path (the symlink to create)

• overwrite (bool) – If True, remove existing dst before creating symlink

Return type:

Path

Returns:

Path object of the created symlink

scitex_path.find_dir(root_dir, exp)

Find directories matching pattern.

Return type:

List[str]

scitex_path.find_file(root_dir, exp)

Find files matching pattern.

Return type:

List[str]

scitex_path.find_git_root()

Find the root directory of the current git repository.

Returns:

Path to the git repository root.

Return type:

str

scitex_path.find_latest(dirname, fname, ext, version_prefix='_v')

Find the latest versioned file in a directory.

Parameters:

• dirname (str) – Directory to search in.

• fname (str) – Base filename without version number or extension.

• ext (str) – File extension including the dot (e.g., ‘.txt’).

• version_prefix (str, optional) – Prefix before the version number. Default is ‘_v’.

Returns:

Path to the latest versioned file, or None if not found.

Return type:

str or None

scitex_path.fix_broken_symlinks(directory, recursive=False, remove=False, new_target=None)

Find and optionally fix broken symbolic links.

Parameters:

• directory (Union[str, Path]) – Directory to search

• recursive (bool) – If True, search recursively

• remove (bool) – If True, remove broken symlinks

• new_target (Union[str, Path, None]) – If provided, repoint broken symlinks to this target

Return type:

dict

Returns:

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

scitex_path.get_data_path_from_a_package(package_str, resource)

Get the path to a data file within a package.

Parameters:

• package_str (str) – The name of the package as a string.

• resource (str) – The name of the resource file within the package’s data directory.

Returns:

The full path to the resource file.

Return type:

Path

Raises:

• ImportError – If the specified package cannot be found.

• FileNotFoundError – If the resource file does not exist in the package’s data directory.

scitex_path.get_spath(sfname, makedirs=False)

Create a save path based on the calling script’s location.

Parameters:

• sfname (str or Path) – The name of the file to be saved.

• makedirs (bool, optional) – If True, create the directory structure for the save path.

Returns:

The full save path for the file.

Return type:

str

Example

>>> spath = mk_spath('output.txt', makedirs=True)

scitex_path.get_this_path(ipython_fake_path='/tmp/fake.py')

Get the path of the calling script.

Note

This function historically captures the caller’s filename via inspect.stack()[1] but then returns this module’s __file__. The tests codify that legacy behavior; do not change without updating callers.

Return type:

str

scitex_path.getsize(path)

Get file size in bytes.

Parameters:

path (str or Path) – Path to file.

Returns:

File size in bytes, or math.nan if file doesn’t exist.

Return type:

int or float

Raises:

PermissionError – If the file cannot be accessed due to permissions.

scitex_path.increment_version(dirname, fname, ext, version_prefix='_v')

Generate the next version of a filename based on existing versioned files.

Parameters:

• dirname (str) – Directory to search in.

• fname (str) – Base filename without version number or extension.

• ext (str) – File extension including the dot (e.g., ‘.txt’).

• version_prefix (str, optional) – Prefix before the version number. Default is ‘_v’.

Returns:

Full path for the next version of the file.

Return type:

str

Example

>>> increment_version('/path/to/dir', 'myfile', '.txt')
'/path/to/dir/myfile_v001.txt'

scitex_path.is_symlink(path)

Check if a path is a symbolic link.

Parameters:

path (Union[str, Path]) – Path to check

Return type:

bool

Returns:

True if path is a symlink, False otherwise

scitex_path.list_symlinks(directory, recursive=False)

List all symbolic links in a directory.

Parameters:

• directory (Union[str, Path]) – Directory to search

• recursive (bool) – If True, search recursively

Return type:

list[Path]

Returns:

List of Path objects for all symlinks found

scitex_path.mk_spath(sfname, makedirs=False)

Create a save path based on the calling script’s location.

Parameters:

• sfname (str or Path) – The name of the file to be saved.

• makedirs (bool, optional) – If True, create the directory structure for the save path.

Returns:

The full save path for the file.

Return type:

str

Example

>>> spath = mk_spath('output.txt', makedirs=True)

scitex_path.readlink(path)

Return the path to which the symbolic link points.

Parameters:

path (Union[str, Path]) – Symlink path to read

Return type:

Path

Returns:

Path object pointing to the symlink target

Raises:

OSError – If path is not a symlink

scitex_path.resolve_symlinks(path)

Resolve all symbolic links in a path.

Parameters:

path (Union[str, Path]) – Path potentially containing symlinks

Return type:

Path

Returns:

Fully resolved absolute path

scitex_path.split(fpath)

Split a file path into directory, filename, and extension.

Parameters:

fpath (str or Path) – File path to split.

Returns:

(directory with trailing slash, filename without extension, extension)

Return type:

tuple of (str, str, str)

Example

>>> dirname, fname, ext = split('/path/to/file.txt')
>>> dirname
'/path/to/'
>>> fname
'file'
>>> ext
'.txt'

scitex_path.symlink(src, dst, overwrite=False, target_is_directory=None, relative=False)

Create a symbolic link pointing to src named dst.

Parameters:

• src (Union[str, Path]) – Source path (target of the symlink)

• dst (Union[str, Path]) – Destination path (the symlink to create)

• overwrite (bool) – If True, remove existing dst before creating symlink

• target_is_directory (Optional[bool]) – On Windows, specify if target is directory (auto-detected if None)

• relative (bool) – If True, create relative symlink instead of absolute

Return type:

Path

Returns:

Path object of the created symlink

Raises:

• FileExistsError – If dst exists and overwrite=False

• FileNotFoundError – If src doesn’t exist

• OSError – If symlink creation fails

Examples

>>> from scitex_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)

scitex_path.this_path(ipython_fake_path='/tmp/fake.py')

Get the path of the calling script.

Note

This function historically captures the caller’s filename via inspect.stack()[1] but then returns this module’s __file__. The tests codify that legacy behavior; do not change without updating callers.

Return type:

str

scitex_path.unlink_symlink(path, missing_ok=True)

Remove a symbolic link.

Parameters:

• path (Union[str, Path]) – Symlink to remove

• missing_ok (bool) – 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