Module: utilities.py

Purpose:

This module provides general utility-based functions to the project.

Platform:

Linux/Windows | Python 3.10+

Developer:

J Berendt

Email:

development@s3dev.uk

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 in exclude paths. Adding the trailing path separator prevents this.

Returns:

A new list of paths where any source path sharing a common base path with any exclude 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 the size 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

badsnakes.libs.utilities.utilities

alias of Utilities