cfx_utils.token_unit

cfx_utils.token_unit

A module providing methods to operate token units in Conflux.

Currently cfx_utils.token_unit.Drip, cfx_utils.token_unit.CFX and cfx_utils.token_unit.GDrip can be imported from cfx_utils.token_unit. These classes inherits from cfx_utils.token_unit.AbstractTokenUnit and support computing or comparing:

>>> from cfx_utils.token_unit import CFX, Drip
>>> CFX(1)
1 CFX
>>> CFX(1).value
1
>>> Drip(1)
1 Drip
>>> CFX(1) == Drip(1) * 10**18
True
>>> Drip(1) * 2
2 Drip
>>> CFX(1) / Drip(1)
Decimal('1000000000000000000')
>>> Drip(1) / 2
Traceback (most recent call last):
    ...
cfx_utils.exceptions.InvalidTokenOperation: ...
class cfx_utils.token_unit.Drip(value: str, base: int = 10)[source]
class cfx_utils.token_unit.Drip(value: Union[int, decimal.Decimal, float, cfx_utils.token_unit.AbstractTokenUnit[typing_extensions.Self]])

The base token unit used in Conflux, corresponding to Ethereum’s Wei. Drip inherits from AbstractTokenUnit so it supports __eq__(), __le__(), __add__(), etc.

Initialize a token object of base unit (e.g. Drip). The minimum unit is 1. Error will be raised if value and base are not valid.

Parameters

  • value (Union[str,int,decimal.Decimal,float,AbstractTokenUnit[Self]]) – value to init the token, should be a number which can convert to int or another token unit which share the same

  • base (int) – base to init a str-typed value, defaults to 10

>>> from cfx_utils.token_unit import Drip
>>> Drip(10)
10 Drip
>>> Drip("0x10", base=16)
16 Drip
>>> Drip(0.5)
_base_unit

alias of cfx_utils.token_unit.Drip

_decimals: ClassVar[int] = 0

The class variable to defining relation between current token unit and _base_unit.

>>> from cfx_utils import CFX, Drip
>>> CFX._decimals
18
>>> Drip._decimals
0
classmethod get_derived_units_dict() → Dict[str, Type[cfx_utils.token_unit.AbstractTokenUnit[typing_extensions.Self]]]
Return Dict

returns a dict object containing token_name -> token_unit_class mapping

>>> from cfx_utils.token_unit import Drip
>>> Drip.get_derived_units_dict()
{'Drip': <class 'cfx_utils.token_unit.Drip'>,
'CFX': <class 'cfx_utils.token_unit.CFX'>,
'GDrip': <class 'cfx_utils.token_unit.GDrip'>}
classmethod register_derived_unit(derived_unit: Type[cfx_utils.token_unit.AbstractDerivedTokenUnit[typing_extensions.Self]]) → None

Register a new derived token unit to a base unit

Raises

ValueError – if a token unit with the same name is already registered

>>> from cfx_utils import Drip, AbstractDerivedTokenUnit
>>> # The AbstractDerivedTokenUnit[Drip] is used for type hints
>>> class uCFX(AbstractDerivedTokenUnit[Drip]):
...     _decimals = 12
...
>>> Drip.register_derived_unit(uCFX)
>>> uCFX(1)
1 uCFX
>>> uCFX(1).to_base_unit()
1000000000000 Drip
to(target_unit: Union[str, Type[AnyTokenUnit]]) → Union[AnyTokenUnit, cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit]]

Return a new TokenUnit object in target_unit

Parameters

target_unit (Union[str,Type[AnyTokenUnit]]) – the target token unit to convert to

Returns

a new token unit object of target unit

Examples

>>> from cfx_utils.token_unit import CFX, GDrip
>>> val = CFX(1)
>>> val.to(GDrip)
1000000000 GDrip
>>> val.to("Drip")
1000000000000000000 Drip
to_base_unit() → BaseTokenUnit

Return a new token unit object in _base_unit

Examples

>>> from cfx_utils import CFX
>>> CFX(1).to_base_unit()
1000000000000000000 Drip
property value
class cfx_utils.token_unit.CFX(value: Union[int, decimal.Decimal, str, float, cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit]])[source]

A derived token unit from Drip in Conflux, corresponding to Ethereum’s Ether. CFX inherits from AbstractTokenUnit so it supports __eq__(), __le__(), __add__(), etc. 1 CFX = 10**18 Drip.

_base_unit

alias of cfx_utils.token_unit.Drip

_decimals: ClassVar[int] = 18

The class variable to defining relation between current token unit and _base_unit.

>>> from cfx_utils import CFX, Drip
>>> CFX._decimals
18
>>> Drip._decimals
0
to(target_unit: Union[str, Type[AnyTokenUnit]]) → Union[AnyTokenUnit, cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit]]

Return a new TokenUnit object in target_unit

Parameters

target_unit (Union[str,Type[AnyTokenUnit]]) – the target token unit to convert to

Returns

a new token unit object of target unit

Examples

>>> from cfx_utils.token_unit import CFX, GDrip
>>> val = CFX(1)
>>> val.to(GDrip)
1000000000 GDrip
>>> val.to("Drip")
1000000000000000000 Drip
to_base_unit() → BaseTokenUnit

Return a new token unit object in _base_unit

Examples

>>> from cfx_utils import CFX
>>> CFX(1).to_base_unit()
1000000000000000000 Drip
property value

Returns the token value as decimal.Decimal.

Return decimal.Decimal

returns the token value

Can be set using an int, decimal.Decimal, str or float

Raises

  • FloatWarning – it is recommended to use decimal.Decimal, when a float-typed value is used to set value, a warning will be raised

  • InvalidTokenValueType – the value type is not int, Decimal, str or float

  • InvalidTokenValuePrecision – the value cannot be divided exactly by its base unit

Examples

>>> from cfx_utils import CFX
>>> val = CFX(1)
>>> val.value = 0.5 # will raise a FloatWarning
>>> val
0.5 CFX
>>> val.value = 1/3
Traceback (most recent call last):
    ...
cfx_utils.exceptions.InvalidTokenValuePrecision: Not able to initialize <class 'cfx_utils.token_unit.CFX'>
with <class 'decimal.Decimal'> 0.333333333333333314829616256247390992939472198486328125 due to unexpected precision.
Try representing 0.333333333333333314829616256247390992939472198486328125 in <class 'decimal.Decimal'> properly,
or init token value in int from <class 'cfx_utils.token_unit.Drip'>
class cfx_utils.token_unit.AbstractTokenUnit(value: Union[cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit], int, decimal.Decimal, float])[source]

AbstractTokenUnit provides the implementation of token units computing operations, such as __eq__(), __le__(), __add__(), etc. Token unit object can be directly used as transaction gas price or the value field of transaction.

>>> from cfx_utils.token_unit import CFX, Drip
>>> CFX(1)
1 CFX
>>> CFX(1).value
1
>>> Drip(1)
1 Drip
>>> CFX(1) == Drip(1) * 10**18
True
>>> Drip(1) / 2
Traceback (most recent call last):
    ...
cfx_utils.exceptions.InvalidTokenOperation: ...
abstract __init__(value: Union[cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit], int, decimal.Decimal, float])[source]

Initialize self. See help(type(self)) for accurate signature.

to(target_unit: str) → AbstractTokenUnit[BaseTokenUnit][source]
to(target_unit: Type[AnyTokenUnit]) → AnyTokenUnit

Return a new TokenUnit object in target_unit

Parameters

target_unit (Union[str,Type[AnyTokenUnit]]) – the target token unit to convert to

Returns

a new token unit object of target unit

Examples

>>> from cfx_utils.token_unit import CFX, GDrip
>>> val = CFX(1)
>>> val.to(GDrip)
1000000000 GDrip
>>> val.to("Drip")
1000000000000000000 Drip
to_base_unit() → BaseTokenUnit[source]

Return a new token unit object in _base_unit

Examples

>>> from cfx_utils import CFX
>>> CFX(1).to_base_unit()
1000000000000000000 Drip
__eq__(other: Union[cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit], typing_extensions.Literal[0]]) → bool[source]

Whether self equals to other. other is supposed to be a token unit or 0. Other values are also viable but the result might be not as expected. If other is not a token unit nor 0, False will always be returned.

Raises

DangerEqualWarning – when the compared param is not 0 nor token unit

>>> CFX(0) == 0
True
>>> CFX(1) == 1 # will raise a warning
False
>>> CFX(1).value == 1
True
>>> CFX(1) == Drip(10**18)
True
__lt__(other: Union[cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit], typing_extensions.Literal[0]]) → bool[source]

Return self<value.

__le__(other: Union[cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit], typing_extensions.Literal[0]]) → bool[source]

Return self<=value.

__gt__(other: Union[cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit], typing_extensions.Literal[0]]) → bool[source]

Return self>value.

__ge__(other: Union[cfx_utils.token_unit.AbstractTokenUnit[BaseTokenUnit], typing_extensions.Literal[0]]) → bool[source]

Return self>=value.

__str__()[source]

Return str(self).

__repr__()[source]

Return repr(self).

__add__(other: typing_extensions.Self) → typing_extensions.Self[source]
__add__(other: AbstractTokenUnit[Self]) → typing_extensions.Self
__add__(other: AbstractTokenUnit[BaseTokenUnit]) → BaseTokenUnit

Add 2 object of AbstractTokenUnit with same _base_unit.

Raises

  • TokenUnitNotMatch – The 2 objects are not in same _base_unit

  • InvalidTokenValueType – The added object is not a AbstractTokenUnit object

Returns Union[BaseTokenUnit, Self]

If 2 units are in the same unit, return the same. Else, return the result in _base_unit

>>> from cfx_utils.token_unit import CFX, Drip, GDrip
>>> CFX(1) + Drip(1)
1000000000000000001 Drip
>>> CFX(1) + CFX(1)
2 CFX
>>> GDrip(1) + CFX(1)
1000000001000000000 Drip
__sub__(other: typing_extensions.Self) → typing_extensions.Self[source]
__sub__(other: AbstractTokenUnit[Self]) → typing_extensions.Self
__sub__(other: AbstractTokenUnit[BaseTokenUnit]) → BaseTokenUnit

Sub other from self with same _base_unit.

Raises

  • TokenUnitNotMatch – The 2 objects are not in same _base_unit

  • InvalidTokenValueType – other is not a AbstractTokenUnit object

  • NegativeTokenValueWarning – The value of the result is less than 0

Returns Union[BaseTokenUnit, Self]

If 2 units are in the same unit, return the same. Else, return the result in _base_unit

>>> from cfx_utils.token_unit import CFX, Drip, GDrip
>>> CFX(1) - Drip(1)
999999999999999999 Drip
>>> CFX(1) - CFX(1)
0 CFX
>>> GDrip(1) - CFX(1) # will raise a warning
-999999999000000000 Drip
__mul__(other: Union[int, decimal.Decimal, float]) → typing_extensions.Self[source]

Multiply self with other.

Raises

  • InvalidTokenOperation – other is a AbstractTokenUnit object or the returned result will not be in a valid value

  • NegativeTokenValueWarning – The value of the result is less than 0

  • FloatWarning – The multiplied time is a float

Returns Self

Returns the result in Self

>>> from cfx_utils.token_unit import Drip
>>> Drip(1) * 2
2 Drip
>>> Drip(1) * 0.5 # will raise a warning and an error
Traceback (most recent call last):
...
cfx_utils.exceptions.InvalidTokenOperation: Not able to execute operation __mul__ on (1 Drip, 0.5) due to invalid argument type
__truediv__(other: AbstractTokenUnit[BaseTokenUnit]) → decimal.Decimal[source]
__truediv__(other: Union[int, decimal.Decimal, float]) → typing_extensions.Self

Divide self with other. The other could be a number or another AbstractTokenUnit object sharing same _base_unit.

Raises

  • TokenUnitNotMatch – Another AbstractTokenUnit object is not in same _base_unit

  • InvalidTokenOperation – The returned result will not be in a valid value

  • NegativeTokenValueWarning – The value of the result is less than 0

  • FloatWarning – other is a float

Returns Union[Self, decimal.Decimal]

Returns the result depending on the type of other

>>> from cfx_utils.token_unit import Drip
>>> Drip(1) / Drip(2)
Decimal('0.5')
>>> Drip(2) / 2
1 Drip
__hash__()[source]

Return hash(self).

token_unit.to_int_if_drip_units() → Union[int, T]
A util function to convert token units derived from Drip to int.
If the input is in token unit derived from Drip, then return a int corresponding to token value in Drip.
Else return the original input
>>> from cfx.token_unit import to_int_if_drip_units, CFX
>>> to_int_if_drip_units(CFX(1))
1000000000000000000
>>> to_int_if_drip_units(10**18)
1000000000000000000
>>> to_int_if_drip_units("a string")
'a string'

previous

cfx_utils.types

next

Base32Address