hbutils.system.filesystem

Overview:

Utilities for filesystem operations.

This module provides a comprehensive set of utilities for working with filesystems, including binary file operations, directory management, file handling, and temporary file creation. It serves as a central import point for all filesystem-related functionality in the hbutils.system package.

The module aggregates functionality from:

binary: Binary file operations and utilities for detecting file types
directory: Directory creation, traversal, and management operations
file: General file operations and manipulation utilities
tempfile: Temporary file and directory creation utilities with cross-platform support

This module re-exports all public functions and classes from its submodules, providing a convenient single import point for filesystem operations.

touch

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

Touch the file at given path. Just like the touch command in unix system.

Parameters:

file (str) – Path of the file to create or update.
exist_ok (bool) – If True, do not raise an error if the file already exists. Defaults to True.
makedirs (bool) – If True, create parent directories as needed. Defaults to True.

Note

You can use this like touch command on unix.

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]

Glob filter by the given items.

This function performs pattern matching on file paths using glob patterns. Unlike the native glob.glob, this function returns a generator that yields matching paths, making it more memory-efficient for large result sets.

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

Note

glob() is different from native glob.glob, for its return value is a generator instead of list.

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.

No less than 2 arguments are accepted. When the last path is an existing path, all the fore paths will be copied to this path. Otherwise, the first path will be copied to the last path (exactly 2 arguments are accepted in this case, or NotADirectoryError will be raised).

From Stack Overflow - Copy file or directories recursively in Python.

Parameters:

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

Raises:

NotADirectoryError – If destination is not a directory when multiple sources are provided.

Note

You can use this like cp -rf command on unix.

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 to match multiple files at once. The function works recursively for directories.

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

Note

You can use this like rm -rf command on unix.

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) → int[source]

Get the total size of files or directories.

This function calculates the total size of one or more files or directories. For directories, it recursively sums up all file sizes. Supports glob patterns to match multiple files.

Parameters:: files (str) – File or directory paths. Supports glob patterns.
Returns:: Total size in bytes of all specified files or directories.
Return type:: int

Note

You can use this like du -sh command on unix.

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 from the beginning of the file and checks if it contains binary characters. Files are considered binary if they contain characters outside the standard text character set.

Parameters:: filename (str) – The path to the file to check.
Returns:: True if the file is binary, False otherwise.
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 will be treated as 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 reads a sample from the beginning of the file and checks if it contains only text characters. Files are considered text if they do not contain binary characters.

Parameters:: filename (str) – The path to the file to check.
Returns:: True if the file is text, False otherwise.
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 will be treated as 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. This has the same behavior as mkdtemp but can be used as a context manager. For example:

with TemporaryDirectory() as tmpdir:
…

Upon exiting the context, the directory and everything contained in it are removed.