| Name | magnitude JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | None |
| Summary | Python library for computing with numbers with units |
| upload_time | 2025-07-28 13:39:04 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
si
conversion
measurement
physics
units
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Magnitude
A Python library for computing with numbers with units.
## About
A magnitude is a number with a unit, like 10 km/h. Units can be any of the SI units, plus a bunch of non-SI, bits, dollars, and any combination of them. They can include the standard SI prefixes. Magnitude can operate with physical quantities, parse their units, and print them. You don't have to worry about unit consistency or conversions; everything is handled transparently. By default output is done in basic SI units, but you can specify any output unit, as long as it can be reduced to the basic units of the physical quantity.
## Installation
```bash
uv add magnitude # recommended
# or with pip
pip install magnitude
```
## Quick Example
```python
from magnitude import mg
# Basic usage
print("10 m/s ** 2 ->", mg(10, 'm/s') ** 2)
# 10 m/s ** 2 -> 100.0000 m2 / s2
# Unit conversions
speed = mg(10, 'm/s', 'km/h')
speed
# 36.0000 km/h
# Dimensional analysis
time_squared = mg(10, 'm') * 2 / (10, 'm/s2')
time_squared
# 2.0000 s2
back_to_time = time_squared ** 0.5
back_to_time
# 1.4142 s
# Natural constants
year = mg(1, "lightyear") / (1, "c")
year.ounit("year")
# 1.0000 year
year.ounit('day')
# 365.2500 day
```
## Features
- Full support for SI units and prefixes
- Automatic unit conversion and dimensional analysis
- Support for derived units (joules, watts, etc.)
- Binary prefixes (Ki, Mi, Gi, etc.)
- Currency units
- Unicode superscript support for unit notation (m², s⁻¹, etc.)
- Extensible - add your own units
- Pure Python, no dependencies
## Basic Units
The basic units understood by magnitude are:
- `$` - dollar
- `A` - ampere
- `b` - bit
- `cd` - candela
- `K` - degrees Kelvin
- `kg` - kilograms
- `m` - meters
- `mol` - amount of substance
- `s` - seconds
## Derived Units
From the basic units, magnitude supports many derived units:
- `Bq` - becquerel
- `C` - coulomb
- `c` - speed of light (m/s)
- `day` - day
- `degC` - degree Celsius
- `dpi` - dots per inch
- `F` - farad
- `ft` - feet ("'" is also acceptable)
- `g` - gram
- `gravity` - acceleration due to gravity (m/s²)
- `Gy` - gray
- `H` - henry
- `h` - hour
- `Hz` - Hertz
- `inch` - inch ('"' is also acceptable)
- `ips` - inches per second
- `J` - joule
- `kat` - katal
- `l` - liter
- `lightyear` - light year
- `lm` - lumen
- `lpi` - lines per inch
- `lux` - lux
- `min` - minute
- `N` - newton
- `ohm` - ohm
- `Pa` - pascal
- `S` - siemens
- `Sv` - sievert
- `T` - tesla
- `V` - volt
- `W` - watt
- `Wb` - weber
- `year` - year
- `B` - byte
Two magnitudes have no units: `rad` (radian - unit of plane angle) and `sr` (steradian - unit of solid angle).
## Scale Prefixes
Any unit can be augmented with these scale prefixes:
### Decimal Prefixes
- `y` - yocto (10⁻²⁴)
- `z` - zepto (10⁻²¹)
- `a` - atto (10⁻¹⁸)
- `f` - femto (10⁻¹⁵)
- `p` - pico (10⁻¹²)
- `n` - nano (10⁻⁹)
- `u` - micro (10⁻⁶)
- `m` - milli (10⁻³)
- `c` - centi (10⁻²)
- `d` - deci (10⁻¹)
- `k` - kilo (10³)
- `M` - mega (10⁶)
- `G` - giga (10⁹)
- `T` - tera (10¹²)
- `P` - peta (10¹⁵)
- `E` - exa (10¹⁸)
- `Z` - zetta (10²¹)
- `Y` - yotta (10²⁴)
### Binary Prefixes
- `Ki` - Kibi (2¹⁰)
- `Mi` - Mebi (2²⁰)
- `Gi` - Gibi (2³⁰)
- `Ti` - Tebi (2⁴⁰)
- `Pi` - Pebi (2⁵⁰)
- `Ei` - Exbi (2⁶⁰)
## Unicode Superscripts
Magnitude supports Unicode superscripts for both input and output of units:
### Input
You can use Unicode superscripts when creating magnitudes:
```python
from magnitude import mg
# These are equivalent
area1 = mg(10, 'm²')
area2 = mg(10, 'm2')
# Works with negative exponents too
frequency = mg(440, 's⁻¹') # Same as mg(440, 's-1') or mg(440, 'Hz')
# And multi-digit exponents
special = mg(1, 'kg¹²') # Same as mg(1, 'kg12')
```
### Output
By default, output uses regular ASCII notation. You can enable Unicode superscripts:
```python
from magnitude import mg, unicode_superscript
m = mg(10, 'm2/s2')
print(m) # 10.0000 m2/s2
# Enable Unicode superscripts
unicode_superscript(True)
print(m) # 10.0000 m²/s²
# Works with all units
print(mg(1, 'kg') / mg(1, 'm3')) # 1.0000 kg / m³
```
### Environment Variable
You can set the default behavior using the `MAGNITUDE_UNICODE_SUPERSCRIPTS` environment variable:
```bash
# Enable Unicode superscripts by default
export MAGNITUDE_UNICODE_SUPERSCRIPTS=1 # or 'true', 'yes', 'on'
# In Python
from magnitude import mg
print(mg(10, 'm2')) # Will print: 10.0000 m²
```
## Defining New Magnitudes
You can define new magnitudes by instantiating the Magnitude class. For example, to define pounds:
```python
from magnitude import Magnitude, mg, new_mag
# A pound is 0.45359237 kilograms
lb = Magnitude(0.45359237, kg=1)
# Register it in the system
new_mag('lb', lb)
# Now you can use it
me = mg(180, 'lb')
print(me.ounit('kg')) # 81.6466 kg
```
## API Reference
### Main Classes and Functions
- `Magnitude` - The main class for numbers with units
- `mg(value, unit, ounit='')` - Construct a Magnitude
- `ensmg(m, unit='')` - Convert something to a Magnitude
- `new_mag(indicator, mag)` - Register a new magnitude unit
- `MagnitudeError` - Exception for magnitude errors
### Output Formatting
- `output_precision(prec)` - Set/get output precision (default: 4)
- `output_units(enabled)` - Enable/disable unit output
- `default_format(fmt)` - Set/get default output format
## Documentation
Full documentation is available at: https://juanreyero.com/open/magnitude/
## References
- [NIST Units](http://physics.nist.gov/cuu/Units/units.html)
- [SI Units on Wikipedia](http://en.wikipedia.org/wiki/SI)
- [GNU Units](http://www.gnu.org/software/units/units.html)
This code was inspired by [Novak's units code](http://www.cs.utexas.edu/users/novak/units.html) and its [associated paper](http://www.cs.utexas.edu/users/novak/units95.html).
## License
Copyright (c) 2006-2024 Juan Reyero (https://juanreyero.com).
Licensed under the MIT License. See LICENSE for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "magnitude",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "SI, conversion, measurement, physics, units",
"author": null,
"author_email": "Juan Reyero <juan@juanreyero.com>",
"download_url": "https://files.pythonhosted.org/packages/9a/68/b0077f365dbe8444495a316058fec5b513c1fd022d80365031a03f7cf11c/magnitude-1.1.1.tar.gz",
"platform": null,
"description": "# Magnitude\n\nA Python library for computing with numbers with units.\n\n## About\n\nA magnitude is a number with a unit, like 10 km/h. Units can be any of the SI units, plus a bunch of non-SI, bits, dollars, and any combination of them. They can include the standard SI prefixes. Magnitude can operate with physical quantities, parse their units, and print them. You don't have to worry about unit consistency or conversions; everything is handled transparently. By default output is done in basic SI units, but you can specify any output unit, as long as it can be reduced to the basic units of the physical quantity.\n\n## Installation\n\n```bash\nuv add magnitude # recommended\n\n# or with pip\n\npip install magnitude\n```\n\n## Quick Example\n\n```python\nfrom magnitude import mg\n\n# Basic usage\nprint(\"10 m/s ** 2 ->\", mg(10, 'm/s') ** 2)\n# 10 m/s ** 2 -> 100.0000 m2 / s2\n\n# Unit conversions\nspeed = mg(10, 'm/s', 'km/h')\nspeed\n# 36.0000 km/h\n\n# Dimensional analysis\ntime_squared = mg(10, 'm') * 2 / (10, 'm/s2')\ntime_squared\n# 2.0000 s2\nback_to_time = time_squared ** 0.5\nback_to_time\n# 1.4142 s\n\n# Natural constants\nyear = mg(1, \"lightyear\") / (1, \"c\")\nyear.ounit(\"year\")\n# 1.0000 year\nyear.ounit('day')\n# 365.2500 day\n```\n\n## Features\n\n- Full support for SI units and prefixes\n- Automatic unit conversion and dimensional analysis\n- Support for derived units (joules, watts, etc.)\n- Binary prefixes (Ki, Mi, Gi, etc.)\n- Currency units\n- Unicode superscript support for unit notation (m\u00b2, s\u207b\u00b9, etc.)\n- Extensible - add your own units\n- Pure Python, no dependencies\n\n## Basic Units\n\nThe basic units understood by magnitude are:\n\n- `$` - dollar\n- `A` - ampere\n- `b` - bit\n- `cd` - candela\n- `K` - degrees Kelvin\n- `kg` - kilograms\n- `m` - meters\n- `mol` - amount of substance\n- `s` - seconds\n\n## Derived Units\n\nFrom the basic units, magnitude supports many derived units:\n\n- `Bq` - becquerel\n- `C` - coulomb\n- `c` - speed of light (m/s)\n- `day` - day\n- `degC` - degree Celsius\n- `dpi` - dots per inch\n- `F` - farad\n- `ft` - feet (\"'\" is also acceptable)\n- `g` - gram\n- `gravity` - acceleration due to gravity (m/s\u00b2)\n- `Gy` - gray\n- `H` - henry\n- `h` - hour\n- `Hz` - Hertz\n- `inch` - inch ('\"' is also acceptable)\n- `ips` - inches per second\n- `J` - joule\n- `kat` - katal\n- `l` - liter\n- `lightyear` - light year\n- `lm` - lumen\n- `lpi` - lines per inch\n- `lux` - lux\n- `min` - minute\n- `N` - newton\n- `ohm` - ohm\n- `Pa` - pascal\n- `S` - siemens\n- `Sv` - sievert\n- `T` - tesla\n- `V` - volt\n- `W` - watt\n- `Wb` - weber\n- `year` - year\n- `B` - byte\n\nTwo magnitudes have no units: `rad` (radian - unit of plane angle) and `sr` (steradian - unit of solid angle).\n\n## Scale Prefixes\n\nAny unit can be augmented with these scale prefixes:\n\n### Decimal Prefixes\n- `y` - yocto (10\u207b\u00b2\u2074)\n- `z` - zepto (10\u207b\u00b2\u00b9)\n- `a` - atto (10\u207b\u00b9\u2078)\n- `f` - femto (10\u207b\u00b9\u2075)\n- `p` - pico (10\u207b\u00b9\u00b2)\n- `n` - nano (10\u207b\u2079)\n- `u` - micro (10\u207b\u2076)\n- `m` - milli (10\u207b\u00b3)\n- `c` - centi (10\u207b\u00b2)\n- `d` - deci (10\u207b\u00b9)\n- `k` - kilo (10\u00b3)\n- `M` - mega (10\u2076)\n- `G` - giga (10\u2079)\n- `T` - tera (10\u00b9\u00b2)\n- `P` - peta (10\u00b9\u2075)\n- `E` - exa (10\u00b9\u2078)\n- `Z` - zetta (10\u00b2\u00b9)\n- `Y` - yotta (10\u00b2\u2074)\n\n### Binary Prefixes\n- `Ki` - Kibi (2\u00b9\u2070)\n- `Mi` - Mebi (2\u00b2\u2070)\n- `Gi` - Gibi (2\u00b3\u2070)\n- `Ti` - Tebi (2\u2074\u2070)\n- `Pi` - Pebi (2\u2075\u2070)\n- `Ei` - Exbi (2\u2076\u2070)\n\n## Unicode Superscripts\n\nMagnitude supports Unicode superscripts for both input and output of units:\n\n### Input\nYou can use Unicode superscripts when creating magnitudes:\n\n```python\nfrom magnitude import mg\n\n# These are equivalent\narea1 = mg(10, 'm\u00b2')\narea2 = mg(10, 'm2')\n\n# Works with negative exponents too\nfrequency = mg(440, 's\u207b\u00b9') # Same as mg(440, 's-1') or mg(440, 'Hz')\n\n# And multi-digit exponents\nspecial = mg(1, 'kg\u00b9\u00b2') # Same as mg(1, 'kg12')\n```\n\n### Output\nBy default, output uses regular ASCII notation. You can enable Unicode superscripts:\n\n```python\nfrom magnitude import mg, unicode_superscript\n\nm = mg(10, 'm2/s2')\nprint(m) # 10.0000 m2/s2\n\n# Enable Unicode superscripts\nunicode_superscript(True)\nprint(m) # 10.0000 m\u00b2/s\u00b2\n\n# Works with all units\nprint(mg(1, 'kg') / mg(1, 'm3')) # 1.0000 kg / m\u00b3\n```\n\n### Environment Variable\nYou can set the default behavior using the `MAGNITUDE_UNICODE_SUPERSCRIPTS` environment variable:\n\n```bash\n# Enable Unicode superscripts by default\nexport MAGNITUDE_UNICODE_SUPERSCRIPTS=1 # or 'true', 'yes', 'on'\n\n# In Python\nfrom magnitude import mg\nprint(mg(10, 'm2')) # Will print: 10.0000 m\u00b2\n```\n\n## Defining New Magnitudes\n\nYou can define new magnitudes by instantiating the Magnitude class. For example, to define pounds:\n\n```python\nfrom magnitude import Magnitude, mg, new_mag\n\n# A pound is 0.45359237 kilograms\nlb = Magnitude(0.45359237, kg=1)\n\n# Register it in the system\nnew_mag('lb', lb)\n\n# Now you can use it\nme = mg(180, 'lb')\nprint(me.ounit('kg')) # 81.6466 kg\n```\n\n## API Reference\n\n### Main Classes and Functions\n\n- `Magnitude` - The main class for numbers with units\n- `mg(value, unit, ounit='')` - Construct a Magnitude\n- `ensmg(m, unit='')` - Convert something to a Magnitude\n- `new_mag(indicator, mag)` - Register a new magnitude unit\n- `MagnitudeError` - Exception for magnitude errors\n\n### Output Formatting\n\n- `output_precision(prec)` - Set/get output precision (default: 4)\n- `output_units(enabled)` - Enable/disable unit output\n- `default_format(fmt)` - Set/get default output format\n\n## Documentation\n\nFull documentation is available at: https://juanreyero.com/open/magnitude/\n\n## References\n\n- [NIST Units](http://physics.nist.gov/cuu/Units/units.html)\n- [SI Units on Wikipedia](http://en.wikipedia.org/wiki/SI)\n- [GNU Units](http://www.gnu.org/software/units/units.html)\n\nThis code was inspired by [Novak's units code](http://www.cs.utexas.edu/users/novak/units.html) and its [associated paper](http://www.cs.utexas.edu/users/novak/units95.html).\n\n## License\n\nCopyright (c) 2006-2024 Juan Reyero (https://juanreyero.com).\n\nLicensed under the MIT License. See LICENSE for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for computing with numbers with units",
"version": "1.1.1",
"project_urls": {
"Documentation": "http://juanreyero.com/open/magnitude/",
"Homepage": "http://juanreyero.com/open/magnitude/",
"Issues": "https://github.com/juanre/magnitude/issues",
"Repository": "https://github.com/juanre/magnitude"
},
"split_keywords": [
"si",
" conversion",
" measurement",
" physics",
" units"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7c998bd0a4771a42d862cf2f2cc2516497927a86f4cfcf0d00a76c8b7a351631",
"md5": "7455d0a4deeae37dd46344aeb37699fc",
"sha256": "82f3f5c58ccfc75134e0708515fde8c145e03b9d5d7d05471f191ec86d905eaa"
},
"downloads": -1,
"filename": "magnitude-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7455d0a4deeae37dd46344aeb37699fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4591,
"upload_time": "2025-07-28T13:39:02",
"upload_time_iso_8601": "2025-07-28T13:39:02.544265Z",
"url": "https://files.pythonhosted.org/packages/7c/99/8bd0a4771a42d862cf2f2cc2516497927a86f4cfcf0d00a76c8b7a351631/magnitude-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9a68b0077f365dbe8444495a316058fec5b513c1fd022d80365031a03f7cf11c",
"md5": "ce685a4ce2be929d5bfa8c310f49d0d4",
"sha256": "c57c190cf5dc208090b55846c24901aa0b2e596b2037019690d46d7938849896"
},
"downloads": -1,
"filename": "magnitude-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ce685a4ce2be929d5bfa8c310f49d0d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 40356,
"upload_time": "2025-07-28T13:39:04",
"upload_time_iso_8601": "2025-07-28T13:39:04.012852Z",
"url": "https://files.pythonhosted.org/packages/9a/68/b0077f365dbe8444495a316058fec5b513c1fd022d80365031a03f7cf11c/magnitude-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 13:39:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "juanre",
"github_project": "magnitude",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "magnitude"
}
