TorrentFile API Documentation
Utils
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.
MissingPathError
— Path parameter is required to specify target content.PieceLengthValueError
— Piece Length parameter must equal a perfect power of 2.
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
)
(`int`) — Calculate the ideal piece length for bittorrent data.humanize_bytes
(
amount
)
(`str` :) — Convert integer into human readable memory sized denomination.next_power_2
(
value
)
(`int`) — Calculate the next perfect power of 2 equal to or greater than value.normalize_piece_length
(
piece_length
)
(piece_length : `int`) — Verify input piece_length is valid and convert accordingly.path_piece_length
(
path
)
(`int`) — Calculate piece length for input path and contents.path_size
(
path
)
(`int`) — Return the total size of all files in path recursively.path_stat
(
path
)
(`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). |
None |
Source code in torrentfile\utils.py
class MissingPathError(Exception):
"""Path parameter is required to specify target content.
Creating a .torrent file with no contents seems rather silly.
Parameters
----------
message : `any`
Message for user (optional).
"""
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)
__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). |
None |
Source code in torrentfile\utils.py
class PieceLengthValueError(Exception):
"""Piece Length parameter must equal a perfect power of 2.
Parameters
----------
message : `any`
Message for user (optional).
"""
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)
__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
-------
`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 |
Returns:
Type | Description |
---|---|
str |
human readable representation of the given amount of bytes. |
Source code in torrentfile\utils.py
def humanize_bytes(amount: int) -> str:
"""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"
next_power_2(value)
Calculate the next perfect power of 2 equal to or greater than value.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value |
`int` |
integer value that is less than some perfect power of 2. |
required |
Returns:
Type | Description |
---|---|
`int` |
The next power of 2 greater than value, or value if already power of 2. |
Source code in torrentfile\utils.py
def next_power_2(value):
"""Calculate the next perfect power of 2 equal to or greater than value.
Parameters
----------
value : `int`
integer value that is less than some perfect power of 2.
Returns
-------
`int`
The next power of 2 greater than value, or value if already power of 2.
"""
if not value & (value - 1) and value:
return value
start = 1
while start < value:
start <<= 1
return start
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
-------
`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
-------
`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
-------
`list`
List of all files contained in Directory
`int`
Total sum of bytes from all contents of dir
`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)