hbutils.system.filesystem¶

Overview:: Utilities for filesystem.

touch¶

hbutils.system.filesystem.touch(file: str, exist_ok: bool = True, makedirs: bool = True)[source]¶

Create a file at the specified path, similar to the Unix ‘touch’ command.

This function creates an empty file at the given path. If the file already exists, it updates the file’s access and modification times. It can also create necessary parent directories if they don’t exist.

Parameters:

file (str) – Path of the file to be created or updated.
exist_ok (bool) – If True, don’t raise an error if the file already exists. Default is True.
makedirs (bool) – If True, create parent directories when necessary. Default is True.

Raises:

FileExistsError – If the file already exists and exist_ok is False.
OSError – If there’s an error creating the file or directories.

Note

This function mimics the behavior of the ‘touch’ command in Unix systems.

Examples:

>>> import os
>>> from hbutils.system import touch
>>> os.listdir('.')
[]
>>> touch('simple.txt')  # touch simple file
>>> touch('1/2/3/simple.txt')  # touch file in nested directory (1/2/3 will be created)
>>> os.listdir('.')
['1', 'simple.txt']
>>> os.listdir('1/2/3')
['simple.txt']

glob¶

hbutils.system.filesystem.glob(*items) → Iterator[str][source]¶

Perform glob operations on the given patterns and return an iterator of matching file paths.

This function allows for flexible file matching using wildcard patterns. It can handle multiple patterns and performs recursive matching by default.

Parameters:: items (str) – One or more glob patterns to match against file paths.
Returns:: An iterator yielding paths of files that match the given patterns.
Return type:: Iterator[str]

Note

This function differs from the native glob.glob in that it returns a generator instead of a list, which can be more memory-efficient for large directory structures.

Examples:

>>> from hbutils.system import glob
>>>
>>> list(glob('*.md'))  # simple filter
['CONTRIBUTING.md', 'README.md']
>>> list(glob('*.md', '*.txt'))  # multiple filter
['CONTRIBUTING.md', 'README.md', 'requirements-test.txt', 'requirements-doc.txt', 'requirements.txt']
>>> print(*glob('hbutils/system/**/*.py'), sep='\n')  # nested filter
hbutils/system/__init__.py
hbutils/system/filesystem/directory.py
hbutils/system/filesystem/file.py
hbutils/system/filesystem/__init__.py
hbutils/system/python/package.py
hbutils/system/python/implementation.py
hbutils/system/python/version.py
hbutils/system/python/__init__.py
hbutils/system/os/type.py
hbutils/system/os/__init__.py

copy¶

hbutils.system.filesystem.copy(src1: str, src2: str, *srcn_dst: str)[source]¶

Copy files or directories.

This function provides a flexible way to copy multiple files or directories to a destination. It can be used similarly to the ‘cp -rf’ command in Unix.

Parameters:

src1 (str) – First source path.
src2 (str) – Second source path or destination path.
srcn_dst (str) – Additional source paths and the destination path.

Raises:

NotADirectoryError – If the destination is not a directory when copying multiple sources.

Usage:

To copy a single file or directory: copy(‘source’, ‘destination’)
To copy multiple files/directories to an existing directory: copy(‘source1’, ‘source2’, ‘destination’)
To copy files matching a pattern: copy(’*.txt’, ‘destination’)

Examples:

>>> import os
>>> from hbutils.system import copy
>>>
>>> os.listdir('.')
['test', 'README.md', 'cloc.sh', 'LICENSE', 'codecov.yml', 'pytest.ini', 'Makefile', 'setup.py', 'requirements-test.txt', 'requirements-doc.txt', 'requirements.txt']
>>>
>>> copy('cloc.sh', 'new_cloc.sh')  # copy file
>>> copy('test', 'new_test')  # copy directory
>>> os.listdir('.')
['test', 'README.md', 'cloc.sh', 'LICENSE', 'codecov.yml', 'new_test', 'pytest.ini', 'Makefile', 'setup.py', 'requirements-test.txt', 'requirements-doc.txt', 'requirements.txt', 'new_cloc.sh']
>>>
>>> os.makedirs('new_path_1')
>>> copy('*.txt', 'new_path_1')  # copy to new path
>>> os.listdir('new_path_1')
['requirements-test.txt', 'requirements-doc.txt', 'requirements.txt']
>>>
>>> os.makedirs('new_path_2')
>>> copy('*.txt', 'test/system/**/*.py', 'new_path_2')  # copy plenty of files to new path
>>> print(*os.listdir('new_path_2'), sep='\n')
test_version.py
test_file.py
test_type.py
test_package.py
test_implementation.py
requirements-test.txt
__init__.py
test_directory.py
requirements-doc.txt
requirements.txt

remove¶

hbutils.system.filesystem.remove(*files: str)[source]¶

Remove files or directories.

This function can remove both files and directories. It supports glob patterns for batch removal. It can be used similarly to the ‘rm -rf’ command in Unix.

Parameters:: files (str) – Files or directories to be removed.

Usage:

To remove a single file or directory: remove(‘path/to/file_or_dir’)
To remove multiple files or directories: remove(‘file1’, ‘dir1’, ‘file2’)
To remove files matching a pattern: remove(’.txt’, ‘dir/*/*.py’)

Examples:

>>> import os
>>> from hbutils.system import remove
>>>
>>> os.listdir('.')
['test', 'README.md', 'cloc.sh', 'codecov.yml', 'new_test', 'new_path_2', 'setup.py', 'requirements-test.txt', 'new_path_1', 'requirements-doc.txt', 'requirements.txt', 'new_cloc.sh']
>>>
>>> remove('codecov.yml')  # remove file
>>> remove('new_test')  # remove directory
>>> os.listdir('.')
['test', 'README.md', 'cloc.sh', 'new_path_2', 'setup.py', 'requirements-test.txt', 'new_path_1', 'requirements-doc.txt', 'requirements.txt', 'new_cloc.sh']
>>>
>>> os.listdir('new_path_1')
['requirements-test.txt', 'requirements-doc.txt', 'requirements.txt']
>>> remove('new_path_1/*.txt')  # remove files from directory
>>> os.listdir('new_path_1')
[]
>>>
>>> print(*os.listdir('new_path_2'), sep='\n')
test_version.py
test_file.py
test_type.py
test_package.py
test_implementation.py
requirements-test.txt
__init__.py
test_directory.py
requirements-doc.txt
requirements.txt
>>> remove('README.md', 'test/**/*.py', 'new_path_2/*.py')  # remove plenty of files
>>> print(*os.listdir('new_path_2'), sep='\n')
requirements-test.txt
requirements-doc.txt
requirements.txt

getsize¶

hbutils.system.filesystem.getsize(*files: str)[source]¶

Get the size of files or directories.

This function calculates the total size of all specified files and directories. It supports glob patterns for batch size calculation.

Parameters:: files (str) – Paths to files or directories.
Returns:: Total size in bytes.
Return type:: int

Usage:

To get size of a single file or directory: getsize(‘path/to/file_or_dir’)
To get total size of multiple files or directories: getsize(‘file1’, ‘dir1’, ‘file2’)
To get total size of files matching a pattern: getsize(’.txt’, ‘dir/*/*.py’)

Examples:

>>> from hbutils.system import getsize
>>>
>>> getsize('README.md')  # a file
5368
>>> getsize('test')  # a directory
1575574
>>> getsize('hbutils/**/*.py')  # glob filtered files
238080

is_binary_file¶

hbutils.system.filesystem.is_binary_file(filename) → bool[source]¶

Check if the given file is a binary file.

This function reads a sample of the file and analyzes its content to determine if it contains non-text characters.

Parameters:: filename (str) – The name of the file to check.
Returns:: True if the file is binary, False if it’s a text file.
Return type:: bool

Examples::

>>> from hbutils.system import is_binary_file
>>> is_binary_file('rar_template-simple.rar')
True
>>> is_binary_file('README.md')
False

Note

Empty files are considered text files.

is_text_file¶

hbutils.system.filesystem.is_text_file(filename) → bool[source]¶

Check if the given file is a text file.

This function is the inverse of is_binary_file. It reads a sample of the file and analyzes its content to determine if it contains only text characters.

Parameters:: filename (str) – The name of the file to check.
Returns:: True if the file is a text file, False if it’s binary.
Return type:: bool

Examples::

>>> from hbutils.system import is_text_file
>>> is_text_file('rar_template-simple.rar')
False
>>> is_text_file('README.md')
True

Note

Empty files are considered text files.

TemporaryDirectory¶

class hbutils.system.filesystem.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False)[source]¶

Create and return a temporary directory that can be used as a context manager.

This class is a backport of the Python 3.10 tempfile.TemporaryDirectory implementation, addressing PermissionError issues on Windows Python 3.7.

Usage:

>>> with TemporaryDirectory() as tmpdir:
>>>     # Use tmpdir as a temporary directory
>>>     ...

Upon exiting the context, the directory and its contents are removed.

Parameters:

suffix (str or None) – Optional suffix for the directory name.
prefix (str or None) – Optional prefix for the directory name.
dir (str or None) – The parent directory to create the temporary directory in.
ignore_cleanup_errors (bool) – If True, ignore errors during cleanup.

Raises:

OSError – If there is an error in creating or cleaning up the directory.