From fecd61f5f891d92fba3449f06f6e541d0b2eb11a Mon Sep 17 00:00:00 2001 From: Chris Berkhout Date: Tue, 17 Aug 2021 12:58:49 +0200 Subject: [PATCH] More README changes. --- README.md | 161 +++++++++++++++++++++++------------------------------- 1 file changed, 68 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 8d02e6a..06e2842 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,10 @@ support for multiple data sources and output formats. ## Installation -Install via [pip](https://pip.pypa.io/en/stable/) or +Install via pip or [pipx](https://pypa.github.io/pipx/): -```bash +``` pipx install pricehist ``` @@ -36,33 +36,44 @@ pipx install pricehist ## Usage -The following sections demonstrate different uses of `pricehist`. +### Fetch prices -### Online help +Fetch prices by choosing a source, a pair and, optionally, a time interval: -The `-h` option will show usage information: - -```bash -pricehist -h +``` +pricehist fetch ecb EUR/AUD -s 2021-01-04 -e 2021-01-08 ``` ``` -usage: pricehist [-h] [--version] [-vvv] {sources,source,fetch} ... - -Fetch historical price data - -optional arguments: - -h, --help show this help message and exit - --version show version information - -vvv, --verbose show all log messages - -commands: - {sources,source,fetch} - sources list sources - source show source details - fetch fetch prices +date,base,quote,amount,source,type +2021-01-04,EUR,AUD,1.5928,ecb,reference +2021-01-05,EUR,AUD,1.5927,ecb,reference +2021-01-06,EUR,AUD,1.5824,ecb,reference +2021-01-07,EUR,AUD,1.5836,ecb,reference +2021-01-08,EUR,AUD,1.5758,ecb,reference ``` -Here's the usage information for the `fetch` command: +The default output format is CSV, which is suitable for use in spreadsheets and +with other tools. For example, on the command line using +[gnuplot](http://www.gnuplot.info/) we can chart Bitcoin prices: + +``` +pricehist fetch coindesk BTC/USD -s 2021-01-01 | \ + cut -d, -f1,4 | \ + sed 1d | \ + gnuplot -p -e ' + set datafile separator ","; + set xdata time; + set timefmt "%Y-%m-%d"; + set format x "%b\n%Y"; + plot "/dev/stdin" using 1:2 with lines title "BTC/USD" + ' +``` + +![BTC/USD prices](example-gnuplot.png) + +### Show usage information + +Add `-h` to any command to see usage information: ``` pricehist fetch -h @@ -98,47 +109,12 @@ optional arguments: --fmt-csvdelim CHAR field delimiter for CSV output (default: ',') ``` -### Fetching prices +### Choose and customize the output format -Fetch prices by choosing a source, a pair and, optionally, a time interval: - -```bash -pricehist fetch ecb EUR/AUD -s 2021-01-04 -e 2021-01-08 -``` -``` -date,base,quote,amount,source,type -2021-01-04,EUR,AUD,1.5928,ecb,reference -2021-01-05,EUR,AUD,1.5927,ecb,reference -2021-01-06,EUR,AUD,1.5824,ecb,reference -2021-01-07,EUR,AUD,1.5836,ecb,reference -2021-01-08,EUR,AUD,1.5758,ecb,reference -``` - -The default output format is CSV, which is suitable for use in spreadsheets and -with other tools. For example, on the command line using -[gnuplot](http://www.gnuplot.info/) we can chart Bitcoin prices: - -```bash -pricehist fetch coindesk BTC/USD -s 2021-01-01 | \ - cut -d, -f1,4 | \ - sed 1d | \ - gnuplot -p -e ' - set datafile separator ","; - set xdata time; - set timefmt "%Y-%m-%d"; - set format x "%b\n%Y"; - plot "/dev/stdin" using 1:2 with lines title "BTC/USD" - ' -``` - -![BTC/USD prices](example-gnuplot.png) - -### Choosing and customizing the output format - -You can choose a different output format: `ledger`, `beancount` or +As the output format you can choose one of `beancount`, `csv`, `ledger` or `gnucash-sql`. -```bash +``` pricehist fetch ecb EUR/AUD -s 2021-01-04 -e 2021-01-08 -o ledger ``` ``` @@ -149,11 +125,9 @@ P 2021-01-07 00:00:00 EUR 1.5836 AUD P 2021-01-08 00:00:00 EUR 1.5758 AUD ``` -The formatting options let you control certain details of the output. The -following example removes the time of day (to make it suitable for hledger) and -makes a few other adjustments. +Formatting options let you control certain details of the output. -```bash +``` pricehist fetch ecb EUR/AUD -s 2021-01-04 -e 2021-01-08 -o ledger \ --fmt-time '' --fmt-datesep / --fmt-base € --fmt-quote $ --fmt-symbol left ``` @@ -165,12 +139,12 @@ P 2021/01/07 € $1.5836 P 2021/01/08 € $1.5758 ``` -### GnuCash SQL output +### Load prices into GnuCash You can generate SQL for a GnuCash database and apply it immediately with one of the following commands: -```bash +``` pricehist fetch ecb EUR/AUD -s 2021-01-01 -o gnucash-sql | sqlite3 Accounts.gnucash pricehist fetch ecb EUR/AUD -s 2021-01-01 -o gnucash-sql | mysql -u username -p -D databasename pricehist fetch ecb EUR/AUD -s 2021-01-01 -o gnucash-sql | psql -U username -d databasename -v ON_ERROR_STOP=1 @@ -178,31 +152,32 @@ pricehist fetch ecb EUR/AUD -s 2021-01-01 -o gnucash-sql | psql -U username -d d Beware that the GnuCash project itself does not support integration at the database level, so there is a risk that the SQL generated by `pricehist` will -be ineffective or even damaging for some new version of GnuCash. +be ineffective or even damaging for some version of GnuCash. In practice, this strategy has been used successfully by other projects. -Reviewing the SQL and keeping regular database backups is recommended. +Reading the SQL and keeping regular database backups is recommended. -### Source information +### Show source information -Some basic information about each source is available: +The `source` command shows information about a source. -```bash -pricehist source ecb +``` +pricehist source alphavantage ``` ``` -ID : ecb -Name : European Central Bank -Description : European Central Bank Euro foreign exchange reference rates -URL : https://www.ecb.europa.eu/stats/exchange/eurofxref/html/index.en.html -Start : 1999-01-04 -Types : reference +ID : alphavantage +Name : Alpha Vantage +Description : Provider of market data for stocks, forex and cryptocurrencies +URL : https://www.alphavantage.co/ +Start : 1995-01-01 +Types : close, open, high, low, adjclose, mid +Notes : Alpha Vantage has data on... ``` -Symbol information can be listed for most sources, either as full pairs or as -separate base and quote symbols that work in particular combinations: +Available symbols can be listed for most sources, either as full pairs or as +separate base and quote symbols that will work in certain combinations: -```bash +``` pricehist source ecb --symbols ``` ``` @@ -216,7 +191,7 @@ EUR/CHF Euro against Swiss Franc It may also be possible to search for symbols: -```bash +``` pricehist source alphavantage --search Tesla ``` ``` @@ -227,12 +202,13 @@ TSLA Tesla Inc, Equity, United States, USD TXLZF Tesla Exploration Ltd, Equity, United States, USD ``` -### Inspecting source interactions +### Inspect source interactions -You can see extra information, including `curl` commands to reproduce each -request to a source, by adding the verbose option (`--verbose` or `-vvv`): +You can see extra information by adding the verbose option (`--verbose` or +`-vvv`). This will include `curl` commands to reproduce each request to a +source. -```bash +``` pricehist fetch coindesk BTC/USD -s 2021-01-01 -e 2021-01-05 -vvv ``` ``` @@ -253,9 +229,9 @@ DEBUG Ended pricehist run at 2021-08-12 14:38:26.709428. You can run a logged `curl` command to see exactly what data is returned by the source: -```bash +``` pricehist fetch coindesk BTC/USD -s 2021-01-01 -e 2021-01-05 -vvv 2>&1 \ - | grep 'DEBUG curl' | sed 's/^DEBUG //' | bash | jq . + | grep '^DEBUG curl' | sed 's/^DEBUG //' | bash | jq . ``` ```json { @@ -276,10 +252,9 @@ pricehist fetch coindesk BTC/USD -s 2021-01-01 -e 2021-01-05 -vvv 2>&1 \ ### Use as a library -While not yet optimized for use as a library, you may find `pricehist`'s source -classes useful in your own scripts: +You may find `pricehist`'s source classes useful in your own scripts: -```python +``` $ python Python 3.9.6 (default, Jun 30 2021, 10:22:16) [GCC 11.1.0] on linux @@ -319,7 +294,7 @@ of the base. Consider the following command: -```bash +``` pricehist fetch coindesk BTC/USD --type close ```