Basic Usage

Styling

You might want to set your desired attribute unit and unit style flavor first or just keep the preset defaults. See all supported unit styles.

>>> import justunits
>>> from justunits import AttributeUnitSeparators, UnitStyle
>>> justunits.set_default_attribute_unit_separator(AttributeUnitSeparators.WHITESPACE_BOXED)
>>> justunits.set_default_unit_style(UnitStyle.FINE_SLASHED_SUPERSCRIPT)

Reformatting

Attribute/value-unit pairs come in many different, justifiable forms. Either they are demanded by preexisting file format definitions or depend on the context of information transfer. Transferring different formats depicted in figure 1.

>>> import justunits
>>> from justunits import AttributeUnitSeparators, UnitStyle, UnitDividingStyle
>>> justunits.reformat_unit("pressure#kg*m^-1*s^-2")
'pressure [kg/(m⋅s²)]'

Change just the separator in between attribute and unit.

>>> justunits.reformat_unit(
...     "pressure#kg*m^-1*s^-2",
...     target_format=AttributeUnitSeparators.WHITESPACE_IN
... )
'pressure in kg/(m⋅s²)'

Or make custom combinations. Missing definitions will be replaced by defaults.

>>> boxed_fine_powered = (
...     AttributeUnitSeparators.WHITESPACE_BOXED | UnitDividingStyle.BY_POWER
... )
>>> justunits.reformat_unit(
...     "pressure#kg*m^-1*s^-2",
...     target_format=boxed_fine_powered
... )
'pressure [kg⋅m⁻¹⋅s⁻²]'

Splitting

You may come across one of these exemplary formats and want to split attributes/values from units from further processing.

Header of a csv file:

time[s],energy[J],torque[Nm]
0.0,0.0,0.0
...

Attributes with units in text files:

...
height_mm = 1.0
width_mm = 2.0
...

Or values with units in text files:

...
height = 1.0 mm
width = 2.0 mm
...

split_unit_text

Splitting attributes/values from units preserving text. The function justunits.split_unit_text() provides a splitting whenever a unit detection is not desired.

>>> justunits.split_unit_text("heat capacity[kg/(s^−2*K^-1)*m^2]")
('heat capacity', 'kg/(s^−2*K^-1)*m^2')

>>> justunits.split_unit_text("1.23 apples")
('1.23', 'apples')

split_unit

justunits.split_unit() provides the main feature of detecting units in the process of splitting.

>>> attribute_name, any_units = justunits.split_unit("pressure#kg*m^-1*s^-2")
>>> attribute_name
'pressure'

The unit text is converted into an iterable DerivedUnit-Object containing all detected
(and unknown units).

>>> any_units
(AUnit(kg 'kilogram' mass, 1e+03g), AUnit(m 'meter' length; power=-1), AUnit(s 'second' time; power=-2))

>>> [str(unit) for unit in any_units]
['kg', 'm^-1.0', 's^-2.0']

split_unit converting attribute/value

It is also possible to convert the split values by converting them with a Callable[[str], Any]`.

>>> justunits.split_unit("1.23 apples", converter=float)
(1.23, (UnknownUnit('apples'),))

Be aware that using a conversion function any exception will not be caught.

>>> justunits.split_unit("1.23 apples", converter=int)
Traceback (most recent call last):
...
ValueError: invalid literal for int() with base 10: '1.23'

This is intentional as the purpose of the converters result depends on your choice. Either catch a related exception or take different solutions.

>>> justunits.split_unit("1.23 apples", converter=lambda x: int(float(x)))
(1, (UnknownUnit('apples'),))

Joining

justunits.join() The counterpart of splitting attributes/values-unit pairs joins

>>> pressure = justunits.from_string("kg/(m*s^2)")
>>> justunits.join_unit("pressure", pressure)
'pressure [kg/(m⋅s²)]'

>>> from justunits import AttributeUnitSeparators
>>> justunits.join_unit(
...     "pressure", pressure, target_format=AttributeUnitSeparators.WHITESPACE_IN
... )
'pressure in kg/(m⋅s²)'