Utils - TorrentFile

# 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)