The command line#
pyeconomics runs every registered model and reads every data source from a
shell, so a script, R (system2) or Excel Power Query can use them. A model
runs through the same path as the Python API, and --format json prints the
same canonical result Result.to_json() gives, byte for byte, followed by one
newline. The command line comes with the core package: no extra is needed.
Installation#
Install it as a tool, isolated from your projects, with pipx or uv:
pipx install --pre pyeconomics
uv tool install --prerelease allow pyeconomics
--pre and --prerelease allow are needed while 1.0 is in pre-release. To
store providers’ keys in the OS keyring, install the extra too:
pipx install --pre "pyeconomics[keyring]".
$ pyeconomics --version
The commands#
Command |
What it does |
|---|---|
|
List the registered models |
|
Search models by id, title, tags, domain and summary |
|
Print a model’s card, or its full description |
|
Run a model; its inputs are options |
|
Run a model once per row of a CSV or JSON Lines file |
|
Also explain the result with the optional AI narrative (The AI narrative) |
|
Search catalog concepts, then providers’ series |
|
Get a concept’s or a series’ data, transformed if asked |
|
Describe a concept, a series or a provider |
|
List the dates a series changed |
|
List the providers with their licences and keys |
|
Store a provider’s key in the OS keyring |
|
Name where each key would be read from |
|
Delete a key from the OS keyring |
|
Inspect and clear the data cache |
|
Write |
|
Verify a reproducibility bundle without running anything from it (Exports and reproducibility bundles) |
|
Serve the REST API on this machine, with the |
|
Shell completion |
Every command takes --help, and --debug (anywhere on the line) adds a
traceback to a failure. A target is a catalog concept id
(us.unemployment.rate) or a provider series (fred:UNRATE), never a URL.
$ pyeconomics --help
$ pyeconomics models list --domain fixed_income
$ pyeconomics models search "present value annuity" --limit 3
$ pyeconomics models describe fixed_income.bond_pricing
Running a model#
models run ID takes one option per input field of the model, its name written
with hyphens (present_value is --present-value). A number, a date, a choice
or text is written as it is, a boolean as true or false, and an array as a
JSON literal. A model with several calculations needs --calculation.
pyeconomics models run ID --help lists the model’s own options with their
units, and the values each calculation takes.
$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100
$ pyeconomics models run foundations.time_value --calculation irr --cash-flows "[-100, 30, 40, 50]" --format table
$ pyeconomics models run foundations.time_value --help
The first prints the result as canonical JSON (abridged here):
{"inputs":{"calculation":"present_value",...},"manifest":{...},"model_id":"foundations.time_value","model_version":2,"outputs":{"calculation":"present_value","present_value":61.391325354075946},"warnings":[]}
The inputs can also come as a JSON object, from a file or from standard input
(-); options given beside them override the file’s values. The codec reads at
most 16 MiB and refuses repeated keys, NaN and infinity:
pyeconomics models run foundations.time_value --inputs inputs.json --rate 0.06
cat inputs.json | pyeconomics models run foundations.time_value --inputs -
Binding data#
A model that declares data bindings reads its inputs from the data catalog
when any of --as-of DATE, --vintage real_time|latest, --profile NAME,
--concept FIELD=ID or --param NAME=VALUE is given. --as-of reads the data
as published on that date; without it the latest data is read (--profile default binds the default profile so), which a binding that reads a window up
to a date refuses. Options for its fields then override the values bound, and
the result’s manifest records every series, vintage and retrieval time
(Binding models to data):
$ pyeconomics models run macro.recession_probability --as-of 2024-06-28
$ pyeconomics models run macro.recession_probability --as-of 2024-06-28 --format table
$ pyeconomics models run macro.policy_rule --calculation taylor_1993 --profile default
The table prints the data’s sources and, below them, every attribution and notice the data requires.
Data, keys and the cache#
The data commands wrap the data API unchanged, with its
modes, licences and keys. data get --format json prints the frame with its
source records and the attributions its data must be shown with:
$ pyeconomics data search "unemployment rate" --limit 2
$ pyeconomics data describe us.unemployment.rate
$ pyeconomics data sources
$ pyeconomics data get us.treasury.nominal_10y --start 2024-01-01 --end 2024-01-31 --format table
$ pyeconomics data get us.unemployment.rate --start 2024-01-01 --transform "diff(periods=12)"
$ pyeconomics data vintages fred:UNRATE
A key is never an argument, which shell history would keep. keys set asks
for it with a hidden prompt, or reads the first line of standard input with
--stdin, checks it and stores it in the OS keyring (Keys and configuration):
pyeconomics keys set fred
my-secrets-tool read fred | pyeconomics keys set fred --stdin
keys list names where each key would be read from (environment, dotenv,
keyring or none) and never its value:
$ pyeconomics keys list
$ pyeconomics data sources --check-keys
The cache commands show what is cached, never a payload, and create nothing (The cache and offline mode):
$ pyeconomics cache info
$ pyeconomics cache ls
$ pyeconomics cache path
$ pyeconomics cache clear
registry export writes the description of every model, the file the web app
is built from, and with the server extra the REST API’s OpenAPI document:
$ pyeconomics registry export --out site --no-figures
Formats#
|
Output |
|---|---|
|
Canonical JSON (RFC 8785) followed by one newline; the default of |
|
Tables, drawn with borders on a terminal and as aligned plain text in a pipe or a file, with attributions and notices below; the default of the listing commands |
|
The model card ( |
|
An export with its attributions, notices and manifest ( |
--out PATH writes the same bytes to a file instead of standard output. Output
is UTF-8 on every operating system, Windows included, whatever the console’s
code page. A binary format (xlsx, parquet, arrow) goes to standard output
only when it is not a terminal: name a file with --out, redirect it or pipe
it. Parquet and Arrow need pyarrow, which pyeconomics never installs; without
it they exit with code 8.
$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100 --format csv
$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100 --format xlsx --out pv.xlsx
$ pyeconomics models run foundations.time_value --calculation present_value --rate 0.05 --periods 10 --future-value 100 --bundle pv.zip
--bundle PATH also writes the run’s reproducibility bundle, a zip that
pyeconomics bundle check PATH verifies and its own reproduce.py reruns
(Exports and reproducibility bundles). --batch FILE runs the model once per row of a CSV file with
a header row of field names, or a JSON Lines file (- reads standard input);
it takes no field options, --inputs, --bundle or data options beside it:
pyeconomics models run foundations.time_value --batch rows.csv --format csv --out results.csv
pyeconomics bundle check pv.zip
--narrate also asks the optional AI narrative to explain the result, with
your own key (The AI narrative). It follows a table on standard output, and goes to
standard error with any other format or --out, so standard output stays the
canonical bytes; it is never written into an export or a bundle.
Serving the REST API#
With the server extra, pyeconomics serve serves the REST API on
127.0.0.1 port 8000 until Ctrl+C, its runs in worker processes (The REST API):
pipx install --pre "pyeconomics[server]"
pyeconomics serve --port 8000 --workers 2
It reads every source this machine can access, with its keys, so a host that is
not a loopback address is refused (exit code 2) unless --allow-remote is
passed. Without the extra it exits with code 8.
With the app extra, which brings the server extra’s requirements and the
pyeconomics-app wheel at the same version, the same command also serves the
web app at /: every model page, calculator and the data explorer, as
pyeconomics.dev serves them, with the same security headers.
pipx install --pre "pyeconomics[app]"
pyeconomics serve
Open http://127.0.0.1:8000. Served locally, the calculators offer live data
from every source your installation reaches, library-only ones included, with
your own keys where a source needs one, and the data explorer offers the whole
catalog rather than the hosted snapshot. The local site loads no analytics and
no error tracking and is never indexed, and the API keeps its routes (/v1,
/mcp, /docs and the rest). Without the app, serve logs one line saying how
to install it and serves the API alone. The site’s policy upgrades insecure
requests, as production’s does; browsers exempt loopback addresses, but a
browser on another machine (--allow-remote) needs the site behind HTTPS.
Exit codes#
A failure prints one line on standard error, the problem’s slug and a detail that never holds a key, a file path, a host or an upstream URL (Problem types), and exits with its code:
Code |
Meaning |
|---|---|
0 |
Success |
1 |
Internal error, an invalid setting or an inconsistent registry |
2 |
The command line does not parse ( |
3 |
Invalid input |
4 |
The inputs have no defined result, or the method found none |
5 |
Not found: a model, a provider, a concept or a series |
6 |
Not permitted: the source’s licence refuses this use |
7 |
Data unavailable: a key, the source, offline mode or a rate limit |
8 |
An optional extra is not installed |
$ pyeconomics models run foundations.time_value --calculation present_value --rate 7
invalid-input: The inputs failed validation: present_value.rate: Input should be less than or equal to 1.
Shell completion#
pyeconomics --install-completion writes the completion script where the
current shell looks for it. pyeconomics completion bash (or zsh, fish,
powershell) prints the script instead, to install by hand:
$ pyeconomics completion bash
Completion covers the commands and their options; a model’s run options are
generated when the command line names the model, so they are listed by
pyeconomics models run ID --help.