mooonpy.tools.file_utils module

class mooonpy.tools.file_utils.Path(string: str | Path)

Bases: str

As computational scientists, half our jobs is file management and manipulation, the Path class contains several aliases for the os.path and glob.glob modules to make processing data easier. All mooonpy functions internally use this class for inputs of files or folders. Relevant strings are converted to path on entering functions

Examples

A copy of the code used in these examples is avalible in rootmooonpyexamplestoolspath_utilsexample_Path.py

Basic Path Operations

>>> project_path = Path('Project/Data/Analysis')
>>> filename = Path('results.txt')
>>> full_path = project_path / filename
>>> print(full_path)
Project\Data\Analysis\results.txt
>>> print(abs(full_path))
root\mooonpy\examples\tools\path_utils\Project\Data\Analysis\results.txt

Path Parsing

>>> sample_path = Path('experiments/run_001/data.csv.gz')
>>> print(sample_path.dir())
experiments\run_001
>>> print(sample_path.basename())
data.csv.gz
>>> print(sample_path.root())
data.csv
>>> print(sample_path.ext())
.gz

Extension Manipulation

>>> data_file = Path('analysis/results.txt')
>>> print(data_file.new_ext('.json'))
analysis\results.json
>>> print(data_file.new_ext('.txt.gz'))
analysis\results.txt.gz

File Existence

>>> current_file = Path(__file__)
>>> fake_file = Path('nonexistent.txt')
>>> print(bool(current_file))
True
>>> print(bool(fake_file))
False

Wildcard Matching

>>> txt_pattern = Path('temp_dir/*.txt')
>>> print(txt_pattern.matches())
['test1.txt', 'test2.txt']
>>> for file in Path('temp_dir/*'):
...     print(file.basename())
data.csv
readme.md
test1.txt
test2.txt

Recent File Finding

>>> pattern = Path('temp_dir/*.txt')
>>> print(pattern.recent())
newest_file.txt
>>> print(pattern.recent(oldest=True))
old_file.txt

Smart File Opening

>>> mypath = Path('data.txt')
>>> with mypath.open('w') as f:
...     f.write('Hello World')
# Creates regular file
>>> compressed_path = Path('data.txt.gz')
>>> # compressed_path.open() would use gzip automatically
# Would automatically handle gzip compression
** Absolute Path Conversion **
>>> rel_path = Path('data/file.txt')
>>> print(abs(rel_path))
root\mooonpy\examples\tools\path_utils\data\file.txt

Todo

__truediv__ __bool__ __abs__ and __iter__ docstrings in config?

basename() → Path

Split Path to filename and extention.

Alias for os.path.basename

Returns:

Path of file

Return type:

Path

Example:

>>> from mooonpy import Path
>>> MyPath = Path('Project/Monomers/DETDA.mol')
>>> print(MyPath.basename())
'DETDA.mol'

dir() → Path

Split Path to directory.

Alias for os.path.dirname.

Returns:

Path to directory

Return type:

Path

Example:

>>> from mooonpy import Path
>>> MyPath = Path('Project/Monomers/DETDA.mol')
>>> print(MyPath.dir())
'Project\Monomers'

ext() → Path

Split Path to just extention.

Alias for os.path.basename and os.path.splitext.

Returns:

extention as Path

Return type:

Path

Example:

>>> from mooonpy import Path
>>> MyPath = Path('Project/Monomers/DETDA.mol')
>>> print(MyPath.ext())
'.mol'

matches(whitelist_ext=None, blacklist_ext=None) → List[Path]

Finds matching paths with a * (asterisk) wildcard character.

Returns:

List of matching Paths

Return type:

List[Path]

Example:

>>> from mooonpy import Path
>>> MyWildcard = Path('*.mol')
>>> print(Path.matches(MyWildcard))
[Path('DETDA.mol'), Path('DEGBF.mol')]

new_ext(ext: str | Path) → Path

Replace extension on a Path with a new extension.

Parameters:

ext (str or Path) – new extension including delimeter.

Returns:

replaced Path

Return type:

Path

Example:

>>> from mooonpy import Path
>>> MyPath = Path('Project/Monomers/DETDA.mol')
>>> print(MyPath.new_ext('.data'))
'Project/Monomers/DETDA.data'

open(mode='r', encoding='utf-8')

Open path with smart_open

Parameters:

• mode (str) – Open mode, usually ‘r’ or ‘a’

• encoding (str) – File encoding

Returns:

opened file as object

Return type:

File Object

Example:

>>> from mooonpy import Path
>>> MyPath = Path('Project/Monomers/DETDA.mol')
>>> MyFileObj = MyPath.open(mode='r')

recent(oldest: bool = False) → Path | None

Find wildcard matches and return the Path of the most recently modified file.

Parameters:

oldest (bool) – Reverses direction and finds least recently modified file.

Returns:

Path of most recently modified file

Return type:

Path

Example:

>>> from mooonpy import Path
>>> MyWildcard = Path('Template_*.lmpmol')
>>> print(Path.recent())
'Template_1_v10_final_realthistime.lmpmol'
>>> print(Path.recent(oldest=True))
'Template_1.lmpmol'

root() → Path

Split Path to filename with no extention.

Alias for os.path.basename and os.path.splitext.

Returns:

Path of filename

Return type:

Path

Example:

>>> from mooonpy import Path
>>> MyPath = Path('Project/Monomers/DETDA.mol')
>>> print(MyPath.root())
'DETDA'

mooonpy.tools.file_utils.smart_open(filename, mode='r', encoding='utf-8')

Open file with appropriate decompression based on extension

Supported extensions: Use substring in filename

• .gz: Uses gzip module

• .bz2: Uses bzip2 module

• .xz: Uses lzma module

• .lzma: Uses lzma module

• Other extensions use the builtin open function

Parameters:

• filename (Path or str) – Path to file

• mode (str) – Open mode, usually ‘r’, ‘w’ or ‘a’

• encoding (str) – File encoding

Returns:

opened file as object

Return type:

File Object

Example:

>>> from mooonpy.tools.file_utils import smart_open
>>> MyFileObj = smart_open('Project/Monomers/DETDA.data.gz')