pyxx.units.UnitConverter#

class pyxx.units.UnitConverter(unit_system: UnitSystem)#

Bases: Dict[str, UnitConverterEntry]

Data structure for storing units and performing unit conversions

This class is intended to store a collection of units, and provide methods to convert quantities between the stored units or any valid arithmetic combination of stored units. There are no limit on the number or types of units that can be stored; however, all units must belong to the same system of units.

The UnitConverter class inherits from Python’s built-in dict object, so any of the methods that are defined for a dict should also work for UnitConverter objects.

Examples

For examples, refer to the Units 1: Basics page.

Methods

`__init__`(unit_system)	Creates a new unit converter
`add_alias`(key, aliases[, overwrite])	Add one or more aliases for a unit
`add_unit`(key, unit[, tags, name, ...])	Adds a unit to the unit converter
`convert`(quantity, from_unit, to_unit)	Converts a quantity from one unit in the `UnitConverter` to another
`get_aliases`(unit)	Retrieves a list of aliases for a particular unit in the unit converter
`is_convertible`(unit1, unit2, *args)	Checks whether units can be converted between each other
`is_defined_unit`(unit)	Checks whether a simple or complex unit is composed exclusively of units which have been defined in the unit converter
`is_simplified_unit`(unit)	Evaluates whether a unit is a fully-simplified unit
`list_tags`()	Returns a list of all tags currently used in the `UnitConverter` instance
`search`(search_term[, search_fields, ...])	Searches the `UnitConverter` contents for a given term
`str_to_unit`(unit)	Converts a string to a `Unit` object using units defined in the `UnitConverter`

Inherited Methods

`clear`()
`copy`()
`fromkeys`([value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`items`()
`keys`()
`pop`(k[,d])	If the key is not found, return the default if given; otherwise, raise a KeyError.
`popitem`()	Remove and return a (key, value) pair as a 2-tuple.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`update`([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`()

Attributes

unit_system

The system of units used by all units in the unit converter

__init__(unit_system: UnitSystem)#

Creates a new unit converter

Creates an new UnitConverter class with no units defined.

Parameters:: unit_system (UnitSystem) – The system of units to which all units in the unit converter must belong

property unit_system: UnitSystem#: The system of units used by all units in the unit converter

Adds a unit to the unit converter

Adds a unit and possibly unit metadata (tags, description) to the unit converter, so that the unit can be used to perform later unit conversions.

Parameters:

key (str) – A short string, such as 'kg', uniquely identifying the unit
unit (Unit) – A Unit object (or subclass) specifying the unit
tags (TypedList or list or tuple or str, optional) – One or more strings containing brief, one-word descriptors to use to group similar units, such as “length” or “speed” (default is None, meaning that no tags are associated with the unit)
name (str, optional) – A name for the unit (default is None)
description (str, optional) – A written description of the unit (default is None)
aliases (str or list or tuple, optional) – Alternate identifiers to add to unit converter (default is None). Refer to the add_alias() method documentation for more detail about unit aliases
overwrite (bool, optional) – Whether to overwrite units if they already exist in the unit converter (default is False)

add_alias(key: str, aliases: str | List[str] | Tuple[str, ...], overwrite: bool = False) → None#

Add one or more aliases for a unit

Adds alternate identifiers (keys) that may be used to identify a unit in simple or compound unit strings. This method is useful for adding units which have multiple equivalent representations, such as “micron” and “μm,” to the unit converter efficiently.

Parameters:

key (str) – The unit identifier of a unit already in the unit converter for which to add an alias
aliases (str or list or tuple) – Alternate identifiers to add to unit converter
overwrite (bool, optional) – Whether to overwrite units if they already exist in the unit converter (default is False)

Warning

Aliased units are added to the UnitConverter by reference. Thus, if one of the aliased units is modified, all the other aliased units will also be updated.

convert(quantity: ndarray | list | tuple | float, from_unit: str, to_unit: str) → ndarray#

Converts a quantity from one unit in the UnitConverter to another

Converts a value or array from one unit to another, where the units can be either units in the unit converter, or compound units composed of units in the unit converter.

Parameters:

quantity (np.ndarray or list or tuple or float) – Value(s) to convert from from_unit to to_unit
from_unit (str) – String specifying the simple or compound unit of quantity
to_unit (str) – String specifying the simple or compound unit to which quantity is to be converted

Returns:

NumPy array with the same shape as quantity containing the value(s) in quantity converted from from_unit to to_unit

Return type:

np.ndarray

get_aliases(unit: str) → List[str]#

Retrieves a list of aliases for a particular unit in the unit converter

This method identifies all keys in the unit converter that are aliases of a particular unit.

Parameters:: unit (str) – The identifier of the unit for which to search for aliases
Returns:: A list of strings containing all identifiers in the unit converter which are aliases of unit
Return type:: list

clear() → None. Remove all items from D.#

copy() → a shallow copy of D#

fromkeys(value=None, /)#: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#: Return the value for key if key is in the dictionary, else default.

is_convertible(unit1: str, unit2: str, *args: str) → bool#

Checks whether units can be converted between each other

Checks whether two or more units are compatible and can be directly converted between each other. Inputs can be strings of simple or compound units. The corresponding units (or component units of compound units) must exist in the UnitConverter before calling this method.

Parameters:

unit1 (str) – Key/identifier of the first unit to check
unit2 (str) – Key/identifier of the second unit to check
*args (str, optional) – Keys/identifiers of any other units to check

Returns:

Whether all units can be converted directly between each other

Return type:

bool

items() → a set-like object providing a view on D's items#

keys() → a set-like object providing a view on D's keys#

pop(k[, d]) → v, remove specified key and return the corresponding value.#: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.#: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values#

is_defined_unit(unit: str) → bool#

Checks whether a simple or complex unit is composed exclusively of units which have been defined in the unit converter

This method verifies that a simple unit or all component units of a compound unit have been defined in the unit converter; if not, unit conversions involving such a unit cannot be performed.

Parameters:: unit (str) – The simple or compound unit to analyze
Returns:: Whether all component unit(s) in unit are defined in the unit converter
Return type:: bool

is_simplified_unit(unit: str) → bool#

Evaluates whether a unit is a fully-simplified unit

Returns whether a unit is NOT a compound unit. Fully-simplified units can be added to the UnitConverter, but compound units cannot. Note that units that are not of type str or which are enclosed in brackets (such as '(m)') are not considered fully-simplified.

Parameters:: unit (str) – The unit to check
Returns:: Whether unit is fully-simplified and can be added to the UnitConverter
Return type:: bool

list_tags() → List[str]#

Returns a list of all tags currently used in the UnitConverter instance

Returns:: List (in alphabetical order) of all tags used by any unit in the unit converter
Return type:: list

Searches the UnitConverter contents for a given term

Once a unit converter has a large number of units, it can be challenging to remember all included units. This method provides a simple way to search the contents of a UnitConverter, either interactively (on the command line) or programmatically (in a script).

Parameters:

search_term (str) – The term to search for. Any units in which search_term is found in the fields specified by search_fields will be returned. Set search_term to '*' or '**' to match any string
search_fields (list or tuple or str, optional) – The fields of each entry in the UnitConverter to search. Valid options are any of ('key', 'name', 'tags', 'description') (default is to search all valid fields)
filter_by_tags (list or tuple or str, optional) – Only units with tags specified by filter_by_tags will be included in the search results. Set to None disable filtering by tags (default is None)
hide_aliases (bool, optional) – Whether to hide unit aliases when outputting search results (default is False). Refer to the add_alias() method documentation for more detail about unit aliases
print_results (bool, optional) – Whether to print search results to the terminal (default is True)
return_results (bool, optional) – Whether to return a list containing search results (default is False)

Returns:

Returns a list of strings containing the UnitConverter keys for any units matching the specified search criteria if return_results is True. Otherwise, no outputs are returned

Return type:

list or None

str_to_unit(unit: str) → Unit#

Converts a string to a Unit object using units defined in the UnitConverter

Parses a string containing a simple or compound unit, converting it to a Unit object. All simple units and all component units in compound units must be defined in the unit converter prior to calling this method.

Parameters:: unit (str) – String containing the simple or compound unit to parse
Returns:: A Unit object representation of the unit specified by unit
Return type:: Unit