def_unit

astropy.units.def_unit(s, represents=None, doc=None, format=None, prefixes=False, exclude_prefixes=(), namespace=None)

Define a new unit.

This function differs from creating units directly with Unit or IrreducibleUnit because it can also automatically generate prefixed units in the given namespace.

Parameters:

spython:str or python:list of python:str

The name of the unit. If a list, the first element is the canonical (short) name, and the rest of the elements are aliases.

representsastropy:unit-like, optional

The unit that this named unit represents. If not provided, a new IrreducibleUnit is created.

docpython:str, optional

A docstring describing the unit.

formatpython:dict, optional

A mapping to format-specific representations of this unit. For example, for the Ohm unit, it might be nice to have it displayed as \Omega by the latex formatter. In that case, format argument should be set to:

{'latex': r'\Omega'}

prefixesbool or python:iterable of UnitPrefix, optional

When True, generate all of the SI prefixed versions of the unit as well. For example, for a given unit m, will generate mm, cm, km, etc. If only a few prefixed versions should be created then an iterable of UnitPrefix instances can be specified instead. Default is False, which means no prefixed versions will be generated.

This function always returns the base unit object, even if multiple scaled versions of the unit were created.

exclude_prefixesCollection of python:str, optional

If any of the SI prefixes need to be excluded, they may be listed here. For example, when defining the prefixes for a, exclude_prefixes should be set to ["P"] so that Pa would still refer to the pascal.

If a bare str is used then the prefixes that will be excluded are the substrings of the str, not just its individual characters.

namespacepython:dict, optional

When provided, inject the unit (and all of its aliases and prefixes), into the given namespace dictionary.

Returns:

unitNamedUnit

The newly-defined unit, or a matching unit that was already defined.

Raises:

ValueError

If represents cannot be parsed as a unit, e.g., because it is a malformed string or a |Quantity| that is not a scalar.