Module: utilities.py — badsnakes - v0.2.0 Documentation

# 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 derive_log_filename(path: str = 'badsnakes') → str

    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]

    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`