Metadata-Version: 2.4
Name: UnityManager
Version: 0.0.1a1
Summary: Utilities for formatting common units.
Project-URL: Homepage, https://github.com/PlayGames-2020/UnityManager
Project-URL: Repository, https://github.com/PlayGames-2020/UnityManager.git
Project-URL: Documentation, https://github.com/PlayGames-2020/UnityManager/blob/main/README.md
Project-URL: Authors, https://github.com/PlayGames-2020
Author-email: PlayGames-2020 <playgames16.01.2020@gmail.com>
License: MIT License
        
        Copyright (c) 2026 PlayGames-2020
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: bytes,formatting,games,length,mass,money,units,volume
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == 'dev'
Description-Content-Type: text/markdown

# UnityManager

Utilities for formatting common units without runtime dependencies.

> **Status:** alpha (`0.0.1-alpha`). The API is still subject to change.

## Requirements

- Python **3.9 or later**
- No runtime dependencies

## Installation

### GitHub

``` bash
pip install git+https://github.com/PlayGames-2020/UnityManager.git
```

or

``` bash
pip install git+https://github.com/PlayGames-2020/UnityManager.git@master
```

### PyPI

``` bash
pip install UnityManager
```

To install the development dependencies:

```bash
pip install "unitymanager[dev]"
```

## Quick start

```python
from UnityManager import (
    format_bytes,
    format_capacity,
    format_length,
    format_mass,
    format_volume,
)
from games import format_money

print(format_bytes(1024))       # 1.00 KB
print(format_length(1500))      # 1.50 km
print(format_capacity(2.5))     # 2.50 l
print(format_mass(2500))        # 2.50 kg
print(format_volume(1))         # 1.00 m³
print(format_money(1500))       # 1.50 K
```

Each formatter accepts a text mode. The default mode `"s"` displays the unit symbol. Use `"n"` for the unit name, combine modes such as `"ns"`, or add `"upper"`, `"lower"`, `"title"` and `"v"` as needed.

## Games package

The optional game-oriented API is available from the `games` package:

```python
from games import format_money

format_money(999)                  # "999.00"
format_money(1_500)                # "1.50 K"
format_money(2_000_000)            # "2.00 M"
format_money(1_500, "n")            # "1.50 thousand"
format_money(1_500, "ns")           # "1.50 thousand K"
format_money(1_500, "v")            # "1.50 (1500 gold)"
format_money(1_500, "nsupper")      # "1.50 THOUSAND K"
```

### `format_money(value, mode="s")`

Formats a numeric amount in the base game currency, assumed to be gold. Values
are rounded to two decimal places and use the largest applicable suffix:

| Range | Name | Symbol |
| ---: | --- | :--- |
| 1,000 | thousand | `K` |
| 1,000,000 | million | `M` |
| 1,000,000,000 | billion | `B` |
| 1,000,000,000,000 | trillion | `T` |
| 1,000,000,000,000,000 | quadrillion | `Q` |

Supported mode components:

- `s`: append the compact symbol.
- `n`: append the full unit name.
- `d`: append the unit description (reserved for future descriptions).
- `v`: append the original value as gold.
- `upper`, `lower`, `title`: change the case of the appended text.

Modes can be combined, for example `"nsupper"`. Non-numeric values are returned
as text instead of raising an exception.

The formatter is intentionally currency-neutral in its arithmetic: it only
compacts the amount. The displayed base-currency label is currently `gold` and
can be extended in a future API version if games need coins, gems, credits or
other currencies.

## UnityManager API

All public formatters return a string rounded to two decimal places. Numeric
inputs use the base unit described below; non-numeric inputs are returned using
`str(value)`.

### `format_bytes(value, mode="s")`

Formats binary quantities using powers of 1024. The base input is bytes and the
available symbols include `B`, `KB`, `MB`, `GB`, `TB`, `PB`, `EB` and `ZB`.
The mode `"byte"` adds the original value in bytes, while `"bit"` adds its
corresponding bit value.

```python
format_bytes(1024)             # "1.00 KB"
format_bytes(1024, "n")        # "1.00 kilobyte"
format_bytes(2048, "sbyte")   # "2.00 KB (2048 bytes)"
```

### `format_length(value, mode="s")`

Formats a value expressed in metres using metric units from millimetres to
kilometres.

```python
format_length(1_500)            # "1.50 km"
format_length(1, "n")           # "1.00 metre"
format_length(1, "nv")          # "1.00 metre (1.0 m)"
```

### `format_capacity(value, mode="s")`

Formats a value expressed in litres, from millilitres to kilolitres.

```python
format_capacity(2.5)            # "2.50 l"
format_capacity(1_000, "n")     # "1.00 kilolitre"
```

### `format_mass(value, mode="s")`

Formats a value expressed in grams, from milligrams to kilograms.

```python
format_mass(2_500)              # "2.50 kg"
format_mass(1, "n")             # "1.00 gram"
```

### `format_volume(value, mode="s")`

Formats a value expressed in cubic metres, from cubic millimetres to cubic
kilometres.

```python
format_volume(1)                # "1.00 m³"
format_volume(0.000001)         # "1.00 cm³"
```

### Text modes

The general formatters support these mode components:

- `s`: append the unit symbol (the default).
- `n`: append the full unit name.
- `d`: append the unit description, when available.
- `v`: append the original value in the base unit.
- `upper`, `lower`, `title`: change the case of the appended text.

Modes can be combined as a string, for example `"nsupper"`.

## Supported formatters

- `format_bytes`: binary byte units (`B`, `KB`, `MB`, and so on).
- `format_length`: metric lengths from millimetres to kilometres.
- `format_capacity`: metric capacities from millilitres to kilolitres.
- `format_mass`: metric masses from milligrams to kilograms.
- `format_volume`: cubic metric units from cubic millimetres to cubic kilometres.
- `games.format_money`: compact game currency values (`K`, `M`, `B`, `T`, `Q`).

## Development and testing

```bash
git clone https://github.com/PlayGames-2020/UnityManager.git
cd UnityManager
pip install -e ".[dev]"
python -m pytest
```

## License

Distributed under the [MIT License](LICENSE).

## Links

- [Repository](https://github.com/PlayGames-2020/UnityManager)
- [Documentation](https://github.com/PlayGames-2020/UnityManager/blob/main/README.md)
