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)

class cfx_utils.token_unit.Drip(value: int | Decimal | float | AbstractTokenUnit[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 Drip

_decimals: typing.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'>,
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.Dict\`\\ \\\[\:py\:class\:\`str\`\, \:py\:class\:\`typing.Type\`\\ \\\[\:py\:class\:\`cfx\_utils.token\_unit.AbstractTokenUnit\`\\ \\\[\:py\:class\:\`typing.Self\`\]\]\]`

‘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
:rtype: :sphinx_autodoc_typehints_type:`\:py\:obj\:\`None\``

>>> uCFX(1).to_base_unit()
1000000000000 Drip

to(target_unit: str | Type[cfx_utils.token_unit.AnyTokenUnit]) → cfx_utils.token_unit.AnyTokenUnit | cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit]

Return a new TokenUnit object in target_unit

Parameters:

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

Return type:

typing.TypeVar(AnyTokenUnit, bound= AbstractTokenUnit) | cfx_utils.token_unit.AbstractTokenUnit[typing.TypeVar(BaseTokenUnit, bound= AbstractBaseTokenUnit)]

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() → cfx_utils.token_unit.BaseTokenUnit

Return a new token unit object in _base_unit

Examples:

>>> from cfx_utils import CFX
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.TypeVar\`\\ \\\(\`\`BaseTokenUnit\`\`\, bound\= AbstractBaseTokenUnit\)`

>>> CFX(1).to_base_unit()
1000000000000000000 Drip

property value: int

class cfx_utils.token_unit.CFX(value: int | decimal.Decimal | str | float | cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit])

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 Drip

_decimals: typing.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: str | Type[cfx_utils.token_unit.AnyTokenUnit]) → cfx_utils.token_unit.AnyTokenUnit | cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit]

Return a new TokenUnit object in target_unit

Parameters:

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

Return type:

typing.TypeVar(AnyTokenUnit, bound= AbstractTokenUnit) | cfx_utils.token_unit.AbstractTokenUnit[typing.TypeVar(BaseTokenUnit, bound= AbstractBaseTokenUnit)]

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() → cfx_utils.token_unit.BaseTokenUnit

Return a new token unit object in _base_unit

Examples:

>>> from cfx_utils import CFX
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.TypeVar\`\\ \\\(\`\`BaseTokenUnit\`\`\, bound\= AbstractBaseTokenUnit\)`

>>> CFX(1).to_base_unit()
1000000000000000000 Drip

property value: Decimal

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: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | int | decimal.Decimal | float)

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: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | int | decimal.Decimal | float)

to(target_unit: str | Type[cfx_utils.token_unit.AnyTokenUnit]) → cfx_utils.token_unit.AnyTokenUnit | cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit]

Return a new TokenUnit object in target_unit

Parameters:

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

Return type:

typing.TypeVar(AnyTokenUnit, bound= AbstractTokenUnit) | cfx_utils.token_unit.AbstractTokenUnit[typing.TypeVar(BaseTokenUnit, bound= AbstractBaseTokenUnit)]

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() → cfx_utils.token_unit.BaseTokenUnit

Return a new token unit object in _base_unit

Examples:

>>> from cfx_utils import CFX
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.TypeVar\`\\ \\\(\`\`BaseTokenUnit\`\`\, bound\= AbstractBaseTokenUnit\)`

>>> CFX(1).to_base_unit()
1000000000000000000 Drip

__eq__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | Literal[0]) → bool

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
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`bool\``

>>> CFX(1) == Drip(10**18)
True

__lt__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | Literal[0]) → bool

Return self<value.

Return type:

bool

__le__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | Literal[0]) → bool

Return self<=value.

Return type:

bool

__gt__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | Literal[0]) → bool

Return self>value.

Return type:

bool

__ge__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | Literal[0]) → bool

Return self>=value.

Return type:

bool

__str__()

Return str(self).

__repr__()

Return repr(self).

__add__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit]) → cfx_utils.token_unit.BaseTokenUnit | typing_extensions.Self

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
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.TypeVar\`\\ \\\(\`\`BaseTokenUnit\`\`\, bound\= AbstractBaseTokenUnit\) \| \:py\:class\:\`typing.Self\``

>>> GDrip(1) + CFX(1)
1000000001000000000 Drip

__sub__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit]) → cfx_utils.token_unit.BaseTokenUnit | typing_extensions.Self

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
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.TypeVar\`\\ \\\(\`\`BaseTokenUnit\`\`\, bound\= AbstractBaseTokenUnit\) \| \:py\:class\:\`typing.Self\``

>>> GDrip(1) - CFX(1) # will raise a warning
-999999999000000000 Drip

__mul__(other: int | decimal.Decimal | float) → typing_extensions.Self

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):
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.Self\``

… cfx_utils.exceptions.InvalidTokenOperation: Not able to execute operation __mul__ on (1 Drip, 0.5) due to invalid argument type

__truediv__(other: cfx_utils.token_unit.AbstractTokenUnit[cfx_utils.token_unit.BaseTokenUnit] | int | decimal.Decimal | float) → typing_extensions.Self | decimal.Decimal

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')
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`typing.Self\` \| \:py\:class\:\`decimal.Decimal\``

>>> Drip(2) / 2
1 Drip

__hash__()

Return hash(self).

token_unit.to_int_if_drip_units() → int | cfx_utils.token_unit.T

Return type:

int | typing.TypeVar(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'