Base Unit Types (tendril.utils.types.unitbase
)¶
The Types provided in this module are not intended for direct use. Instead, they provide reusable primitives which can be sub-classed to provide functional Types.
Ideally, all Unit classes should derive from the UnitBase
class
provided here. In practice, only the newer Types follow this inheritance,
while the older ones still need to be migrated to this form.
Module Contents
UnitBase (value, _dostr, _parse_func) |
The base class for all tendril.utils.types units. |
NumericalUnitBase (value, _orders, _dostr, ...) |
The base class for all tendril.utils.types numerical units. |
DummyUnit ([value]) |
This class provides a type for placeholder objects. |
parse_none (value) |
A placeholder parse function which can be used if the Unit requires / supports no parsing. |
parse_percent (value) |
A parse function for use by the Percentage Type and its subclasses. |
Percentage (value) |
A base Unit class which provides support for Types that are essentially percentages. |
See also
tendril.utils.types
, for an overview applicable to
most types defined in Tendril.
-
class
tendril.utils.types.unitbase.
TypedComparisonMixin
[source]¶ Bases:
object
This mixin allows implementing comparison operators in a Python 3 compatible way.
Two instances of a class are compared using their
_cmpkey()
methods. If the instances have a different__class__
, the comparison is not implemented. A single exception is implemented, for when the other instance is of a numerical type, with value 0.
-
class
tendril.utils.types.unitbase.
UnitBase
(value, _dostr, _parse_func)[source]¶ Bases:
object
The base class for all
tendril.utils.types
units.When instantiated, the value param is processed as follows :
str
value is passed though _parse_func, and whatever it returns is stored.numbers.Number
values are first converted intodecimal.Decimal
and then stored.- All other value types are simply stored as is.
Parameters: - value – The core value to be stored.
- _dostr – The canonical unit / order string to use.
- _parse_func – The function used to parse string values into an actual value in the canonical unit.
Arithmetic Operations
This class supports no arithmetic operations.
-
value
¶ Returns: The core value of the Unit instance, in it’s canonical unit.
-
class
tendril.utils.types.unitbase.
NumericalUnitBase
(value, _orders, _dostr, _parse_func)[source]¶ Bases:
tendril.utils.types.unitbase.TypedComparisonMixin
,tendril.utils.types.unitbase.UnitBase
The base class for all
tendril.utils.types
numerical units.Provides the patterns used by the various Numerical Units to provide their functionality. This class represents and implements the core ideas that remain valid across Units (for the most part). The various methods and functions implemented here establish the minimum required functionality and behaviour expected of all numerical units.
Specific numerical unit classes may override the methods present here to tweak the implementation and/or the interface as per the requirements of the quantity they represent, as long as they stay true to the spirit of the architecture.
Parameters: - value – The core value to be stored.
- _orders – The recognized orders / units for the Unit.
- _dostr – The canonical unit / order string to use.
- _parse_func – The function used to parse string values into an actual value in the canonical unit.
See also
The orders Parameter
The orders parameter can either be a list of strings or a list of tuples.
- In case it is a list of str, it is assumed that each string represents a unit value 1000 times smaller than the next.
- In case it is a list of tuple, it is assumed that the first element of the tuple is the string representation of the order, and the second element is the multipicative factor relative to the default order string.
- In both cases, note that first order within which the unit value’s representation lies between 1 and 1000 is used to produce the unit’s string representation. As such, you should place higher priority or more ‘standard’ units towards the beginning of the list.
Arithmetic Operations
__add__
(other)Addition of two Unit class instances of the same type returns a Unit class instance of the same type, with the sum of the two operands as it’s value. __sub__
(other)Subtraction of two Unit class instances of the same type returns a Unit class instance of the same type, with the difference of the two operands as it’s value. __mul__
(other)Multiplication of one Unit type class instance with a numerical type results in a Unit type class instance of the same type, whose value is the Unit type operand’s value multiplied by the numerical operand’s value. __div__
(other)Division of one Unit type class instance with a numerical type results in a Unit type class instance of the same type, whose value is the Unit type operand’s value divided by the numerical operand’s value. __cmpkey
-
__add__
(other)[source]¶ Addition of two Unit class instances of the same type returns a Unit class instance of the same type, with the sum of the two operands as it’s value.
If the other operand is a numerical type and evaluates to 0, this object is simply returned unchanged.
Addition with all other Types / Classes is not supported.
-
__mul__
(other)[source]¶ Multiplication of one Unit type class instance with a numerical type results in a Unit type class instance of the same type, whose value is the Unit type operand’s value multiplied by the numerical operand’s value.
Multiplication with all other Types / Classes is not supported.
-
__div__
(other)[source]¶ Division of one Unit type class instance with a numerical type results in a Unit type class instance of the same type, whose value is the Unit type operand’s value divided by the numerical operand’s value.
In this case, the first operand must be a Unit type class instance, and not the reverse.
Division of one Unit type class instance by another of the same type returns a numerical value, which is obtained by performing the division with the operands’ value.
Division with all other Types / Classes is not supported.
-
__sub__
(other)[source]¶ Subtraction of two Unit class instances of the same type returns a Unit class instance of the same type, with the difference of the two operands as it’s value.
If the other operand is a numerical type and evaluates to 0, this object is simply returned unchanged.
Subtraction with all other Types / Classes is not supported.
-
_cmpkey
()[source]¶ The comparison of two Unit type class instances of the same type behaves identically to the comparison of the operands’ values.
Comparison with all other Types / Classes is not supported.
-
natural_repr
¶
-
quantized_repr
¶
-
integral_repr
¶
-
class
tendril.utils.types.unitbase.
DummyUnit
(value=None)[source]¶ Bases:
tendril.utils.types.unitbase.UnitBase
This class provides a type for placeholder objects. The original use case is for handling wave boundaries in streaming protocols.
Does not support any arithmetic operations.
-
tendril.utils.types.unitbase.
parse_none
(value)[source]¶ A placeholder parse function which can be used if the Unit requires / supports no parsing.
-
tendril.utils.types.unitbase.
parse_percent
(value)[source]¶ A parse function for use by the
Percentage
Type and its subclasses.
-
class
tendril.utils.types.unitbase.
Percentage
(value)[source]¶ Bases:
tendril.utils.types.unitbase.NumericalUnitBase
A base Unit class which provides support for Types that are essentially percentages.
The contribution this base class makes is to be able to parse percentage strings so that the Descendant class need not.
Only the standard
NumericalUnitBase
Arithmetic is supported by this class at this time.