simplebooks 0.1.0__tar.gz

simplebooks-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: 'Bug: '
+labels: bug
+assignees: k98kurz
+
+---
+
+### Describe the bug
+
+A clear and concise description of what the bug is.
+
+### To Reproduce
+
+Steps to reproduce the behavior:
+1. ...
+2. ...
+3. ...
+
+### Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+### Screenshots
+
+If applicable, add screenshots to help explain your problem.
+
+### Platform and Version (please complete the following information)
+
+- Platform/device: [e.g. desktop or specific phone model]
+- OS: [e.g. Ubuntu]
+- Python Version: [e.g. 3.10]
+- Library Version [e.g. 0.1.0]
+
+### Additional context
+
+Add any other context about the problem here.

simplebooks-0.1.0/.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,25 @@
+---
+name: Documentation
+about: Improve the documentation
+title: 'Documentation: '
+labels: documentation
+assignees: k98kurz
+
+---
+
+### Describe the Issue
+
+A clear and concise description of the documentation issue.
+
+### Documentation Files and Sections
+
+- readme.md: "Usage"
+- dox.md: "Classes > Entry"
+
+### Discrepancies from Documentation Encountered
+
+A clear and concise description of what discrepancies you found.
+
+### Additional context
+
+Add any other context about the problem here.

simplebooks-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: 'Feature Request: '
+labels: enhancement
+assignees: k98kurz
+
+---
+
+### Is your feature request related to a problem? Please describe.
+
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+### Describe the solution you'd like
+
+A clear and concise description of what you want to happen.
+
+### Describe alternatives you've considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional context
+
+Add any other context or screenshots about the feature request here.

simplebooks-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*/__pycache__
+*.db
+*/*.db
+dist/
+temp/
+build/
+venv*/
+.env
+.vscode/

simplebooks-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.3
+Name: simplebooks
+Version: 0.1.0
+Summary: Simple double-entry accounting system using sqloquent for data storage.
+Project-URL: Homepage, https://github.com/k98kurz/simplebooks
+Project-URL: Bug Tracker, https://github.com/k98kurz/simplebooks/issues
+Author-email: k98kurz <k98kurz@gmail.com>
+License: Copyright (c) 2024 Jonathan Voss (k98kurz)
+        
+        Permission to use, copy, modify, and/or distribute this software
+        for any personal, non-commercial purpose is hereby granted, provided
+        that the above copyright notice and this permission notice appear in
+        all copies. For other uses, contact the software author.
+        
+        THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+        WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+        WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+        AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+        CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+        OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+        NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+        CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Requires-Dist: sqloquent>=0.5.3
+Provides-Extra: asyncql
+Requires-Dist: sqloquent[asyncql]>=0.5.3; extra == 'asyncql'
+Provides-Extra: docs
+Requires-Dist: autodox>=0.1.16; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# SimpleBooks
+
+SimpleBooks is a simple accounting library that uses sqlite3 to persist data for
+identities, ledgers, accounts, transactions, and entries. Included are tools for
+accomplishing basic bookkeeping tasks. The basic accounting formula is this:
+`Assets = Liabilities + Equity`. Assets are debit-balance; liabilities and
+equity are credit-balance. Every transaction must have entries that have no net
+difference between the amount of credits and the amount of debits.
+
+This is a simplification of [bookchain](https://pypi.org/project/bookchain): all
+cryptographic features have been removed. This may be useful in scenarios when
+cryptographic features cannot be supported.
+
+## Status
+
+All initially planned features have been implemented and tested.
+
+Open issues can be found [here](https://github.com/k98kurz/simplebooks/issues).
+
+The async implementation has an upstream issue from the sqloquent dependency
+that can be tracked [here](https://github.com/k98kurz/sqloquent/issues/16). Once
+that is fixed, the dependency will be updated, and this notice will be removed.
+
+## Overview
+
+This library provides an accounting system using sqloquent for persistence,
+packify for deterministic encoding, and the classic rules of double-entry
+bookkeeping. The `Transaction.prepare` and `Transaction.validate` ensure that
+the accounting rule is followed.
+
+### Class organization
+
+`Currency` represents a currency/unit of account for a `Ledger`. It includes the
+number of subunits to track and optionally the base for conversion to decimal
+(defaults to 10), FX symbol, prefix symbol, and/or postfix symbol to be used with
+the `format` method (e.g. `USD.format(1200)` could result in "12.00 USD",
+"$12.00", or "12.00$", respectively). It also includes `to_decimal` method for
+formatting int amounts into `Decimal`s.
+
+`Identity` represents a legal person or other entity that can sign contracts
+or engage in transactions. It includes the name, details, and optionally public
+key bytes and private key seed bytes.
+
+`Ledger` represents a general ledger for a given `Identity` using a specific
+`Currency`. It includes a name, the `Identity` id, and the `Currency` id.
+
+`Account` represents an account for a given `Ledger`. It includes a name, a type
+(one of the `AccountType` enum options), the `Ledger` id, an optional locking
+script for access control, and optional details.
+
+`AccountType` is an enum representing the valid account types. The options are
+`DEBIT_BALANCE`, `ASSET`, `CONTRA_ASSET`, `CREDIT_BALANCE`, `LIABILITY`,
+`EQUITY`, `CONTRA_LIABILITY`, and `CONTRA_EQUITY`.
+
+`Entry` represents an entry in the general ledger for a given `Account`. It
+includes a type (one of the `EntryType` enum options), an amount, a nonce, the
+`Account` id, and optional details.
+
+`EntryType` is an enum representing the valid entry types. The options are
+CREDIT and DEBIT.
+
+`Transaction` represents a transaction made of `Entry`s. It includes the `Entry`
+ids, `Ledger` ids, a timestamp, and the details. Each `Transaction` must include
+entries that balance the number of credits and debits applied to each ledger
+affected by the transaction. Use `Transaction.prepare` to prepare a transaction
+-- it will raise validation errors if the transaction is not valid -- then call
+`.save()` on the result to persist it to the database. Transactions in the
+database can be validated by using `.validate()`, which will return `True` if it
+is valid and `False` if it is not (it will also raise errors in some situations
+that require more information about the validation failure).
+
+`Customer` and `Vendor` are provided in case they are useful in some way, but no
+relations are set up for them currently. This is likely to change in a future
+release.
+
+- `Identity` has many `Ledger`s
+- `Ledger` belongs to `Identity` and `Currency`, has many `Account`s, and is within `Transaction`s
+- `Account` belongs to `Ledger` and has many `Entry`s
+- `Entry` belongs to `Account` and is within `Transaction`s
+- `Transaction` contains `Ledger`s and `Entry`s
+
+## Installation and Setup
+
+Install with `pip install simplebooks`. If you want to use the async version,
+instead install with `pip install simplebooks[asyncql]`.
+
+Once installed, use the following to setup your project as appropriate:
+
+```python
+import simplebooks
+
+simplebooks.publish_migrations(path_to_migrations_folder)
+simplebooks.automigrate(path_to_migrations_folder, db_file_path)
+simplebooks.set_connection_info(db_file_path)
+```
+
+To use the async version:
+
+```python
+import simplebooks
+import simplebooks.asyncql
+
+simplebooks.publish_migrations(path_to_migrations_folder)
+simplebooks.automigrate(path_to_migrations_folder, db_file_path)
+simplebooks.asyncql.set_connection_info(db_file_path)
+```
+
+## More Resources
+
+Documentation generated by [autodox](https://pypi.org/project/autodox) can be
+found [here](https://github.com/k98kurz/simplebooks/blob/v0.1.0/dox.md). Docs for
+the async version can be found
+[here](https://github.com/k98kurz/simplebooks/blob/v0.1.0/asyncql_dox.md).
+
+Check out the [Pycelium discord server](https://discord.gg/b2QFEJDX69). If you
+experience a problem, please discuss it on the Discord server. All suggestions
+for improvement are also welcome, and the best place for that is also Discord.
+If you experience a bug and do not use Discord, open an issue on Github.
+
+## Tests
+
+There are a total of 7 tests (2 e2e tests and 5 tests for miscellaneous
+tools/features). To run them, clone the repo, set up a virtual environment
+(e.g. `python -m venv venv && source venv/bin/activate`), install the
+dependencies with `pip install -r requirements.txt`, and then run the following:
+`find tests -name test_*.py -print -exec python {} \;`. On Windows, the 3 test
+files will have to be individually run with the following:
+
+```bash
+python tests/test_async_basic_e2e.py
+python tests/test_basic_e2e.py
+python tests/test_misc.py
+```
+
+## Personal, Non-commercial Use License
+
+Copyright (c) 2024 Jonathan Voss (k98kurz)
+
+Permission to use, copy, modify, and/or distribute this software
+for any personal, non-commercial purpose is hereby granted, provided
+that the above copyright notice and this permission notice appear in
+all copies. For other uses, contact the software author.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

simplebooks-0.1.0/asyncql_dox.md

@@ -0,0 +1,327 @@
+# simplebooks.asyncql
+
+## Classes
+
+### `AccountType(Enum)`
+
+Enum of valid Account types: DEBIT_BALANCE, ASSET, CONTRA_ASSET, CREDIT_BALANCE,
+LIABILITY, EQUITY, CONTRA_LIABILITY, CONTRA_EQUITY.
+
+### `EntryType(Enum)`
+
+Enum of valid Entry types: CREDIT and DEBIT.
+
+### `Entry(AsyncSqlModel)`
+
+#### Annotations
+
+- table: str
+- id_column: str
+- columns: tuple[str]
+- id: str
+- name: str
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: str
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- type: str
+- amount: int
+- nonce: bytes
+- account_id: str
+- details: bytes
+- account: AsyncRelatedModel
+- transactions: AsyncRelatedCollection
+
+#### Properties
+
+- type: The EntryType of the Entry.
+- details: A packify.SerializableType stored in the database as a blob.
+- account: The related Account. Setting raises TypeError if the precondition
+check fails.
+- transactions: The related Transactions. Setting raises TypeError if the
+precondition check fails.
+
+#### Methods
+
+##### `__hash__() -> int:`
+
+##### `@staticmethod parse(models: Entry | list[Entry]) -> Entry | list[Entry]:`
+
+##### `@classmethod async insert(data: dict) -> Entry | None:`
+
+Ensure data is encoded before inserting.
+
+##### `@classmethod async insert_many(items: list[dict]) -> int:`
+
+Ensure data is encoded before inserting.
+
+##### `@classmethod query(conditions: dict = None) -> AsyncQueryBuilderProtocol:`
+
+Ensure conditions are encoded properly before querying.
+
+### `Account(AsyncSqlModel)`
+
+#### Annotations
+
+- table: str
+- id_column: str
+- columns: tuple[str]
+- id: str
+- name: str
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: str
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- type: str
+- ledger_id: str
+- parent_id: str
+- code: str | None
+- category: str | None
+- details: bytes | None
+- ledger: AsyncRelatedModel
+- parent: AsyncRelatedModel
+- children: AsyncRelatedCollection
+- entries: AsyncRelatedCollection
+
+#### Properties
+
+- type: The AccountType of the Account.
+- details: A packify.SerializableType stored in the database as a blob.
+- ledger: The related Ledger. Setting raises TypeError if the precondition check
+fails.
+- children: The related Accounts. Setting raises TypeError if the precondition
+check fails.
+- parent: The related Account. Setting raises TypeError if the precondition
+check fails.
+- entries: The related Entrys. Setting raises TypeError if the precondition
+check fails.
+
+#### Methods
+
+##### `@classmethod async insert(data: dict) -> Account | None:`
+
+Ensure data is encoded before inserting.
+
+##### `async balance(include_sub_accounts: bool = True) -> int:`
+
+Tally all entries for this account. Includes the balances of all sub-accounts if
+include_sub_accounts is True.
+
+### `Currency(AsyncSqlModel)`
+
+#### Annotations
+
+- table: <class 'str'>
+- id_column: <class 'str'>
+- columns: tuple[str]
+- id: <class 'str'>
+- name: <class 'str'>
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: <class 'str'>
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- prefix_symbol: str | None
+- postfix_symbol: str | None
+- fx_symbol: str | None
+- unit_divisions: <class 'int'>
+- base: int | None
+- details: str | None
+
+#### Methods
+
+##### `to_decimal(amount: int) -> Decimal:`
+
+Convert the amount into a Decimal representation.
+
+##### `get_units(amount: int) -> tuple[int]:`
+
+Get the full units and subunits. The number of subunit figures will be equal to
+unit_divisions; e.g. if base=10 and unit_divisions=2, get_units(200) will return
+(2, 0, 0); if base=60 and unit_divisions=2, get_units(200) will return (0, 3,
+20).
+
+##### `format(amount: int, /, *, use_fx_symbol: bool = False, use_postfix: bool = False, use_prefix: bool = True, decimal_places: int = 2) -> str:`
+
+Format an amount using the correct number of decimal_places.
+
+### `Customer(AsyncSqlModel)`
+
+#### Annotations
+
+- table: <class 'str'>
+- id_column: <class 'str'>
+- columns: tuple[str]
+- id: <class 'str'>
+- name: <class 'str'>
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: <class 'str'>
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- code: str | None
+- details: str | None
+
+#### Properties
+
+- details: A packify.SerializableType stored in the database as a blob.
+
+### `Ledger(AsyncSqlModel)`
+
+#### Annotations
+
+- table: str
+- id_column: str
+- columns: tuple[str]
+- id: str
+- name: str
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: str
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- identity_id: str
+- currency_id: str
+- owner: AsyncRelatedModel
+- currency: AsyncRelatedModel
+- accounts: AsyncRelatedCollection
+- transactions: AsyncRelatedCollection
+
+#### Properties
+
+- owner: The related Identity. Setting raises TypeError if the precondition
+check fails.
+- currency: The related Currency. Setting raises TypeError if the precondition
+check fails.
+- accounts: The related Accounts. Setting raises TypeError if the precondition
+check fails.
+- transactions: The related Transactions. Setting raises TypeError if the
+precondition check fails.
+
+#### Methods
+
+##### `async balances(reload: bool = False) -> dict[str, tuple[int, AccountType]]:`
+
+Return a dict mapping account ids to their balances. Accounts with sub-accounts
+will not include the sub-account balances; the sub-account balances will be
+returned separately.
+
+##### `setup_basic_accounts() -> list[Account]:`
+
+Creates and returns a list of 3 unsaved Accounts covering the 3 basic
+categories: Asset, Liability, Equity.
+
+### `Identity(AsyncSqlModel)`
+
+#### Annotations
+
+- table: str
+- id_column: str
+- columns: tuple[str]
+- id: str
+- name: str
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: str
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- columns_excluded_from_hash: tuple[str]
+- details: bytes
+- pubkey: bytes | None
+- seed: bytes | None
+- secret_details: bytes | None
+- ledgers: AsyncRelatedCollection
+
+#### Properties
+
+- ledgers: The related Ledgers. Setting raises TypeError if the precondition
+check fails.
+
+#### Methods
+
+##### `public() -> dict:`
+
+Return the public data for cloning the Identity.
+
+### `Transaction(AsyncSqlModel)`
+
+#### Annotations
+
+- table: str
+- id_column: str
+- columns: tuple[str]
+- id: str
+- name: str
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: str
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- entry_ids: str
+- ledger_ids: str
+- timestamp: str
+- details: bytes
+- entries: AsyncRelatedCollection
+- ledgers: AsyncRelatedCollection
+
+#### Properties
+
+- details: A packify.SerializableType stored in the database as a blob.
+- entries: The related Entrys. Setting raises TypeError if the precondition
+check fails.
+- ledgers: The related Ledgers. Setting raises TypeError if the precondition
+check fails.
+
+#### Methods
+
+##### `@classmethod async prepare(entries: list[Entry], timestamp: str, details: packify.SerializableType = None, reload: bool = False) -> Transaction:`
+
+Prepare a transaction. Raises TypeError for invalid arguments. Raises ValueError
+if the entries do not balance for each ledger; if a required auth script is
+missing; or if any of the entries is contained within an existing Transaction.
+Entries and Transaction will have IDs generated but will not be persisted to the
+database and must be saved separately.
+
+##### `async validate(reload: bool = False) -> bool:`
+
+Determines if a Transaction is valid using the rules of accounting. Raises
+TypeError for invalid arguments. Raises ValueError if the entries do not balance
+for each ledger; or if any of the entries is contained within an existing
+Transaction. If reload is set to True, entries and accounts will be reloaded
+from the database.
+
+##### `async save(reload: bool = False) -> Transaction:`
+
+Validate the transaction, save the entries, then save the transaction.
+
+### `Vendor(AsyncSqlModel)`
+
+#### Annotations
+
+- table: <class 'str'>
+- id_column: <class 'str'>
+- columns: tuple[str]
+- id: <class 'str'>
+- name: <class 'str'>
+- query_builder_class: Type[AsyncQueryBuilderProtocol]
+- connection_info: <class 'str'>
+- data: dict
+- data_original: MappingProxyType
+- _event_hooks: dict[str, list[Callable]]
+- code: str | None
+- details: str | None
+
+#### Properties
+
+- details: A packify.SerializableType stored in the database as a blob.
+
+## Functions
+
+### `set_connection_info(db_file_path: str):`
+
+Set the connection info for all models to use the specified sqlite3 database
+file path.
+
+