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: object

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

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: object

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, scan_before_checking=False)

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()

Print the contents of the folder, including subfolders and files.

Prints subfolders first, followed by files.

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=inf, max_files=inf, max_folders=inf, include=None, exclude=None, _only_folders=False, _only_files=False, _depth_count=0, _clear=True)

Recursively scan subfolders and files in the current folder.

Parameters:

max_depth (int, optional) – The maximum depth to scan. Default is math.inf.
max_files (int, optional) – The maximum number of files to scan. Default is math.inf.
max_folders (int, optional) – The maximum number of subfolders to scan. Default is math.inf.
include (str, optional) – A regex pattern to include files or folders matching the pattern. Default is None (include all).
exclude (str, optional) – A regex pattern to exclude files or folders matching the pattern. Default is None (exclude none).
_only_folders (bool, optional) – Whether to scan only subfolders. Default is False.
_only_files (bool, optional) – Whether to scan only files. Default is False.
_depth_count (int, optional) – The current depth count. Default is 0.
_clear (bool, optional) – Whether to clear the subfolders and files before scanning. Default is True.

set_all_files_to_sc(overwrite=False, prefix='')

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 “”.

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=inf, max_files=inf, max_folders=inf, 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: object

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_files(directory, overwrite=False, prefix='')

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.

Examples

>>> shortcut = Shortcut()
>>> shortcut.add_all_files_in_directory("/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=inf, max_files=inf, max_folders=inf)

Create a PathNavigator object with the given root directory and load nested directories.

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) – The maximum depth to load the nested directories. Default is math.inf.
max_files (int) – The maximum number of files to load. Default is math.inf.
max_folders (int) – The maximum number of subdirectories to load. Default is math.inf.

Returns:

The PathNavigator object with the given root directory.

Return type:

PathNavigator