mpal-cli 0.0.1__tar.gz → 0.6.0__tar.gz

mpal_cli-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nasser
+
+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.

mpal_cli-0.6.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: mpal-cli
+Version: 0.6.0
+Summary: Multi-Portfolio Asset Ledger (mpal) - A minimal CLI tool for manual asset tracking and capital management.
+License-Expression: MIT
+Keywords: assets,capital,cli,ledger,portfolio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1; extra == "release"
+Requires-Dist: twine>=5; extra == "release"
+Dynamic: license-file
+
+# mpal
+
+mpal — Multi-Portfolio Asset Ledger — is a minimal CLI tool for manual asset
+tracking and capital management.
+
+The CLI command is `mpal`. The package/distribution name is `mpal-cli`.
+Current version: `0.6.0`. License: MIT.
+
+## Installation
+
+mpal requires Python 3.11 or later.
+
+For a future PyPI release:
+
+```console
+python -m pip install mpal-cli
+mpal --help
+```
+
+From a project checkout:
+
+```console
+python -m pip install -e .
+mpal --help
+```
+
+## Storage
+
+mpal stores records in a local SQLite database named `mpal.db`. By default it
+uses the platform data directory, but you can set `MPAL_DATA_DIR` to choose a
+different directory:
+
+```console
+MPAL_DATA_DIR=/path/to/mpal-data mpal init
+```
+
+## What mpal is
+
+- A manual capital ledger.
+- A portfolio tracker.
+- A deterministic, record-based calculator.
+- A local database-backed CLI.
+- A foundation for future extensions.
+
+mpal calculates its results only from manually recorded operations.
+
+## Scope
+
+mpal is intentionally simple. It does not fetch market data, calculate live
+prices, calculate market value, calculate unrealized PnL, connect to market
+APIs or other external services, or provide financial advice.
+
+mpal only works with the records you enter manually.
+
+mpal tracks capital, cash, open positions by book cost, manually recorded
+asset income, realized P&L, and return. Portfolio summaries use
+book/accounting values. Book Value is derived from manual records and is not
+market value.
+
+## Quick Start
+
+```console
+mpal init
+mpal summary
+mpal summary --explain
+mpal portfolio create stocks
+mpal deposit 1000 -p stocks
+mpal withdraw 250 -p stocks
+mpal capital -p stocks
+mpal capital log -p stocks
+mpal asset add AAPL -p stocks
+mpal asset buy AAPL -p stocks --price 234.43 --quantity 3 --fee 2.30
+mpal asset list
+mpal summary -p stocks
+mpal summary -p stocks -a AAPL
+mpal asset log AAPL -p stocks
+```
+
+## Command Hierarchy
+
+mpal groups commands by the records they manage:
+
+```console
+mpal init
+
+mpal summary
+mpal summary --explain
+mpal summary -p stocks
+mpal summary -p stocks -a AAPL
+
+mpal portfolio create stocks
+mpal portfolio create stocks --initial 5000
+mpal portfolio list
+mpal portfolio allocation
+mpal portfolio reset stocks --yes
+mpal portfolio delete stocks --yes
+
+mpal deposit 1000 -p stocks
+mpal withdraw 250 --portfolio stocks --date 2026-06-19 --note "withdrawal"
+mpal capital -p stocks
+mpal capital log -p stocks
+mpal capital entry edit 2 -p stocks --amount 500
+mpal capital entry delete 2 -p stocks
+
+mpal asset add AAPL AMZN MSFT -p stocks
+mpal asset list
+mpal asset list -p stocks
+mpal asset log AAPL -p stocks
+mpal asset delete AAPL -p stocks --yes
+mpal asset entry edit AAPL 2 -p stocks --price 234.50 --quantity 3
+mpal asset entry delete AAPL 2 -p stocks --yes
+mpal asset income AAPL 32 -p stocks --date 2026-06-20 --note "Distribution"
+mpal asset buy AAPL -p stocks --price 234.43 --quantity 3 --fee 2.30
+mpal asset sell AAPL -p stocks --price 235.50 --quantity 1 --fee 1.25
+```
+
+`mpal summary` is the unified summary/reporting command. With no options it
+shows a global dashboard summary across all active portfolios: total capital,
+total cash, positions, book value, total income, realized P&L, and return.
+`mpal summary --explain` prints concise definitions below that global table.
+`mpal summary -p <portfolio>` summarizes one active portfolio. `mpal summary
+-p <portfolio> -a <asset>` summarizes one active asset within one active
+portfolio; `-a` requires `-p`. Positions are open position book cost, not
+market value. Book Value is total cash plus open position book cost. Summary
+views do not use live prices, market value, or unrealized PnL. Global return
+is computed from global totals, not by averaging portfolio returns.
+
+`mpal portfolio allocation` shows active portfolio allocation by book value.
+`BOOK VALUE = TOTAL CASH + POSITIONS`, where positions are open position book
+cost. Allocation is not based on capital, cash alone, market value, live
+prices, or unrealized PnL.
+
+Portfolio-scoped capital and asset operations require `--portfolio` or `-p`.
+Global collection views such as `mpal summary` and `mpal asset list` do not
+require `-p`. No compatibility aliases are kept in this CLI redesign.
+
+Use `mpal deposit <amount> -p <portfolio>` for external capital deposits and
+`mpal withdraw <amount> -p <portfolio>` for external capital withdrawals. Use
+`mpal capital -p <portfolio>` to inspect current capital and
+`mpal capital log -p <portfolio>` to inspect capital history.
+
+Asset list output uses an `Asset/Portfolio` column. Combined labels display
+as `<SYMBOL> • <Portfolio>`, such as `AAPL • Stocks`; portfolio capitalization
+there is display-only, and command syntax still uses `-p <portfolio>`. The
+symbol uses the key style while the portfolio segment is muted for scanning.
+
+Entry numbers shown by `mpal capital log` are stable, portfolio-local
+numbers. Internal database IDs are not part of the CLI contract.
+Capital entry correction is under `mpal capital entry edit/delete`; `mpal
+capital log` remains the historical entry view, and `mpal capital -p
+<portfolio>` is the capital-only current-state view.
+
+Explicit transaction dates must use `YYYY-MM-DD` and cannot be in the future. If
+`--date` is omitted, mpal uses the current local date.
+
+The current release covers initialization, portfolio creation, optional initial capital,
+deposits, withdrawals, summaries, logs, capital-entry correction and deletion,
+portfolio reset, and soft deletion of portfolios. The asset foundation adds
+manual symbol creation, current-state views, and soft deletion under existing
+portfolios. The read-only asset log and its transaction storage foundation are
+also present. Manual asset income updates asset and portfolio summaries.
+Manual buys update open quantity, Cost Basis, portfolio Cash, and Positions.
+Manual sells use moving-average book cost and update open quantity, Cost Basis,
+Cash, Positions, and Realized PnL. Individual asset transactions can be edited
+or soft-deleted by asset-local entry number, with active transactions replayed
+before commit. `asset list` is the current asset collection view, and
+`summary -p <portfolio> -a <asset>` reports current open quantity, Cost Basis,
+Average Cost, Realized PnL, Income, and Realized Return for one asset from
+active manual transactions.
+Asset transaction correction is under `mpal asset entry edit/delete`; `mpal
+asset log` remains the historical transaction view.
+
+`summary` owns global, portfolio, and asset summary/reporting views. Daily
+capital actions are top-level commands, and `capital -p` owns the current
+capital view.
+
+## Planned capabilities
+
+Later releases are planned to extend portfolio tracking, record management, calculations, reporting, backup, import and export, audit tooling, and release automation.
+
+See [the roadmap](docs/ROADMAP.md) for the phased plan.
+
+## Financial advice disclaimer
+
+mpal is a record-keeping and calculation tool. It does not provide financial, investment, tax, or legal advice. Users are responsible for verifying their records and decisions.

mpal_cli-0.6.0/README.md

@@ -0,0 +1,185 @@
+# mpal
+
+mpal — Multi-Portfolio Asset Ledger — is a minimal CLI tool for manual asset
+tracking and capital management.
+
+The CLI command is `mpal`. The package/distribution name is `mpal-cli`.
+Current version: `0.6.0`. License: MIT.
+
+## Installation
+
+mpal requires Python 3.11 or later.
+
+For a future PyPI release:
+
+```console
+python -m pip install mpal-cli
+mpal --help
+```
+
+From a project checkout:
+
+```console
+python -m pip install -e .
+mpal --help
+```
+
+## Storage
+
+mpal stores records in a local SQLite database named `mpal.db`. By default it
+uses the platform data directory, but you can set `MPAL_DATA_DIR` to choose a
+different directory:
+
+```console
+MPAL_DATA_DIR=/path/to/mpal-data mpal init
+```
+
+## What mpal is
+
+- A manual capital ledger.
+- A portfolio tracker.
+- A deterministic, record-based calculator.
+- A local database-backed CLI.
+- A foundation for future extensions.
+
+mpal calculates its results only from manually recorded operations.
+
+## Scope
+
+mpal is intentionally simple. It does not fetch market data, calculate live
+prices, calculate market value, calculate unrealized PnL, connect to market
+APIs or other external services, or provide financial advice.
+
+mpal only works with the records you enter manually.
+
+mpal tracks capital, cash, open positions by book cost, manually recorded
+asset income, realized P&L, and return. Portfolio summaries use
+book/accounting values. Book Value is derived from manual records and is not
+market value.
+
+## Quick Start
+
+```console
+mpal init
+mpal summary
+mpal summary --explain
+mpal portfolio create stocks
+mpal deposit 1000 -p stocks
+mpal withdraw 250 -p stocks
+mpal capital -p stocks
+mpal capital log -p stocks
+mpal asset add AAPL -p stocks
+mpal asset buy AAPL -p stocks --price 234.43 --quantity 3 --fee 2.30
+mpal asset list
+mpal summary -p stocks
+mpal summary -p stocks -a AAPL
+mpal asset log AAPL -p stocks
+```
+
+## Command Hierarchy
+
+mpal groups commands by the records they manage:
+
+```console
+mpal init
+
+mpal summary
+mpal summary --explain
+mpal summary -p stocks
+mpal summary -p stocks -a AAPL
+
+mpal portfolio create stocks
+mpal portfolio create stocks --initial 5000
+mpal portfolio list
+mpal portfolio allocation
+mpal portfolio reset stocks --yes
+mpal portfolio delete stocks --yes
+
+mpal deposit 1000 -p stocks
+mpal withdraw 250 --portfolio stocks --date 2026-06-19 --note "withdrawal"
+mpal capital -p stocks
+mpal capital log -p stocks
+mpal capital entry edit 2 -p stocks --amount 500
+mpal capital entry delete 2 -p stocks
+
+mpal asset add AAPL AMZN MSFT -p stocks
+mpal asset list
+mpal asset list -p stocks
+mpal asset log AAPL -p stocks
+mpal asset delete AAPL -p stocks --yes
+mpal asset entry edit AAPL 2 -p stocks --price 234.50 --quantity 3
+mpal asset entry delete AAPL 2 -p stocks --yes
+mpal asset income AAPL 32 -p stocks --date 2026-06-20 --note "Distribution"
+mpal asset buy AAPL -p stocks --price 234.43 --quantity 3 --fee 2.30
+mpal asset sell AAPL -p stocks --price 235.50 --quantity 1 --fee 1.25
+```
+
+`mpal summary` is the unified summary/reporting command. With no options it
+shows a global dashboard summary across all active portfolios: total capital,
+total cash, positions, book value, total income, realized P&L, and return.
+`mpal summary --explain` prints concise definitions below that global table.
+`mpal summary -p <portfolio>` summarizes one active portfolio. `mpal summary
+-p <portfolio> -a <asset>` summarizes one active asset within one active
+portfolio; `-a` requires `-p`. Positions are open position book cost, not
+market value. Book Value is total cash plus open position book cost. Summary
+views do not use live prices, market value, or unrealized PnL. Global return
+is computed from global totals, not by averaging portfolio returns.
+
+`mpal portfolio allocation` shows active portfolio allocation by book value.
+`BOOK VALUE = TOTAL CASH + POSITIONS`, where positions are open position book
+cost. Allocation is not based on capital, cash alone, market value, live
+prices, or unrealized PnL.
+
+Portfolio-scoped capital and asset operations require `--portfolio` or `-p`.
+Global collection views such as `mpal summary` and `mpal asset list` do not
+require `-p`. No compatibility aliases are kept in this CLI redesign.
+
+Use `mpal deposit <amount> -p <portfolio>` for external capital deposits and
+`mpal withdraw <amount> -p <portfolio>` for external capital withdrawals. Use
+`mpal capital -p <portfolio>` to inspect current capital and
+`mpal capital log -p <portfolio>` to inspect capital history.
+
+Asset list output uses an `Asset/Portfolio` column. Combined labels display
+as `<SYMBOL> • <Portfolio>`, such as `AAPL • Stocks`; portfolio capitalization
+there is display-only, and command syntax still uses `-p <portfolio>`. The
+symbol uses the key style while the portfolio segment is muted for scanning.
+
+Entry numbers shown by `mpal capital log` are stable, portfolio-local
+numbers. Internal database IDs are not part of the CLI contract.
+Capital entry correction is under `mpal capital entry edit/delete`; `mpal
+capital log` remains the historical entry view, and `mpal capital -p
+<portfolio>` is the capital-only current-state view.
+
+Explicit transaction dates must use `YYYY-MM-DD` and cannot be in the future. If
+`--date` is omitted, mpal uses the current local date.
+
+The current release covers initialization, portfolio creation, optional initial capital,
+deposits, withdrawals, summaries, logs, capital-entry correction and deletion,
+portfolio reset, and soft deletion of portfolios. The asset foundation adds
+manual symbol creation, current-state views, and soft deletion under existing
+portfolios. The read-only asset log and its transaction storage foundation are
+also present. Manual asset income updates asset and portfolio summaries.
+Manual buys update open quantity, Cost Basis, portfolio Cash, and Positions.
+Manual sells use moving-average book cost and update open quantity, Cost Basis,
+Cash, Positions, and Realized PnL. Individual asset transactions can be edited
+or soft-deleted by asset-local entry number, with active transactions replayed
+before commit. `asset list` is the current asset collection view, and
+`summary -p <portfolio> -a <asset>` reports current open quantity, Cost Basis,
+Average Cost, Realized PnL, Income, and Realized Return for one asset from
+active manual transactions.
+Asset transaction correction is under `mpal asset entry edit/delete`; `mpal
+asset log` remains the historical transaction view.
+
+`summary` owns global, portfolio, and asset summary/reporting views. Daily
+capital actions are top-level commands, and `capital -p` owns the current
+capital view.
+
+## Planned capabilities
+
+Later releases are planned to extend portfolio tracking, record management, calculations, reporting, backup, import and export, audit tooling, and release automation.
+
+See [the roadmap](docs/ROADMAP.md) for the phased plan.
+
+## Financial advice disclaimer
+
+mpal is a record-keeping and calculation tool. It does not provide financial, investment, tax, or legal advice. Users are responsible for verifying their records and decisions.

mpal_cli-0.6.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mpal-cli"
+version = "0.6.0"
+description = "Multi-Portfolio Asset Ledger (mpal) - A minimal CLI tool for manual asset tracking and capital management."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["assets", "capital", "cli", "ledger", "portfolio"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "rich>=13",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+]
+release = [
+    "build>=1",
+    "twine>=5",
+]
+
+[project.scripts]
+mpal = "mpal.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

mpal_cli-0.6.0/src/mpal/__init__.py

@@ -0,0 +1,3 @@
+"""mpal command-line application."""
+
+__version__ = "0.6.0"

mpal_cli-0.6.0/src/mpal/__main__.py

@@ -0,0 +1,12 @@
+"""Run mpal with ``python -m mpal``."""
+
+from mpal.cli import app
+
+
+def main() -> None:
+    """Run the mpal CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

mpal_cli-0.6.0/src/mpal/amounts.py

@@ -0,0 +1,44 @@
+"""Exact monetary parsing and money-specific display formatting."""
+
+from decimal import Decimal, InvalidOperation
+
+from mpal.errors import InvalidAmountError
+
+MINOR_UNITS_PER_UNIT = 100
+
+
+def parse_amount_minor(amount: str, *, allow_zero: bool = False) -> int:
+    """Parse money with at most two decimal places."""
+    try:
+        decimal_amount = Decimal(amount)
+    except InvalidOperation as error:
+        raise InvalidAmountError(f"Invalid amount: '{amount}'.") from error
+
+    if not decimal_amount.is_finite():
+        raise InvalidAmountError(f"Invalid amount: '{amount}'.")
+    if decimal_amount < 0 or (decimal_amount == 0 and not allow_zero):
+        comparison = "nonnegative" if allow_zero else "greater than zero"
+        raise InvalidAmountError(f"Amount must be {comparison}.")
+    if decimal_amount.as_tuple().exponent < -2:
+        raise InvalidAmountError("Amount cannot have more than 2 decimal places.")
+
+    minor_amount = decimal_amount * MINOR_UNITS_PER_UNIT
+    if minor_amount != minor_amount.to_integral_value():
+        raise InvalidAmountError("Amount cannot have more than 2 decimal places.")
+
+    return int(minor_amount)
+
+
+def format_money(amount_minor: int) -> str:
+    """Format integer minor units as money with grouping and two places."""
+    sign = "-" if amount_minor < 0 else ""
+    whole, fraction = divmod(abs(amount_minor), MINOR_UNITS_PER_UNIT)
+    return f"{sign}{whole:,}.{fraction:02d}"
+
+
+def format_signed_money(amount_minor: int) -> str:
+    """Format profit or loss money with an explicit positive sign."""
+    formatted = format_money(amount_minor)
+    if amount_minor > 0:
+        return f"+{formatted}"
+    return formatted