Documentation for Utils Module

module
torrentfile.utils

Utility functions and classes used throughout package.

Functions: get_piece_length: calculate ideal piece length for torrent file. sortfiles: traverse directory in sorted order yielding paths encountered. path_size: Sum the sizes of each file in path. get_file_list: Return list of all files contained in directory. path_stat: Get ideal piece length, total size, and file list for directory. path_piece_length: Get ideal piece length based on size of directory.

Classes
  • MissingPathError Path parameter is required to specify target content.
  • PieceLengthValueError Piece Length parameter must equal a perfect power of 2.
Functions
  • filelist_total(pathstring) (`os.PathLike`) Perform error checking and format conversion to os.PathLike.
  • get_file_list(path) (filelist : `list`) Return a sorted list of file paths contained in directory.
  • get_piece_length(size) (piece_length : `int`) Calculate the ideal piece length for bittorrent data.
  • humanize_bytes(amount) (`str` :) Convert integer into human readable memory sized denomination.
  • normalize_piece_length(piece_length) (piece_length : `int`) Verify input piece_length is valid and convert accordingly.
  • path_piece_length(path) (piece_length : `int`) Calculate piece length for input path and contents.
  • path_size(path) (size : `int`) Return the total size of all files in path recursively.
  • path_stat(path) (filelist : `list`) Calculate directory statistics.

torrentfile.utils

Utility functions and classes used throughout package.

Functions: get_piece_length: calculate ideal piece length for torrent file. sortfiles: traverse directory in sorted order yielding paths encountered. path_size: Sum the sizes of each file in path. get_file_list: Return list of all files contained in directory. path_stat: Get ideal piece length, total size, and file list for directory. path_piece_length: Get ideal piece length based on size of directory.

MissingPathError (Exception)

Path parameter is required to specify target content.

Creating a .torrent file with no contents seems rather silly.

Parameters:

Name Type Description Default
message `any`

Message for user (optional).

required

__init__(self, message=None) special

Raise when creating a meta file without specifying target content.

The message argument is a message to pass to Exception base class.

Source code in torrentfile\utils.py
def __init__(self, message=None):
    """Raise when creating a meta file without specifying target content.

    The `message` argument is a message to pass to Exception base class.
    """
    self.message = f"Path arguement is missing and required {str(message)}"
    super().__init__(message)

PieceLengthValueError (Exception)

Piece Length parameter must equal a perfect power of 2.

Parameters:

Name Type Description Default
message `any`

Message for user (optional).

required

__init__(self, message=None) special

Raise when creating a meta file with incorrect piece length value.

The message argument is a message to pass to Exception base class.

Source code in torrentfile\utils.py
def __init__(self, message=None):
    """Raise when creating a meta file with incorrect piece length value.

    The `message` argument is a message to pass to Exception base class.
    """
    self.message = f"Incorrect value for piece length: {str(message)}"
    super().__init__(message)

filelist_total(pathstring)

Perform error checking and format conversion to os.PathLike.

Parameters:

Name Type Description Default
pathstring `str`

An existing filesystem path.

required

Exceptions:

Type Description
MissingPathError

File could not be found.

Returns:

Type Description
`os.PathLike`

Input path converted to bytes format.

Source code in torrentfile\utils.py
def filelist_total(pathstring):
    """Perform error checking and format conversion to os.PathLike.

    Parameters
    ----------
    pathstring : `str`
        An existing filesystem path.

    Returns
    -------
    `os.PathLike`
        Input path converted to bytes format.

    Raises
    ------
    MissingPathError
        File could not be found.
    """
    if os.path.exists(pathstring):
        path = Path(pathstring)
        return _filelist_total(path)
    raise MissingPathError

get_file_list(path)

Return a sorted list of file paths contained in directory.

Parameters:

Name Type Description Default
path `str`

target file or directory.

required

Returns:

Type Description
`list`

sorted list of file paths.

Source code in torrentfile\utils.py
def get_file_list(path):
    """Return a sorted list of file paths contained in directory.

    Parameters
    ----------
    path : `str`
        target file or directory.

    Returns
    -------
    filelist : `list`
        sorted list of file paths.
    """
    _, filelist = filelist_total(path)
    return filelist

get_piece_length(size)

Calculate the ideal piece length for bittorrent data.

Parameters:

Name Type Description Default
size int

Total bits of all files incluided in .torrent file.

required

Returns:

Type Description
int

Ideal peace length size arguement.

Source code in torrentfile\utils.py
def get_piece_length(size: int) -> int:
    """Calculate the ideal piece length for bittorrent data.

    Parameters
    ----------
    size : `int`
        Total bits of all files incluided in .torrent file.

    Returns
    -------
    piece_length : `int`
        Ideal peace length size arguement.
    """
    exp = 14
    while size / (2 ** exp) > 200 and exp < 25:
        exp += 1
    return 2 ** exp

humanize_bytes(amount)

Convert integer into human readable memory sized denomination.

Parameters:

Name Type Description Default
amount `int`

total number of bytes.

required
Source code in torrentfile\utils.py
def humanize_bytes(amount):
    """Convert integer into human readable memory sized denomination.

    Parameters
    ----------
    amount : `int`
        total number of bytes.

    Returns
    -------
    `str` :
        human readable representation of the given amount of bytes.
    """
    if amount < 1024:
        return str(amount)
    if 1024 <= amount < 1_048_576:
        return f"{amount // 1024} KiB"
    if 1_048_576 <= amount < 1_073_741_824:
        return f"{amount // 1_048_576} MiB"
    return f"{amount // 1073741824} GiB"

normalize_piece_length(piece_length)

Verify input piece_length is valid and convert accordingly.

Parameters:

Name Type Description Default
piece_length `int` | `str`

The piece length provided by user.

required

Exceptions:

Type Description
PieceLengthValueError :

If piece length is improper value.

Returns:

Type Description
int

normalized piece length.

Source code in torrentfile\utils.py
def normalize_piece_length(piece_length) -> int:
    """Verify input piece_length is valid and convert accordingly.

    Parameters
    ----------
    piece_length : `int` | `str`
        The piece length provided by user.

    Returns
    -------
    piece_length : `int`
        normalized piece length.

    Raises
    ------
    PieceLengthValueError :
        If piece length is improper value.
    """
    if isinstance(piece_length, str):
        if piece_length.isnumeric():
            piece_length = int(piece_length)
        else:
            raise PieceLengthValueError(piece_length)

    if 13 < piece_length < 26:
        return 2 ** piece_length
    if piece_length <= 13:
        raise PieceLengthValueError(piece_length)

    log = int(math.log2(piece_length))
    if 2 ** log == piece_length:
        return piece_length
    raise PieceLengthValueError

path_piece_length(path)

Calculate piece length for input path and contents.

Parameters:

Name Type Description Default
path `str`

The absolute path to directory and contents.

required

Returns:

Type Description
`int`

The size of pieces of torrent content.

Source code in torrentfile\utils.py
def path_piece_length(path):
    """Calculate piece length for input path and contents.

    Parameters
    ----------
    path : `str`
        The absolute path to directory and contents.

    Returns
    -------
    piece_length : `int`
        The size of pieces of torrent content.
    """
    psize = path_size(path)
    return get_piece_length(psize)

path_size(path)

Return the total size of all files in path recursively.

Parameters:

Name Type Description Default
path `str`

path to target file or directory.

required

Returns:

Type Description
`int`

total size of files.

Source code in torrentfile\utils.py
def path_size(path):
    """Return the total size of all files in path recursively.

    Parameters
    ----------
    path : `str`
        path to target file or directory.

    Returns
    -------
    size : `int`
        total size of files.
    """
    total_size, _ = filelist_total(path)
    return total_size

path_stat(path)

Calculate directory statistics.

Parameters:

Name Type Description Default
path `str`

The path to start calculating from.

required

Returns:

Type Description
`list`

List of all files contained in Directory

Source code in torrentfile\utils.py
def path_stat(path):
    """Calculate directory statistics.

    Parameters
    ----------
    path : `str`
        The path to start calculating from.

    Returns
    -------
    filelist : `list`
        List of all files contained in Directory
    size : `int`
        Total sum of bytes from all contents of dir
    piece_length : `int`
        The size of pieces of the torrent contents.
    """
    total_size, filelist = filelist_total(path)
    piece_length = get_piece_length(total_size)
    return (filelist, total_size, piece_length)