Module: utilities.py
- Purpose:
This module provides general utility-based functions to the project.
- Platform:
Linux/Windows | Python 3.10+
- Developer:
J Berendt
- Email:
- Comments:
n/a
- Examples:
Test if a file is binary:
>>> from badsnakes.libs.utilities import utilities >>> utilities.isbinary(path='/path/to/myfile.ext') True
Test if a file is text:
>>> from badsnakes.libs.utilities import utilities >>> utilities.istext(path='/path/to/myfile.py') True
Test if a file is a Python wheel:
>>> from badsnakes.libs.utilities import utilities >>> utilities.iszip(path='/path/to/mypackage.whl') True
- class badsnakes.libs.utilities.Utilities[source]
Bases:
object
Generalised utilities for use throughout the project.
- static derive_log_filename(path: str = 'badsnakes') str [source]
Derive the log filename from the provided path.
- Parameters:
path (str, optional) – Path from which the log filename is to be derived. If not provided, the default log base filename is used. Defaults to ‘badsnakes’.
- Logic:
If
path
is provided, the basename is extracted and the file extension is dropped and any trailing ‘/’ are dropped. This is used as the base for the filename convention. Otherwise, ‘badsnakes’ is used as the base.Filename convention:
<base>__YmdTHMS.bs.log
Additionally, if the
--logpath
argument was passed to the CLI, this directory is used. Otherwise the user’s desktop is used as the directory.- Returns:
The complete path to the log file.
- Return type:
str
- static exclude_dirs(source: list[str], exclude: list[str]) list[str] [source]
Exclude the listed directories from the source.
- Parameters:
source (list[str]) – List of source paths.
exclude (list[str]) – List of directories to be excluded from
source
.
- Design:
The paths in
exclude
are expanded to their realpath, with a trailing path separator explicitly added to ensure only directory paths are matched.For example, if the trailing path separator was not added,
.gitignore
would be excluded if./.git
was inexclude
paths. Adding the trailing path separator prevents this.- Returns:
A new list of paths where any
source
path sharing a common base path with anyexclude
path has been removed.- Return type:
list[str]
- classmethod isbinary(path: str, size: int = 1024) bool [source]
Determine if a file is binary.
- Parameters:
path (str) – Full path to the file to be tested.
size (int, optional) – Number of bytes read at a time to perform the test. As with
io.RawIOBase.read()
, if size is unspecified or -1, all bytes until EOF are returned. Defaults to 1024.
- Design:
For each chunk of the file, if any characters are left over after removing all text characters, the file is classified as ‘binary’, and
True
is returned immediately. For efficiency, only (N) bytes of the files are read at a time, as controlled by thesize
argument. Once a file is found to be binary, the function returns immediately as there is no need to continue reading.- References:
- Returns:
True if a file is binary, otherwise False if the file is plain-text.
- Return type:
bool
- classmethod istext(path: str, size: int = 1024) bool [source]
Determine if a file is plain-text.
- Parameters:
path (str) – Full path to the file to be tested.
size (int, optional) – Number of bytes read to perform the test. As with
io.RawIOBase.read()
, if size is unspecified or -1, all bytes until EOF are returned. Defaults to 1024.
- Design:
This function simply calls the
isbinary()
method and inverts the return value.- Returns:
True if a file is plain-text, otherwise false if the file is binary.
- Return type:
bool
- classmethod iszip(path: str) bool [source]
Determine if a file is a
ZIP
archive.- Parameters:
path (str) – Full path to the file to be tested.
Note
A file is tested to be a
ZIP
archive by checking the first four bytes of the file itself, not using the file extension.It is up to the caller to handle empty or spanned ZIP archives appropriately.
- Returns:
True if the first four bytes of the file match any of the below. Otherwise, False.
\x50\x4b\x03\x04
: ‘Standard’ archive\x50\x4b\x05\x06
: Empty archive\x50\x4b\x07\x08
: Spanned archive
- Return type:
bool