# linearmoney
Full multi-currency support for python.
---
Quickstart Tutorial: https://grammacc.github.io/linearmoney/quickstart.html
Full Documentation: https://grammacc.github.io/linearmoney
License: [MIT](LICENSE)
This project uses [semantic versioning](https://semver.org). However, this
is a pre-release piece of software, so until the first stable release, minor versions
may contain breaking changes. Version 1.0.0 will mark the first stable release, at
which point the regular rules of semver will apply and backwards-incompatible changes
will only be introduced in major versions.
## Description
linearmoney was created to make calculations and formatting with multiple currencies
in modern international applications easier and more reliable.
Key Features:
- Full support for arithmetic with monetary amounts in different currencies.
- Full support for non-destructive currency conversion.
- Full support for fractional currency rounding and fixed-point rounding.
- Full support for currency formatting and localization.
- No dependencies other than Python itself.
- Completely thread-safe.
- 100% Test and API Documentation coverage.
- Database/ORM integrations.
The linearmoney library takes a non-traditional approach to financial applications
by using linear algebra internally to ensure the correctness of monetary calculations
involving multiple currencies without passing this burden onto the programmer.
Understanding of linear algebra is not needed to use and understand the linearmoney
library, but an understanding of basic arithmetic with vectors is helpful for
understanding how the library works under the hood.
For a technical explanation of the motivation and philosophy behind linearmoney
as well as the complete pure-math model that defines the behaviors of the library, see
the [Linear Money Model](https://grammacc.github.io/linearmoney/linear_money_model.html) article.
linearmoney uses the amazing [Unicode CLDR-JSON](https://github.com/unicode-org/cldr-json)
data to provide data-driven interfaces for currency rounding, formatting, and localization.
## Installation
linearmoney requires Python >= 3.10
From PyPi:
```bash
pip install linearmoney
```
From source:
```bash
git clone https://github.com/GrammAcc/linearmoney
cd linearmoney
python -m build .
```
Then to install (virtual environment recommended):
```bash
pip install path/to/cloned/repo
```
## Basic Usage
```pycon
>>> import linearmoney as lm
>>> fo = lm.vector.forex({"base": "usd", "rates": {"jpy": 100}}) # 1 USD -> 100 JPY
>>> sp = lm.vector.space(fo)
>>> cart = []
>>> local_milk_price = lm.vector.asset(4.32, "usd", sp)
>>> cart.append(local_milk_price)
>>> foreign_eggs_price = lm.vector.asset(545, "jpy", sp)
>>> cart.append(foreign_eggs_price)
>>> sales_tax = 0.095
>>> subtotal = sum(cart)
>>> total = subtotal + (subtotal * sales_tax)
>>> total_usd = lm.vector.evaluate(total, "usd", fo)
>>> total_jpy = lm.vector.evaluate(total, "jpy", fo)
>>> usd = lm.data.currency("usd")
>>> jpy = lm.data.currency("jpy")
>>> rounded_total_usd = lm.scalar.roundas(total_usd, usd)
>>> rounded_total_jpy = lm.scalar.roundas(total_jpy, jpy)
>>> en_US = lm.data.locale("en", "us")
>>> localized_total_usd = lm.scalar.l10n(rounded_total_usd, usd, en_US)
>>> localized_total_jpy = lm.scalar.l10n(rounded_total_jpy, jpy, en_US)
>>> print(localized_total_usd)
$10.70
>>> print(localized_total_jpy)
¥1,070
```
linearymoney uses a functional/procedural style where all objects are immutable, so
the code can become verbose compared to more idiomatic Python, but this also makes
the code more explicit and easier to test.
See the [Recipes](https://grammacc.github.io/linearmoney/recipes.html)
section of the user guide for
some examples of how to mitigate the verbosity of the library and other helpful patterns.
## Optional Extensions
The `linearmoney.ext` sub-package provides optional integrations with other libraries/tools.
Most tools shouldn't need any kind of adapter layer for you to use linearmoney with
them since you would normally evaluate a money vector whenever you need to do something
with its value outside of linearmoney's functions or math between vectors. The exceptions
to this are ORMs and similar tools that need some kind of serialization step to be
performed.
[SQLAlchemy](https://grammacc.github.io/linearmoney/api_reference/linearmoney/ext/sqlalchemy.html)
integrations are implemented, and Django ORM is planned.
If there is a tool that you want better integration with or simply some kind of
extra functionality that requires additional dependencies, please
[open an issue](https://github.com/GrammAcc/linearmoney/issues/new/choose) and
we will evaluate if it is within the scope of the project to support as an extension.
## Contributing
Contributions are greatly appreciated!
See the [contributing guidelines](/CONTRIBUTING.md) to get started.
## Roadmap
Version 1.0.0:
- [ ] Redesign locale/formatting data structure
- [#15](https://github.com/GrammAcc/linearmoney/issues/15)
- [ ] Redesign caching system
- [ ] Higher-order serialization interface
- [ ] Serialization/deserialization of forex vectors
- [ ] Recipes to add
- [ ] Use-cases without vectors
- [x] Refactor CLDR data processing script
- [#11](https://github.com/GrammAcc/linearmoney/issues/11)
- [x] Add contributing guidelines and setup CI
- [x] Contributing guidelines
- [x] CI workflow
Raw data
{
"_id": null,
"home_page": null,
"name": "linearmoney",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "GrammAcc <grammaticallyacceptable@grammacc.dev>",
"keywords": "currency, fintech, forex, framework, money",
"author": null,
"author_email": "GrammAcc <grammaticallyacceptable@grammacc.dev>",
"download_url": "https://files.pythonhosted.org/packages/e6/1c/94cd5cfeee97f8d6c292f47a0b3f489add791eee413c930093ebe9dd1321/linearmoney-0.2.1.tar.gz",
"platform": null,
"description": "# linearmoney\n\nFull multi-currency support for python.\n\n---\n\nQuickstart Tutorial: https://grammacc.github.io/linearmoney/quickstart.html\n\nFull Documentation: https://grammacc.github.io/linearmoney\n\nLicense: [MIT](LICENSE)\n\nThis project uses [semantic versioning](https://semver.org). However, this\nis a pre-release piece of software, so until the first stable release, minor versions\nmay contain breaking changes. Version 1.0.0 will mark the first stable release, at\nwhich point the regular rules of semver will apply and backwards-incompatible changes\nwill only be introduced in major versions.\n\n## Description\n\nlinearmoney was created to make calculations and formatting with multiple currencies\nin modern international applications easier and more reliable.\n\nKey Features:\n\n- Full support for arithmetic with monetary amounts in different currencies.\n- Full support for non-destructive currency conversion.\n- Full support for fractional currency rounding and fixed-point rounding.\n- Full support for currency formatting and localization.\n- No dependencies other than Python itself.\n- Completely thread-safe.\n- 100% Test and API Documentation coverage.\n- Database/ORM integrations.\n\nThe linearmoney library takes a non-traditional approach to financial applications\nby using linear algebra internally to ensure the correctness of monetary calculations\ninvolving multiple currencies without passing this burden onto the programmer.\nUnderstanding of linear algebra is not needed to use and understand the linearmoney\nlibrary, but an understanding of basic arithmetic with vectors is helpful for\nunderstanding how the library works under the hood.\n\nFor a technical explanation of the motivation and philosophy behind linearmoney\nas well as the complete pure-math model that defines the behaviors of the library, see\nthe [Linear Money Model](https://grammacc.github.io/linearmoney/linear_money_model.html) article.\n\nlinearmoney uses the amazing [Unicode CLDR-JSON](https://github.com/unicode-org/cldr-json)\ndata to provide data-driven interfaces for currency rounding, formatting, and localization.\n\n## Installation\n\nlinearmoney requires Python >= 3.10\n\nFrom PyPi:\n\n```bash\npip install linearmoney\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/GrammAcc/linearmoney\ncd linearmoney\npython -m build .\n```\n\nThen to install (virtual environment recommended):\n\n```bash\npip install path/to/cloned/repo\n```\n\n## Basic Usage\n\n```pycon\n>>> import linearmoney as lm\n>>> fo = lm.vector.forex({\"base\": \"usd\", \"rates\": {\"jpy\": 100}}) # 1 USD -> 100 JPY\n>>> sp = lm.vector.space(fo)\n>>> cart = []\n>>> local_milk_price = lm.vector.asset(4.32, \"usd\", sp)\n>>> cart.append(local_milk_price)\n>>> foreign_eggs_price = lm.vector.asset(545, \"jpy\", sp)\n>>> cart.append(foreign_eggs_price)\n>>> sales_tax = 0.095\n>>> subtotal = sum(cart)\n>>> total = subtotal + (subtotal * sales_tax)\n>>> total_usd = lm.vector.evaluate(total, \"usd\", fo)\n>>> total_jpy = lm.vector.evaluate(total, \"jpy\", fo)\n>>> usd = lm.data.currency(\"usd\")\n>>> jpy = lm.data.currency(\"jpy\")\n>>> rounded_total_usd = lm.scalar.roundas(total_usd, usd)\n>>> rounded_total_jpy = lm.scalar.roundas(total_jpy, jpy)\n>>> en_US = lm.data.locale(\"en\", \"us\")\n>>> localized_total_usd = lm.scalar.l10n(rounded_total_usd, usd, en_US)\n>>> localized_total_jpy = lm.scalar.l10n(rounded_total_jpy, jpy, en_US)\n>>> print(localized_total_usd)\n$10.70\n>>> print(localized_total_jpy)\n\u00a51,070\n\n```\n\nlinearymoney uses a functional/procedural style where all objects are immutable, so\nthe code can become verbose compared to more idiomatic Python, but this also makes\nthe code more explicit and easier to test.\n\nSee the [Recipes](https://grammacc.github.io/linearmoney/recipes.html)\nsection of the user guide for\nsome examples of how to mitigate the verbosity of the library and other helpful patterns.\n\n## Optional Extensions\n\nThe `linearmoney.ext` sub-package provides optional integrations with other libraries/tools.\n\nMost tools shouldn't need any kind of adapter layer for you to use linearmoney with\nthem since you would normally evaluate a money vector whenever you need to do something\nwith its value outside of linearmoney's functions or math between vectors. The exceptions\nto this are ORMs and similar tools that need some kind of serialization step to be\nperformed.\n\n[SQLAlchemy](https://grammacc.github.io/linearmoney/api_reference/linearmoney/ext/sqlalchemy.html)\nintegrations are implemented, and Django ORM is planned.\n\nIf there is a tool that you want better integration with or simply some kind of\nextra functionality that requires additional dependencies, please\n[open an issue](https://github.com/GrammAcc/linearmoney/issues/new/choose) and\nwe will evaluate if it is within the scope of the project to support as an extension.\n\n## Contributing\n\nContributions are greatly appreciated!\n\nSee the [contributing guidelines](/CONTRIBUTING.md) to get started.\n\n## Roadmap\n\nVersion 1.0.0:\n- [ ] Redesign locale/formatting data structure\n - [#15](https://github.com/GrammAcc/linearmoney/issues/15)\n- [ ] Redesign caching system\n- [ ] Higher-order serialization interface\n - [ ] Serialization/deserialization of forex vectors\n- [ ] Recipes to add\n - [ ] Use-cases without vectors\n- [x] Refactor CLDR data processing script\n - [#11](https://github.com/GrammAcc/linearmoney/issues/11)\n- [x] Add contributing guidelines and setup CI\n - [x] Contributing guidelines\n - [x] CI workflow\n",
"bugtrack_url": null,
"license": null,
"summary": "Full multi-currency support for python.",
"version": "0.2.1",
"project_urls": {
"bug_tracker": "https://github.com/GrammAcc/linearmoney/issues",
"documentation": "https://grammacc.github.io/linearmoney",
"homepage": "https://github.com/GrammAcc/linearmoney",
"repository": "https://github.com/GrammAcc/linearmoney"
},
"split_keywords": [
"currency",
" fintech",
" forex",
" framework",
" money"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a2a08c5f3154a38059ed36cb48e8cd691201596102faa586ff681513f374cd51",
"md5": "faf1cda20b64796788af6021413debaa",
"sha256": "6f7d9cfa6986520a6ee8eab07b5dffd72f3ea360014c56dec45eff52642dba1f"
},
"downloads": -1,
"filename": "linearmoney-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "faf1cda20b64796788af6021413debaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 87468,
"upload_time": "2024-07-07T16:25:37",
"upload_time_iso_8601": "2024-07-07T16:25:37.721675Z",
"url": "https://files.pythonhosted.org/packages/a2/a0/8c5f3154a38059ed36cb48e8cd691201596102faa586ff681513f374cd51/linearmoney-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e61c94cd5cfeee97f8d6c292f47a0b3f489add791eee413c930093ebe9dd1321",
"md5": "237ec3430a39bbe6f9e9665f8b25a7ee",
"sha256": "807e6fecbe397e02a9c8280ffdd092c060af9b5d40814ec8df680aea424c6624"
},
"downloads": -1,
"filename": "linearmoney-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "237ec3430a39bbe6f9e9665f8b25a7ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 77748,
"upload_time": "2024-07-07T16:25:39",
"upload_time_iso_8601": "2024-07-07T16:25:39.645165Z",
"url": "https://files.pythonhosted.org/packages/e6/1c/94cd5cfeee97f8d6c292f47a0b3f489add791eee413c930093ebe9dd1321/linearmoney-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-07 16:25:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GrammAcc",
"github_project": "linearmoney",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "linearmoney"
}
JSON
