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

Bases: object

Generalised utilities for use throughout the project.

static exclude_dirs(source: list[str], exclude: list[str]) → list[str]

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

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:

• How to detect if a file is binary

• ASCII printable character reference

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

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

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