Metadata-Version: 2.4
Name: beancount-derived-prices
Version: 0.1.0
Summary: Beancount plugin to derive commodity prices in alternative currencies like gold (XAU)
Project-URL: Homepage, https://github.com/stenius/beancount-derived-prices
Project-URL: Repository, https://github.com/stenius/beancount-derived-prices
Project-URL: Issues, https://github.com/stenius/beancount-derived-prices/issues
Author: Paul Stenius
License-Expression: MIT
License-File: LICENSE
Keywords: accounting,beancount,currency,fava,finance,gold,prices
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.8
Requires-Dist: beancount>=2.3
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# beancount-derived-prices

A Beancount plugin that automatically generates commodity prices in alternative currencies (like gold/XAU) based on existing price data.

## Why?

If you track your investments in USD but want to see their value in gold (XAU) to measure real purchasing power over time, you'd normally need to manually calculate and enter prices like:

```beancount
2024-01-02 price VTSAX 0.060578 XAU
```

This plugin does that automatically. Given:

```beancount
2024-01-02 price VTSAX 163.56 USD
2024-01-02 price XAU   2700.00 USD
```

It derives:

```beancount
2024-01-02 price VTSAX 0.060578 XAU  ; 163.56 / 2700.00
```

## Features

- **Derived Prices**: Convert all commodity prices to an alternative currency
- **Inverse Rates**: Automatically generates inverse exchange rates (e.g., USD/XAU)
- **Proxy Commodities**: Create a chartable commodity that mirrors an operating currency's price (useful for Fava, which doesn't show charts for operating currencies)
- **Configurable**: Exclude specific commodities, adjust decimal precision

## Installation

```bash
pip install beancount-derived-prices
```

Or install from source:

```bash
git clone https://github.com/stenius/beancount-derived-prices
cd beancount-derived-prices
pip install -e .
```

## Usage

Add to your beancount file:

```beancount
plugin "beancount_derived_prices" "target:XAU via:USD"
```

### Configuration Options

| Option | Default | Description |
|--------|---------|-------------|
| `target:<currency>` | `XAU` | Target currency to derive prices into |
| `via:<currency>` | `USD` | Base currency used for conversion |
| `exclude:<c1,c2>` | (none) | Comma-separated commodities to exclude |
| `precision:<n>` | `6` | Decimal places for derived prices |
| `proxy:<commodity>` | (none) | Create a proxy commodity for charting |

### Examples

**Basic gold pricing:**
```beancount
plugin "beancount_derived_prices" "target:XAU via:USD"
```

**With proxy for Fava charts:**
```beancount
; XAU is an operating currency, so Fava won't show a price chart for it.
; The proxy:GOLD option creates a GOLD commodity with XAU's USD prices,
; which will show up in Fava's Commodities page with a chart.
plugin "beancount_derived_prices" "target:XAU via:USD proxy:GOLD"
```

**Exclude volatile assets:**
```beancount
plugin "beancount_derived_prices" "target:XAU via:USD exclude:BTC,ETH"
```

**Higher precision:**
```beancount
plugin "beancount_derived_prices" "target:XAU via:USD precision:8"
```

**Full example:**
```beancount
option "operating_currency" "USD"
option "operating_currency" "XAU"

plugin "beancount_derived_prices" "target:XAU via:USD proxy:GOLD exclude:BTC precision:8"

; Your price data
2024-01-02 price XAU   2700.00 USD
2024-01-02 price VTSAX 163.56 USD
2024-01-02 price VOO   480.00 USD

; The plugin automatically generates:
; 2024-01-02 price VTSAX 0.06057778 XAU
; 2024-01-02 price VOO   0.17777778 XAU
; 2024-01-02 price USD   0.00037037 XAU
; 2024-01-02 price GOLD  2700.00 USD
```

## How It Works

1. **Collects prices**: Finds all `price` directives quoted in the base currency (USD)
2. **Calculates derived prices**: For each date with a target currency price (XAU), divides each commodity's base price by the target's base price
3. **Generates inverse rates**: Creates base-to-target exchange rates (USD → XAU)
4. **Creates proxy** (optional): Mirrors the target currency's price as a regular commodity for charting

## Use Cases

### Track Portfolio in Gold

See how your investments perform relative to gold's purchasing power:

```beancount
option "operating_currency" "USD"
option "operating_currency" "XAU"

2016-04-14 custom "fava-option" "conversion-currencies" "USD XAU"

plugin "beancount_derived_prices" "target:XAU via:USD"
```

Now in Fava, you can view your balance sheet converted to XAU.

### Multiple Alternative Currencies

Run the plugin multiple times with different targets:

```beancount
plugin "beancount_derived_prices" "target:XAU via:USD"
plugin "beancount_derived_prices" "target:BTC via:USD"
```

## Requirements

- Python 3.8+
- Beancount 2.3+

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! Please open an issue or submit a pull request.
