This release is a pre-release and may not be stable for production use.
monetils
Installation
pip install monetils
Usage
monetils provides BTC and USD classes for representing monetary amounts exactly,
without floating-point rounding artifacts.
Construction and formatting
from monetils import BTC, USD
usd = USD(1234.5)
print(str(usd)) # "1234.50"
btc = BTC(1)
print(str(btc)) # "1.00000000"
# Construct from a non-default unit
half_btc = BTC.sat(50_000_000)
print(str(half_btc)) # "0.50000000"
nineteen_ninety_nine = USD.cent(1999)
print(str(nineteen_ninety_nine)) # "19.99"
Arithmetic
from monetils import BTC, USD, CurrencyMismatchError
total = USD(10.50) + USD(5.25) # USD(15.75)
# A plain number used with +/- is treated as an amount in the currency's base unit
one_more_btc = BTC(1) + 1 # BTC(2)
# A plain number used with */÷ is a dimensionless scaling factor
doubled = BTC(1) * 2 # BTC(2)
# Mixing currencies raises CurrencyMismatchError instead of a silent wrong result
try:
BTC(1) + USD(1)
except CurrencyMismatchError:
print("rejected as expected")
Unit conversion
from monetils import BTC
one_btc = BTC(1)
one_btc.to("sat") # Decimal("100000000")
one_btc.sats # 100000000
msat_value = one_btc.to("msat")
BTC.msat(msat_value) == one_btc # True — lossless round trip
Pydantic support
BTC and USD work directly as Pydantic v2 model fields — no
wrapper type needed. This requires pydantic>=2.0,<3 to be installed in your own project;
monetils does not depend on it (it stays a zero-runtime-dependency library).
from pydantic import BaseModel
from monetils import BTC, USD
class Invoice(BaseModel):
price: USD
fee: BTC | None = None
# Accepts a plain number/string, or an existing BTC/USD instance
invoice = Invoice(price=19.99, fee="0.5")
invoice.model_dump() # {"price": USD(19.99), "fee": BTC(0.5)} — instances, unchanged
invoice.model_dump_json() # '{"price":"19.99","fee":"0.50000000"}' — the same str() convention
Invoice.model_json_schema() # describes price/fee as JSON string properties
# Invalid input (wrong currency, unparseable value) raises a standard pydantic.ValidationError
License
This project is licensed under the terms of the MIT license.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file monetils-0.2.0b2.tar.gz.
File metadata
- Download URL: monetils-0.2.0b2.tar.gz
- Upload date:
- Size: 218.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1272554fa07e79ec70b0702bbbda218d84bd5dea697ed5be5635f5c63af9ca35
|
|
| MD5 |
0e83c20c842d677123e44d36217a55cb
|
|
| BLAKE2b-256 |
0fe663ffb42fdbfb10f7a2f1dc3996291d87d98b65890d056d4833dd2a8617fa
|
Provenance
The following attestation bundles were made for monetils-0.2.0b2.tar.gz:
Publisher:
publish-pypi.yml on seba3c/monetils
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
monetils-0.2.0b2.tar.gz -
Subject digest:
1272554fa07e79ec70b0702bbbda218d84bd5dea697ed5be5635f5c63af9ca35 - Sigstore transparency entry: 2739634250
- Sigstore integration time:
-
Permalink:
seba3c/monetils@5db4f4b64e838cf2d994e8e08b7c769de225e2ed -
Branch / Tag:
refs/heads/main - Owner: https://github.com/seba3c
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@5db4f4b64e838cf2d994e8e08b7c769de225e2ed -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file monetils-0.2.0b2-py3-none-any.whl.
File metadata
- Download URL: monetils-0.2.0b2-py3-none-any.whl
- Upload date:
- Size: 8.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c4c3e622a26eb82c2e17cc4ae8ce141e8867fcbd24da7403b5597139c0006814
|
|
| MD5 |
71822fdb646e517c0e77ee0e2b82b999
|
|
| BLAKE2b-256 |
6298dd4e36750041b5f83ce4e7cc231eb2d36db9b5d591c98a39d69a20e1e282
|
Provenance
The following attestation bundles were made for monetils-0.2.0b2-py3-none-any.whl:
Publisher:
publish-pypi.yml on seba3c/monetils
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
monetils-0.2.0b2-py3-none-any.whl -
Subject digest:
c4c3e622a26eb82c2e17cc4ae8ce141e8867fcbd24da7403b5597139c0006814 - Sigstore transparency entry: 2739634296
- Sigstore integration time:
-
Permalink:
seba3c/monetils@5db4f4b64e838cf2d994e8e08b7c769de225e2ed -
Branch / Tag:
refs/heads/main - Owner: https://github.com/seba3c
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@5db4f4b64e838cf2d994e8e08b7c769de225e2ed -
Trigger Event:
workflow_dispatch
-
Statement type:
