Easy Bytes

`py_simple.easy_bytes`

easy_bytes turns byte counts into readable sizes and back.

`EasyBytesError`

Bases: Exception

Raised when a size cannot be converted.

Parameters:

Name	Type	Description	Default
`message`	`str`	Description of what went wrong.	required

`add_bytes(values, decimal=False)`

Add up a list of sizes and return the total in bytes.

Each value is either an integer (already a byte count) or a size label such as "1 KiB" (1024 bytes). Labels such as "1 KB" follow the same rule as human_to_bytes: 1024 bytes by default, or 1000 bytes with decimal=True.

Parameters:

Name	Type	Description	Default
`values`	`list`	Byte counts (non-negative integers) and/or size labels. A tuple is accepted too. An empty list adds up to 0.	required
`decimal`	`bool`	When `True`, `KB`-style units use factors of 1000. Defaults to `False`.	`False`

Returns:

Name	Type	Description
`int`	`int`	The sum of all the values, in bytes.

Raises:

Type	Description
`EasyBytesError`	If `values` is not a list or a tuple, if an item is neither a non-negative integer nor a string, if a string is not a valid size label, or if `decimal` is not a boolean.

`bytes_to_human(num_bytes, binary=False, decimal=False)`

Turn a byte count into a short label such as "1.5 KB".

By default, KB, MB, GB and TB count in factors of 1024, as they always have. Use binary=True to get the same numbers spelled with KiB, MiB, GiB and TiB, or decimal=True to count in factors of 1000.

Parameters:

Name	Type	Description	Default
`num_bytes`	`int`	Number of bytes. Must be zero or greater.	required
`binary`	`bool`	When `True`, label the size with `KiB`, `MiB`, `GiB` and `TiB` (1 KiB is 1024 bytes). Defaults to `False`.	`False`
`decimal`	`bool`	When `True`, use decimal units where 1 KB is 1000 bytes. Defaults to `False`, where 1 KB is 1024 bytes. Cannot be combined with `binary=True`.	`False`

Returns:

Name	Type	Description
`str`	`str`	A size label using B, KB, MB, GB, or TB (or KiB, MiB, GiB, TiB when `binary` is `True`).

Raises:

Type	Description
`EasyBytesError`	If `num_bytes` is not a non-negative integer, if `binary` or `decimal` is not a boolean, or if both are `True`.

Example

The Py_simple WayThe Traditional Way

from py_simple import bytes_to_human

print(bytes_to_human(1536))
print(bytes_to_human(1536, binary=True))
print(bytes_to_human(1500, decimal=True))

size = 1536
label = f"{size / 1024:.1f} KB" if size >= 1024 else f"{size} B"

size = 1536
label = f"{size / 1024:.1f} KiB" if size >= 1024 else f"{size} B"

size = 1500
label = f"{size / 1000:.1f} KB" if size >= 1000 else f"{size} B"

`human_to_bytes(label, decimal=False)`

Turn a size label such as "1.5 KB" back into a byte count.

By default, KB, MB, GB and TB count in factors of 1024, as they always have, so "1 KB" is 1024 bytes. KiB, MiB, GiB and TiB always count in factors of 1024. Pass decimal=True to make KB, MB, GB and TB count in factors of 1000 instead, so "1 KB" is 1000 bytes. A fractional byte is truncated.

Parameters:

Name	Type	Description	Default
`label`	`str`	A number plus a unit: B, KB, MB, GB, TB, KiB, MiB, GiB or TiB.	required
`decimal`	`bool`	When `True`, `KB`-style units use factors of 1000. Defaults to `False`.	`False`

Returns:

Name	Type	Description
`int`	`int`	The size in bytes.

Raises:

Type	Description
`EasyBytesError`	If `label` is not a recognized size, does not convert to a finite byte count, or if `decimal` is not a boolean.

Example

The Py_simple WayThe Traditional Way

from py_simple import human_to_bytes

print(human_to_bytes("1.5 KB"))
print(human_to_bytes("1.5 KB", decimal=True))
print(human_to_bytes("1.5 KiB"))

number, unit = "1.5 KB".split()
print(int(float(number) * 1024))

number, unit = "1.5 KB".split()
print(int(float(number) * 1000))

number, unit = "1.5 KiB".split()
print(int(float(number) * 1024))

`percent_free(used, total)`

Report how much of a storage total is still free.

Parameters:

Name	Type	Description	Default
`used`	`int`	Bytes already used. Must be a non-negative integer no greater than `total`.	required
`total`	`int`	Bytes available in total. Must be greater than 0.	required

Returns:

Name	Type	Description
`float`	`float`	The free share as a percent, rounded to one decimal place.

Raises:

Type	Description
`EasyBytesError`	If the numbers are not valid byte counts, if `total` is not positive, or if `used` exceeds `total`.

Example

The Py_simple WayThe Traditional Way

from py_simple import percent_free

print(percent_free(250, 1000))

used = 250
total = 1000
print(round((total - used) / total * 100, 1))

`percent_used(used, total)`

Report how much of a storage total is already used.

Parameters:

Name	Type	Description	Default
`used`	`int`	Bytes already used.	required
`total`	`int`	Bytes available in total. Must be greater than 0.	required

Returns:

Name	Type	Description
`float`	`float`	The used share as a percent, rounded to one decimal place.

Raises:

Type	Description
`EasyBytesError`	If the numbers are not valid byte counts, or if `total` is not positive.

Example

The Py_simple WayThe Traditional Way

from py_simple import percent_used

print(percent_used(250, 1000))

print(round(250 / 1000 * 100, 1))

`remaining_bytes(used, total)`

Calculates how many bytes remain in a storage total.

Parameters:

Name	Type	Description	Default
`used`	`int`	Bytes already used. Must be a non-negative integer no greater than `total`.	required
`total`	`int`	Total capacity in bytes. Must be a non-negative integer.	required

Returns:

Name	Type	Description
`int`	`int`	Unused bytes, such as 750 for 250 used out of 1000. A zero-capacity or full storage total has zero remaining bytes.

Raises:

Type	Description
`EasyBytesError`	If either count is negative, is not an integer, is a boolean, or if `used` exceeds `total`.

Example

The Py_simple WayThe Traditional Way

from py_simple import remaining_bytes

print(remaining_bytes(250, 1000))

used = 250
total = 1000
print(total - used)