pathnavigator package

Submodules

pathnavigator.att_name_convertor module

class pathnavigator.att_name_convertor.AttributeNameConverter(_pn_org_to_valid_name=<factory>, _pn_valid_name_to_org=<factory>, _pn_invalid_name_list=<factory>)

Bases: Base

A class to convert original names to valid attribute names and store the mapping.

to_valid_name(name)

Convert the original name to a valid attribute name.

get(name)

Get the valid attribute name for the given original name.

get_org(name)

Get the valid attribute name for the given original name.

Parameters:

name (str) – The original name to get the valid attribute name for.

Return type:

str

get_valid(name)

Get the valid attribute name for the given original name.

Parameters:

name (str) – The original name to get the valid attribute name for.

Return type:

str

remove(name)

Remove the mapping for the given name.

Parameters:

name (str) – The original name to remove from the mapping.

to_valid_name(name)

Convert the original name to a valid attribute name.

Parameters:

name (str) – The original name to convert.

Return type:

str

update_invalid_name_list(invalid_name_list)

Update the list of invalid names.

Parameters:

invalid_name_list (list) – The list of invalid names to update.

pathnavigator.folder module

class pathnavigator.folder.Folder(name, parent_path, subfolders=<factory>, files=<factory>, _pn_object=None, _pn_converter=<factory>, _pn_current_depth=0)

Bases: Base

A class to represent a folder in the filesystem and manage subfolders and files.

name

The name of the folder.

Type:

str

parent_path

The path of the parent folder.

Type:

str

subfolders

A dictionary of subfolder names (keys) and Folder objects (values).

Type:

dict

files

A dictionary of file names (keys) and their paths (values).

Type:

dict

_pn_object

The PathNavigator object that this folder belongs to.

Type:

object

_pn_converter

The AttributeNameConverter object for converting attribute names.

Type:

object

add_to_sys_path(method='insert', index=1)

Adds the directory to the system path.

Parameters:

  • method (str, optional) – The method to use for adding the path to the system path. Options are ‘insert’ (default) or ‘append’.

  • index (int, optional) – The index at which to insert the path if method is ‘insert’. Default is 1.

Raises:

ValueError – If the method is not ‘insert’ or ‘append’.

Examples

>>> folder = Folder('/path/to/folder')
>>> folder.add_to_sys_path()
Inserted /path/to/folder at index 1 in system path.

>>> folder.add_to_sys_path(method='append')
Appended /path/to/folder to system path.

>>> folder.add_to_sys_path(method='invalid')
Invalid method: invalid. Use 'insert' or 'append'.
chdir()

Set this directory as working directory.

Examples

>>> folder.chdir()
exists(name)

Check if a file or subfolder exists in the current folder.

Parameters:

name (str, optional) – The name of the file or subfolder to check.

Returns:

True if the file or folder exists, False otherwise.

Return type:

bool

Examples

>>> folder = Folder(name="root")
>>> folder.exists("filename_or_foldername")
False
files: Dict[str, str]
get(*args)

Get the full path of a file or a subfolder in the current folder.

Parameters:

*args (str) – The name of the file or the subfolder to get. If None, returns the full path of the current folder. Default is None.

Returns:

The full path to the file or the subfolder.

Return type:

Path

get_str(*args)

Get the full path of a file or a subfolder in the current folder.

Parameters:

fname (str) – The name of the file or the subfolder to get. If None, returns the full path of the folder. Default is None.

Returns:

The full path to the file or the subfolder.

Return type:

str

Examples

>>> folder = Folder(name="root")
>>> folder.get_str("file1")
'/home/user/root/file1'
join(*args)

Join the current folder path with additional path components.

Parameters:

args (str) – Path components to join with the current folder path.

Returns:

The full path after joining the current folder path with the provided components.

Return type:

str

Examples

>>> folder = Folder(name="root")
>>> folder.join("subfolder", "file.txt")
'/home/user/root/subfolder/file.txt'
list(mode='name', type=None)

List subfolders or files in the current folder.

Parameters:

  • mode (str, optional) – The mode to use for listing items. Options are ‘name’ (default), ‘dir’, and ‘stem’. - ‘name’: List item names (with extensions for files). - ‘dir’: List full item paths. - ‘stem’: List file stems (filenames without extensions).

  • type (str, optional) – The type of items to list. Options are: - ‘folder’: List only folders. - ‘file’: List only files. - None (default): List both files and directories.

Returns:

A list of directories or files (or both) based on the specified filters.

Return type:

list

ls(scan_before_checking=False)

Print the contents of the folder, including subfolders and files in the pn object. Users should run scan() if the folder structure has changed.

Parameters:

scan_before_checking (bool, optional) – Whether to scan the folder before listing its contents. Default is False.

Examples

>>> folder = Folder(name="root")
>>> folder.subfolders['sub1'] = Folder("sub1")
>>> folder.files['file1'] = "/path/to/file1"
>>> folder.ls()
Contents of '/root':
Subfolders:
  [Dir] sub1
Files:
  [File] file1
mkdir(*args)

Create a directory inside the current folder and update the internal structure.

Parameters:

args (str) – Path components for the new directory relative to the current folder.

Examples

>>> folder = Folder(name="root")
>>> folder.mkdir("new_subfolder")
>>> folder.subfolders['new_subfolder']
Folder(name='new_subfolder', parent_path='/root', subfolders={}, files={})
name: str
parent_path: Path
remove(name)

Remove a file or subfolder from the folder and delete it from the filesystem.

Parameters:

name (str) – The name of the file or folder to remove, replacing underscores with spaces if needed.

Examples

>>> folder = Folder(name="root")
>>> folder.subfolders['sub1'] = Folder("sub1")
>>> folder.files['file1'] = "/path/to/file1"
>>> folder.remove('sub1')
Subfolder 'sub1' has been removed from '/root'
>>> folder.remove('file1')
File 'file1' has been removed from '/root'
scan(max_depth=1, only_include=None, only_exclude=None, only_folders=False, only_files=False, clear=True, max_files=9223372036854775807, max_folders=9223372036854775807, recursive_include_and_exclude=True, include_hidden=False, _depth_count=0)

Recursively scan subfolders and files in the current folder.

Parameters:

  • max_depth (int, optional) – The maximum depth to scan. Default is 1.

  • only_include (list, optional) – A list of patterns to include only files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_exclude (list, optional) – A list of patterns to exclude files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_folders (bool, optional) – Whether to scan only subfolders. Default is False.

  • only_files (bool, optional) – Whether to scan only files. Default is False.

  • clear (bool, optional) – Whether to clear the subfolders and files before scanning. Default is True.

  • max_files (int, optional) – The maximum number of files at each level to scan. Default is sys.maxsize.

  • max_folders (int, optional) – The maximum number of subfolders at each level to scan. Default is sys.maxsize.

  • recursive_include_and_exclude (bool, optional) – Whether to apply the include and exclude patterns recursively. Default is True.

  • include_hidden (bool, optional) – Whether to include hidden files and folders in the scan. Default is False.

  • _depth_count (int, optional) – The current depth count. Default is 0.

set_all_to_sc(overwrite=False, prefix='', only_include=[], only_exclude=[], only_folders=False, only_files=False)

Add all files in the current folder to the shortcut manager.

Parameters:

  • overwrite (bool, optional) – Whether to overwrite existing shortcuts. Default is False.

  • prefix (str, optional) – The prefix to add to the shortcut names. Default is “”.

  • only_include (list, optional) – A list of patterns to include only files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_exclude (list, optional) – A list of patterns to exclude files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_folders (bool, optional) – Whether to scan only subfolders. Default is False.

  • only_files (bool, optional) – Whether to scan only files. Default is False.

set_sc(name, filename=None)

Add a shortcut to this folder using the Shortcut manager.

Parameters:

  • name (str) – The name of the shortcut to add.

  • filename (str, optional) – The name of the file to add a shortcut for. Default is None.

Examples

>>> folder = Folder(name="root")
>>> folder.set_sc("my_folder")
Shortcut 'my_folder' added for path '/root'
subfolders: Dict[str, Any]
tree(level=-1, limit_to_directories=False, length_limit=1000, level_length_limit=100)

Print a visual tree structure of the folder and its contents.

Parameters:

  • level (int, optional) – The max_depth of the tree to print. Default is -1 (print all levels).

  • limit_to_directories (bool, optional) – Whether to limit the tree to directories only. Default is False.

  • length_limit (int, optional) – The maximum number of lines to print. Default is 1000.

  • level_length_limit (int, optional) – The maximum number of lines to print per level. Default is 100.

pathnavigator.pathnavigator module

class pathnavigator.pathnavigator.PathNavigator(root_dir=None, max_depth=1, only_include=None, only_exclude=None, only_folders=True, only_files=False, max_files=9223372036854775807, max_folders=9223372036854775807, recursive_include_and_exclude=False, include_hidden=False, display=False)

Bases: Folder

A class to manage the root folder and recursively load its nested structure (subfolders and files).

Examples

>>> pn = PathNavigator('/path/to/root')

>>> pn.folder1.get()        # returns the full path to folder1 as a Path object.
>>> pn.folder1.get_str()    # returns the full path to folder1 as a string.
>>> pn.folder1.get("file.txt")        # returns the full path to file.txt as a Path object.
>>> pn.get("folder1")       # returns the full path to folder1 as a Path object.
>>> pn.folder1.get_str("file.txt")    # returns the full path to file.txt as a string.

>>> pn.folder1.set_sc('my_folder')  # set the shortcut to folder1 which can be accessed by pn.sc.my_folder or pn.sc.get("my_folder") or pn.sc.get_str("my_folder").
>>> pn.folder1.set_sc('my_file', 'file.txt')  # set the shortcut to file.txt which can be accessed by pn.sc.my_file or pn.sc.get("my_file") or pn.sc.get_str("my_file").
>>> pn.sc.add('shortcut_name', 'shortcut_path')    # add a customized shortcut independent to pn internal folder structure.

>>> pn.folder1.ls()         # prints the contents (subfolders and files) of folder1.
>>> pn.tree()               # prints the entire nested folder structure.

>>> pn.folder1.chdir()      # change the current directory to folder1.
>>> pn.folder1.add_to_sys_path()    # add folder1 to the system path.

>>> pn.exists('folder1')    # check if folder1 exists in the folder structure.
>>> pn.folder1.listdirs()   # returns a list of subfolders in folder1.
>>> pn.folder1.listfiles()  # returns a list of files in folder1.

>>> pn.mkdir('folder1', 'folder2')  # make a subfolder under the root. In this case, 'root/folder1/folder2' will be created.
>>> pn.remove('folder1')    # removes a file or subfolder from the folder and deletes it from the filesystem.

pathnavigator.shortcut module

class pathnavigator.shortcut.Shortcut

Bases: Base

A class to manage shortcuts to specific paths and access them as attributes.

add(name, path, overwrite=False)

Add a new shortcut as an attribute. automatically converts the name to a valid attribute name.

Parameters:

  • name (str) – The name of the shortcut.

  • path (str) – The path that the shortcut refers to.

  • overwrite (bool, optional) – Whether to overwrite an existing shortcut. Default is False.

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.my_folder
'/path/to/folder'
add_all(directory, overwrite=False, prefix='', only_include=[], only_exclude=[], only_folders=False, only_files=False)

Add all files in a given directory as shortcuts.

Parameters:

  • directory (str or Path) – The directory containing the files to add as shortcuts.

  • overwrite (bool, optional) – Whether to overwrite existing shortcuts. Default is False.

  • prefix (str, optional) – The prefix to add to the shortcut names. Default is “”.

  • only_include (list, optional) – A list of patterns to include only files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_exclude (list, optional) – A list of patterns to exclude files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_folders (bool, optional) – Whether to scan only subfolders. Default is False.

  • only_files (bool, optional) – Whether to scan only files. Default is False.

Examples

>>> shortcut = Shortcut()
>>> shortcut.add_all("/path/to/directory")
clear()

Remove all shortcuts.

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.clear()
>>> hasattr(shortcut, "my_folder")
False
get(name)

Retrieve the path of a shortcut.

Parameters:

name (str) – The name of the shortcut.

Returns:

The path associated with the shortcut.

Return type:

str

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.get("my_folder")
'/path/to/folder'
get_str(name)

Retrieve the path of a shortcut.

Parameters:

name (str) – The name of the shortcut.

Returns:

The path associated with the shortcut.

Return type:

str

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.get("my_folder")
'/path/to/folder'
load_dict(data, overwrite=False)

Load shortcuts from a dictionary.

Parameters:

  • data (dict) – A dictionary where keys are shortcut names and values are paths.

  • overwrite (bool, optional) – Whether to overwrite existing shortcuts. Default is False.

Examples

>>> shortcut = Shortcut()
>>> shortcut.load_dict({"project": "/path/to/project", "data": "/path/to/data"})
load_json(filename, overwrite=False)

Load shortcuts from a JSON file.

Parameters:

  • filename (str) – The name of the file containing the shortcuts in JSON format.

  • overwrite (bool, optional) – Whether to overwrite existing shortcuts. Default is False.

Examples

>>> shortcut = Shortcut()
>>> shortcut.load_json("shortcuts.json")
load_yaml(filename, overwrite=False)

Load shortcuts from a YAML file.

Parameters:

  • filename (str) – The name of the file containing the shortcuts in YAML format.

  • overwrite (bool, optional) – Whether to overwrite existing shortcuts. Default is False.

Examples

>>> shortcut = Shortcut()
>>> shortcut.load_yaml("shortcuts.yml")
ls()

List all shortcuts and their paths.

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.ls()
Shortcuts:
my_folder -> /path/to/folder
remove(name)

Remove a shortcut by name and delete its attribute.

Parameters:

name (str) – The name of the shortcut to remove.

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.remove("my_folder")
>>> hasattr(shortcut, "my_folder")
False
to_dict(to_str=False)

Return all shortcuts as a dictionary.

Parameters:

to_str (bool, optional) – Whether to convert all Path objects to strings. Default is False.

Returns:

A dictionary representation of all shortcuts.

Return type:

dict

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.to_dict()
{'my_folder': '/path/to/folder'}
to_json(filename='shortcuts.json')

Return all shortcuts as a JSON string and save it to a file.

Parameters:

filename (str) – The name of the file where the JSON string will be saved.

Returns:

A JSON string representation of all shortcuts.

Return type:

str

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.to_json("shortcuts.json")
'{"my_folder": "/path/to/folder"}'
to_yaml(filename='shortcuts.yml')

Return all shortcuts as a YAML string and save it to a file.

Parameters:

filename (str) – The name of the file where the YAML string will be saved.

Returns:

A YAML string representation of all shortcuts.

Return type:

str

Examples

>>> shortcut = Shortcut()
>>> shortcut.add("my_folder", "/path/to/folder")
>>> shortcut.to_yaml("shortcuts.yml")
my_folder: /path/to/folder

Module contents

pathnavigator.create(root_dir=None, max_depth=1, only_include=None, only_exclude=None, only_folders=True, only_files=False, max_files=9223372036854775807, max_folders=9223372036854775807, recursive_include_and_exclude=False, include_hidden=False, display=False)

Create a PathNavigator object with the given root directory and load nested directories. Default to scan the tree of directories. Files will be dynamically added when related methods are called, e.g., get(). This will avoid long initial loading time.

Parameters:

  • root_dir (str) – The root directory to manage. If it is not given, we use the current working directory and load_nested_dirs will be set to False.

  • max_depth (int, optional) – The maximum depth to scan. Default is 1 (only scan current folder). The internal tree will grow automatically as folders or files are accessed.

  • only_include (list, optional) – A list of patterns to include only files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_exclude (list, optional) – A list of patterns to exclude files or folders that match the patterns. No ** wildcard is allowed, only * is allowed.

  • only_folders (bool, optional) – Whether to scan only subfolders. Default is True. File will be dynamically added when related methods are called, e.g., get().

  • only_files (bool, optional) – Whether to scan only files. Default is False.

  • max_files (int, optional) – The maximum number of files at each level to scan. Default is sys.maxsize.

  • max_folders (int, optional) – The maximum number of subfolders at each level to scan. Default is sys.maxsize.

  • recursive_include_and_exclude (bool, optional) – Whether to apply the include and exclude patterns recursively. Default is True.

  • include_hidden (bool, optional) – Whether to include hidden files and folders. Default is False.

  • display (bool) – Whether to display action complete info like changing directory. Default is False.

Returns:

The PathNavigator object with the given root directory.

Return type:

PathNavigator