Justbytes

https://pythonhosted.org/justbytes/
Admin
Justbytes is a Python library for handling precise computation and arithmetic operations with...
Tokens:11,578
Snippets:143
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get string components with getStringInfo

Source: https://pythonhosted.org/justbytes/_sources/tutorial.txt

Get the components of the string output rather than the whole string value. This example shows the default configuration and a configuration with min_value=10.

```python
>>> size.getStringInfo(ValueConfig())
(Radix(True,[8],[0, 0],[],10), 0, GiB)
>>> size.getStringInfo(ValueConfig(min_value=10))
(Radix(True,[8, 1, 9, 2],[0, 0],[],10), 0, MiB)
```

--------------------------------

### Get string info with getStringInfo

Source: https://pythonhosted.org/justbytes/tutorial.html

Sometimes it is desirable to get the components of the string output rather than the whole string value. getStringInfo() takes the same configuration parameters as getString().

```python
>>> size.getStringInfo(ValueConfig())
(Radix(True,[8],[0, 0],[],10), 0, GiB)

```

--------------------------------

### Configure string representation with getString

Source: https://pythonhosted.org/justbytes/tutorial.html

The string representation is configurable through the default configuration and also by parameters to the getString() method. This example shows various configurations.

```python
>>> import justbases
>>> display_impl = justbases.String
>>> config = StringConfig(ValueConfig(), DisplayConfig(), display_impl)
>>> size.getString(config)
'8 GiB'
>>> strip = StripConfig(strip_whole=False)
>>> display = DisplayConfig(strip_config=strip)
>>> config = StringConfig(ValueConfig(), display, display_impl)
>>> size.getString(config)
'8.00 GiB'
>>> value = ValueConfig(min_value=10)
>>> config = StringConfig(value, DisplayConfig(), display_impl)
>>> size.getString(config)
'8192 MiB'

```

--------------------------------

### Range.getStringInfo

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._size.html

Method to get a representation of the size for display.

```APIDOC
## Range.getStringInfo(config)

### Description
Returns a representation of the size.

### Method
getStringInfo

### Parameters
- **config** (ValueConfig) - Required - Representation configuration.

### Returns
- tuple of Radix * int * unit - A tuple representing the number to display.
```

--------------------------------

### Exact representation with max_places=None

Source: https://pythonhosted.org/justbytes/tutorial.html

To get an exact representation, set the configuration max_places value to None. The final list indicates the repeating values after the radix.

```python
>>> (size / 3).getStringInfo(ValueConfig(max_places=None))
(Radix(True,[2],[],[6],10), 0, GiB)

```

--------------------------------

### Range.getString

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._size.html

Method to get a string representation of the size.

```APIDOC
## Range.getString(config)

### Description
Returns a string representation of the size.

### Method
getString

### Parameters
- **config** (StringConfig) - Required - The configuration for the string representation.

### Returns
- str - A string representation of the size.

### Raises
- RangeValueError - If configuration is not satisfiable.
```

--------------------------------

### Round to whole byte values

Source: https://pythonhosted.org/justbytes/tutorial.html

Round to get whole byte values, if desired.

```python
>>> size / 3
Range(Fraction(8589934592, 3))
>>> (size / 3).roundTo(B, ROUND_DOWN)
Range(Fraction(2863311530, 1))

```

--------------------------------

### getStringInfo with min_value

Source: https://pythonhosted.org/justbytes/tutorial.html

getStringInfo() with a ValueConfig that has min_value set to 10.

```python
>>> size.getStringInfo(ValueConfig(min_value=10))
(Radix(True,[8, 1, 9, 2],[0, 0],[],10), 0, MiB)

```

--------------------------------

### Import justbytes

Source: https://pythonhosted.org/justbytes/tutorial.html

Import the justbytes module to access Range and related classes.

```python
>>> from justbytes import *

```

--------------------------------

### Import justbytes public interface and handle RangeError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes.html

Import the public interface of justbytes directly from the top-level module. Creates a Range of 24 KiB and attempts to add 32, catching the RangeError that is raised.

```python
from justbytes import Range
from justbytes import KiB
from justbytes import RangeError

s = Range(24, KiB)
try:
    s + 32
except RangeError as e:
    raise e

```

--------------------------------

### takeuntil(pred, seq)

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._util.generators.html

Documentation for the takeuntil generator function.

```APIDOC
## takeuntil(pred, seq)

### Description
Like next(), but yields all values until the first matching value.

### Method
Function call

### Endpoint
justbytes._util.generators.takeuntil

### Parameters
- **pred** (bool) - Required - A predicate, return False if the value is not satisfactory
- **seq** - Required - A sequence of values

### Response
Yields values until the first matching value.
```

--------------------------------

### justbytes._constants.BinaryUnits

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._constants.html

Class to store binary unit constants (KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB).

```APIDOC
## justbytes._constants.BinaryUnits

### Description
Class to store binary unit constants.

### Attributes
- `EiB` - EiB constant
- `FACTOR` - 1024
- `GiB` - GiB constant
- `KiB` - KiB constant
- `MiB` - MiB constant
- `PiB` - PiB constant
- `TiB` - TiB constant
- `YiB` - YiB constant
- `ZiB` - ZiB constant

```

--------------------------------

### Config.set_display_config

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._config.html

Sets the configuration for superficial aspects of display, such as formatting and units.

```APIDOC
## Config.set_display_config

### Description
Sets the configuration for superficial aspects of display, such as formatting and units.

### Method
classmethod

### Signature
`set_display_config(config)`

### Parameters
- **config** (DisplayConfig) - Required - A configuration object for display settings.

### Returns
None

```

--------------------------------

### Range.componentsList

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._size.html

Method to yield representations of the size for every unit.

```APIDOC
## Range.componentsList(binary_units=True)

### Description
Yields a representation of this size for every unit, decomposed into a Fraction value and a unit specifier tuple.

### Method
componentsList

### Parameters
- **binary_units** (bool) - Optional - If True, use binary units; else SI.

### Returns
- Generator of tuples - Each tuple contains a Fraction value and a unit specifier.
```

--------------------------------

### justbytes._constants.Units

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._constants.html

Generic class for units.

```APIDOC
## justbytes._constants.Units

### Description
Generic class for units.

### Methods
- `UNITS()` - Class method: Units of this class.
- `max_exponent()` - Class method: The maximum exponent for which there is a unit.
  - Returns: the maximum exponent (int)
- `unit_for_exp(exponent)` - Class method: Get the unit for the given exponent.
  - Parameters: exponent (int) - the exponent, 0 <= exponent < len(UNITS())

```

--------------------------------

### Create a Range object

Source: https://pythonhosted.org/justbytes/tutorial.html

Create a Range object from a numeric value and a unit specification, e.g., 8 GiB.

```python
>>> size = Range(8, GiB)

```

--------------------------------

### Display in selected units

Source: https://pythonhosted.org/justbytes/tutorial.html

Display the Range in selected units, e.g., YiB.

```python
>>> size.getString(StringConfig(ValueConfig(unit=YiB), DisplayConfig(), display_impl))
'> 0.00 YiB'

```

--------------------------------

### justbytes._constants.Unit

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._constants.html

Class to encapsulate unit information.

```APIDOC
## justbytes._constants.Unit

### Description
Class to encapsulate unit information.

### Attributes
- `abbr` - abbreviation for unit, precedes 'B'
- `factor` - numeric multiple of bytes
- `prefix` - prefix for 'bytes'

```

--------------------------------

### justbytes._constants.B

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._constants.html

The universal unit, bytes.

```APIDOC
## justbytes._constants.B

### Description
The universal unit, bytes.

```

--------------------------------

### next_or_last(pred, seq, default=None)

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._util.generators.html

Documentation for the next_or_last generator function.

```APIDOC
## next_or_last(pred, seq, default=None)

### Description
Returns the first element that matches the predicate or the last element in the sequence. If the sequence is empty, returns the default value.

### Method
Function call

### Endpoint
justbytes._util.generators.next_or_last

### Parameters
- **pred** (bool) - Required - A predicate, return False if the value is not satisfactory
- **seq** - Required - A sequence of values
- **default** - Optional - Returned if seq is empty, default is None

### Response
Returns the first matching element, the last element, or the default value.
```

--------------------------------

### justbytes._errors.RangeUnsupportedOpError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Error when executing unsupported operation on Range.

```APIDOC
## RangeUnsupportedOpError

### Description
Error when executing unsupported operation on Range.

### Exception Type
`justbytes._errors.RangeUnsupportedOpError`

### Bases
- `justbytes._errors.RangeError`

### Usage
Raised when an unsupported operation is attempted on a Range.
```

--------------------------------

### justbytes._constants.DecimalUnits

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._constants.html

Class to store decimal unit constants (KB, MB, GB, TB, PB, EB, ZB, YB).

```APIDOC
## justbytes._constants.DecimalUnits

### Description
Class to store decimal unit constants.

### Attributes
- `EB` - EB constant
- `FACTOR` - 1000
- `GB` - GB constant
- `KB` - kB constant
- `MB` - MB constant
- `PB` - PB constant
- `TB` - TB constant
- `YB` - YB constant
- `ZB` - ZB constant

```

--------------------------------

### justbytes._constants.UNITS

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._constants.html

Function that returns all unit constants.

```APIDOC
## justbytes._constants.UNITS

### Description
All unit constants.

```

--------------------------------

### Range.convertTo

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._size.html

Method to convert the size to a specified unit.

```APIDOC
## Range.convertTo(spec=None)

### Description
Returns the size in the units indicated by the specifier.

### Method
convertTo

### Parameters
- **spec** (units specifier or Range) - Optional - A units specifier.

### Returns
- fractions.Fraction - A numeric value in the units indicated by the specifier.

### Raises
- RangeValueError - If unit specifier is non-positive.
```

--------------------------------

### Config.set_display_impl

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._config.html

Sets the display implementation class used for rendering byte ranges.

```APIDOC
## Config.set_display_impl

### Description
Sets the display implementation class used for rendering byte ranges.

### Method
classmethod

### Signature
`set_display_impl(impl)`

### Parameters
- **impl** (type) - Required - The display implementation class.

### Returns
None

```

--------------------------------

### justbytes._errors.RangeNonsensicalBinOpError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Error when requesting a binary operation that doesn't make sense.

```APIDOC
## RangeNonsensicalBinOpError

### Description
Error when requesting a binary operation that doesn't make sense.

### Exception Type
`justbytes._errors.RangeNonsensicalBinOpError`

### Bases
- `justbytes._errors.RangeNonsensicalOpError`

### Constructor Parameters
- `operator` (type: unknown) - The operator involved in the operation.
- `other` (type: unknown) - The other operand.

### Usage
Raised when a binary operation is nonsensical.
```

--------------------------------

### justbytes._errors.RangeError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Generic Range error exception.

```APIDOC
## RangeError

### Description
Generic Range error.

### Exception Type
`justbytes._errors.RangeError`

### Bases
- `exceptions.Exception`

### Usage
Raised for generic range-related errors.
```

--------------------------------

### Display Range string representation

Source: https://pythonhosted.org/justbytes/tutorial.html

Display the Range object using its string representation, which uses units.

```python
>>> str(size)
'8 GiB'

```

--------------------------------

### Config.set_value_config

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._config.html

Sets the configuration for computing the value of string representation.

```APIDOC
## Config.set_value_config

### Description
Sets the configuration for computing the value of string representation.

### Method
classmethod

### Signature
`set_value_config(config)`

### Parameters
- **config** (ValueConfig) - Required - A configuration object for value computation.

### Returns
None

```

--------------------------------

### justbytes._errors.RangePowerResultError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Error when requesting an operation that would yield a byte power.

```APIDOC
## RangePowerResultError

### Description
Error when requesting an operation that would yield a byte power.

### Exception Type
`justbytes._errors.RangePowerResultError`

### Bases
- `justbytes._errors.RangeUnrepresentableResultError`

### Usage
Raised when an operation would result in a byte power that cannot be represented.
```

--------------------------------

### justbytes._errors.RangeNonsensicalBinOpValueError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Error when requesting a binary operation with a nonsense value.

```APIDOC
## RangeNonsensicalBinOpValueError

### Description
Error when requesting a binary operation with a nonsense value.

### Exception Type
`justbytes._errors.RangeNonsensicalBinOpValueError`

### Bases
- `justbytes._errors.RangeNonsensicalOpError`

### Constructor Parameters
- `operator` (type: unknown) - The operator involved in the operation.
- `other` (type: unknown) - The other operand.

### Usage
Raised when a binary operation is attempted with a nonsensical value.
```

--------------------------------

### Display Range internal representation

Source: https://pythonhosted.org/justbytes/tutorial.html

Display the Range object using its internal representation, which shows the number of bytes as a Fraction.

```python
>>> size
Range(Fraction(8589934592, 1))

```

--------------------------------

### justbytes._errors.RangeNonsensicalOpError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Error when requesting an operation that doesn't make sense.

```APIDOC
## RangeNonsensicalOpError

### Description
Error when requesting an operation that doesn't make sense.

### Exception Type
`justbytes._errors.RangeNonsensicalOpError`

### Bases
- `justbytes._errors.RangeUnsupportedOpError`

### Usage
Raised when an operation is nonsensical.
```

--------------------------------

### Sum with additive identity

Source: https://pythonhosted.org/justbytes/tutorial.html

Sum a list of Range objects using the sum method and the additive identity.

```python
>>> sum([], AI)
Range(0)

```

--------------------------------

### Range.roundTo

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._size.html

Method to round the size to a specified unit.

```APIDOC
## Range.roundTo(unit, rounding, bounds=(None, None))

### Description
Rounds to the unit specified as a named constant or a Range.

### Method
roundTo

### Parameters
- **unit** (any non-negative Range or element in _constants.UNITS()) - Required - A unit specifier.
- **rounding** (a field of _constants.RoundingMethods) - Required - Rounding mode to use.
- **bounds** (tuple of (Range or NoneType) * (Range or NoneType)) - Optional - Lower and upper bounds on the value.

### Returns
- Range - Appropriately rounded Range.

### Raises
- RangeValueError - On unusable arguments.
```

--------------------------------

### Range.magnitude

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._size.html

Property that returns the magnitude of the size in bytes.

```APIDOC
## Range.magnitude

### Description
Returns the number of bytes.

### Returns
- Fraction - The number of bytes.
```

--------------------------------

### justbytes._errors.RangeFractionalResultError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Error when Range construction is strict.

```APIDOC
## RangeFractionalResultError

### Description
Error when Range construction is strict.

### Exception Type
`justbytes._errors.RangeFractionalResultError`

### Bases
- `justbytes._errors.RangeUnrepresentableResultError`

### Usage
Raised when a strict Range construction would result in a fractional value.
```

--------------------------------

### Range.components

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._size.html

Method to decompose a Range object into a Fraction value and a unit specifier tuple.

```APIDOC
## Range.components(config=ValueConfig(base=10, binary_units=True, exact_value=False, max_places=2, min_value=1, rounding_method=RoundingMethod, unit=None))

### Description
Returns a representation of this size, decomposed into a Fraction value and a unit specifier tuple.

### Method
components

### Parameters
- **config** (ValueConfig) - Optional - Configuration for the decomposition.

### Returns
- tuple of Fraction and unit - A pair of a decimal value and a unit.

### Raises
- RangeValueError - If min_value is not usable.
```

--------------------------------

### Arithmetic operations on Range

Source: https://pythonhosted.org/justbytes/tutorial.html

Various arithmetic operations on Range objects are available, including multiplication by integers and fractions.

```python
>>> str(size * 8)
'64 GiB'
>>> str(size * Fraction(1, 2))
'4 GiB'

```

--------------------------------

### Sum without additive identity - RangeError

Source: https://pythonhosted.org/justbytes/tutorial.html

If the additive identity is not specified, a RangeError exception may be raised because addition must be type-correct.

```python
>>> l = [Range(32)]
>>> sum(l)
Traceback (most recent call last):
...

```

--------------------------------

### Round to whole byte values

Source: https://pythonhosted.org/justbytes/_sources/tutorial.txt

Round a Range object to whole byte values using roundTo with ROUND_DOWN.

```python
>>> size / 3
Range(Fraction(8589934592, 3))
>>> (size / 3).roundTo(B, ROUND_DOWN)
Range(Fraction(2863311530, 1))
```

--------------------------------

### justbytes._errors.RangeUnrepresentableResultError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Error when requesting an operation that yields units that cannot be represented with Range.

```APIDOC
## RangeUnrepresentableResultError

### Description
Error when requesting an operation that yields units that cannot be represented with Range, e.g., when multiplying a Range by a Range.

### Exception Type
`justbytes._errors.RangeUnrepresentableResultError`

### Bases
- `justbytes._errors.RangeUnsupportedOpError`

### Usage
Raised when an operation produces a result that cannot be represented as a Range.
```

--------------------------------

### Additive identity value

Source: https://pythonhosted.org/justbytes/tutorial.html

The additive identity is just Range(0).

```python
>>> AI
Range(0)

```

--------------------------------

### justbytes._errors.RangeValueError

Source: https://pythonhosted.org/justbytes/justbytes/justbytes._errors.html

Raised when a parameter has an unacceptable value or type.

```APIDOC
## RangeValueError

### Description
Raised when a parameter has an unacceptable value. May also be raised when the parameter has an unacceptable type.

### Exception Type
`justbytes._errors.RangeValueError`

### Bases
- `justbytes._errors.RangeError`

### Constructor Parameters
- `value` (type: unknown) - The unacceptable value.
- `param` (type: unknown) - The parameter name.
- `msg` (type: unknown, optional) - Optional custom message.

### Usage
Raised when a parameter value or type is invalid.
```

--------------------------------

### Add two Range objects

Source: https://pythonhosted.org/justbytes/_sources/tutorial.txt

Add two Range objects. The result may be approximate, indicated by '>' when the value cannot be shown precisely with the current defaults.

```python
>>> new_size = size + Range(1, KiB)
>>> str(new_size)
'> 8.00 GiB'
```

--------------------------------

### Arithmetic with two Range operands

Source: https://pythonhosted.org/justbytes/tutorial.html

Some arithmetic operations work with two Range operands. The symbol '>' indicates that the value is approximate and the actual value represented is greater than that displayed.

```python
>>> new_size = size + Range(1, KiB)
>>> str(new_size)
'> 8.00 GiB'

```

--------------------------------

### Sum without additive identity - wrong type

Source: https://pythonhosted.org/justbytes/tutorial.html

If the list argument is empty, the result will have the wrong type, int.

```python
>>> res = sum(l[1:])
>>> res
0
>>> type(res)
<type 'int'>

```
Tokens:
Raw