pp-terminal 0.6.1

The Analytic Companion for Portfolio Performance

pp-terminal - The Analytic Companion for Portfolio Performance

A powerful command-line tool that uses the openness of Portfolio Performance data and the convenient access of ppxml2db to offer a whole new level of insights into your portfolio.

For example, pp-terminal includes a command to calculate the preliminary tax values ("Vorabpauschale") for Germany:

pp-terminal is a lightweight tool for all the nice-to-have features that won't make it into the official Portfolio Performance app. This can be because of country-dependant tax rules, complex Java implementation, highly individual requirements, too many edge-cases, etc.

By default, pp-terminal provides the following commands:

Command	Description
list accounts	Get detailed information about the balances per each deposit and/or securities account
list securities	Get detailed information about the securities
simulate interest	Calculate how much interest you should have been earned per account and compare with actual values
simulate share-sell	Calculate the taxes if a security from a certain account would be sold
simulate vorabpauschale	Run a simulation for the German preliminary tax ("Vorabpauschale") on the portfolio
validate	Run a number of different validation checks on the portfolio data, e.g. security prices up-to-date

Code completion for commands and options is available.
You can choose between different output formats like JSON or CSV with the --format option.

In addition to the standard set, you can easily create your own commands and share them with the community.

[!IMPORTANT] I am not a tax consultant. All results of this application are just a non-binding indication and without guarantee. They may deviate from the actual values.

Requirements

• pipx to install the application (without having to worry about different Python runtimes)
• Portfolio Performance version >= 0.70.3
• Portfolio Performance file must be saved as "XML with id attributes"

Installing

pipx install pp-terminal

Once installed, update to the latest with:

pipx upgrade pp-terminal

Usage 💡

The commands mentioned above all require the Portfolio Performance XML file as input.
The application does not modify the original Portfolio Performance file.
You can either provide that file as first option to the command

pp-terminal --file=depot.xml list accounts

or by setting an environment variable PP_TERMINAL_INPUT_FILE=depot.xml you can omit the option

pp-terminal list accounts

To view all available arguments you can always use the --help option.

Customize Number Formats

If you want another formatting for numbers, assure that the terminal has the correct language settings, e.g. for Germany set environment variable LANG=de_DE.UTF-8.

Disable Colored Output

To disable all colors in the console output for a better readability, you can set the NO_COLOR=1 environment variable.

Contributing

Propose Changes

To contribute improvements to pp-terminal just follow these steps:

1. Fork and clone this repository
2. Run make
3. Verify build with poetry run pp-terminal --version
4. Create a new branch based on master: git checkout master && git pull && git checkout -b your-patch
5. Implement your changes in this new branch
6. Run make to verify everything is fine
7. Submit a Pull Request

Create Your Own Command ⚒️

Developers can easily extend the default pp-terminal functionality by implementing their own commands. Therefore, the Python entry point pp_terminal.commands is provided. To hook into a sub-command, e.g. list, you have to prefix the entry point name with list..

The most basic pp-terminal command looks like this:

from pp_terminal.output import Console
import typer

app = typer.Typer()
console = Console()


@app.command
def hello_world() -> None:
    console.print("Hello World")

This will result in the command pp-terminal hello-world being available.

For more sophisticated samples take a look at the packaged commands in the pp_terminal/commands directory, e.g. a good starting point is list_accounts.py.

The app uses Typer for composing the commands and Rich for nice console outputs. The Portfolio Performance XML file is read with ppxml2db and efficiently held in pandas dataframes.

If your command makes sense for a broader audience, I'm happy to accept a pull request.

Known Limitations 🚧

• The script is still in beta version, so there might be Portfolio Performance files that are not compatible with and also public APIs can change

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for more details.