fz0x1/pricehist
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

More README changes.

Browse source
This commit is contained in:
Chris Berkhout 2021-08-17 12:58:49 +02:00
parent a4c0a142e3
commit fecd61f5f8
1 changed files with 68 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

161
README.md
View file

@ -12,10 +12,10 @@ support for multiple data sources and output formats.
## Installation ## Installation
Install via [pip](https://pip.pypa.io/en/stable/) or Install via pip or
[pipx](https://pypa.github.io/pipx/): [pipx](https://pypa.github.io/pipx/):
```bash ```
pipx install pricehist pipx install pricehist
``` ```
@ -36,33 +36,44 @@ pipx install pricehist
## Usage ## 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: ```
pricehist fetch ecb EUR/AUD -s 2021-01-04 -e 2021-01-08
```bash
pricehist -h
``` ```
``` ```
usage: pricehist [-h] [--version] [-vvv] {sources,source,fetch} ... date,base,quote,amount,source,type
2021-01-04,EUR,AUD,1.5928,ecb,reference
Fetch historical price data 2021-01-05,EUR,AUD,1.5927,ecb,reference
2021-01-06,EUR,AUD,1.5824,ecb,reference
optional arguments: 2021-01-07,EUR,AUD,1.5836,ecb,reference
-h, --help show this help message and exit 2021-01-08,EUR,AUD,1.5758,ecb,reference
--version show version information
-vvv, --verbose show all log messages
commands:
{sources,source,fetch}
sources list sources
source show source details
fetch fetch prices
``` ```
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 pricehist fetch -h
@ -98,47 +109,12 @@ optional arguments:
--fmt-csvdelim CHAR field delimiter for CSV output (default: ',') --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: As the output format you can choose one of `beancount`, `csv`, `ledger` or
```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
`gnucash-sql`. `gnucash-sql`.
```bash ```
pricehist fetch ecb EUR/AUD -s 2021-01-04 -e 2021-01-08 -o ledger 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 P 2021-01-08 00:00:00 EUR 1.5758 AUD
``` ```
The formatting options let you control certain details of the output. The Formatting options let you control certain details of the output.
following example removes the time of day (to make it suitable for hledger) and
makes a few other adjustments.
```bash ```
pricehist fetch ecb EUR/AUD -s 2021-01-04 -e 2021-01-08 -o ledger \ 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 --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 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 You can generate SQL for a GnuCash database and apply it immediately with one
of the following commands: 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 | 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 | 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 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 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 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. 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 ID : alphavantage
Name : European Central Bank Name : Alpha Vantage
Description : European Central Bank Euro foreign exchange reference rates Description : Provider of market data for stocks, forex and cryptocurrencies
URL : https://www.ecb.europa.eu/stats/exchange/eurofxref/html/index.en.html URL : https://www.alphavantage.co/
Start : 1999-01-04 Start : 1995-01-01
Types : reference 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 Available symbols can be listed for most sources, either as full pairs or as
separate base and quote symbols that work in particular combinations: separate base and quote symbols that will work in certain combinations:
```bash ```
pricehist source ecb --symbols pricehist source ecb --symbols
``` ```
``` ```
@ -216,7 +191,7 @@ EUR/CHF Euro against Swiss Franc
It may also be possible to search for symbols: It may also be possible to search for symbols:
```bash ```
pricehist source alphavantage --search Tesla pricehist source alphavantage --search Tesla
``` ```
``` ```
@ -227,12 +202,13 @@ TSLA Tesla Inc, Equity, United States, USD
TXLZF Tesla Exploration Ltd, 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 You can see extra information by adding the verbose option (`--verbose` or
request to a source, by adding the verbose option (`--verbose` or `-vvv`): `-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 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 You can run a logged `curl` command to see exactly what data is returned by the
source: source:
```bash ```
pricehist fetch coindesk BTC/USD -s 2021-01-01 -e 2021-01-05 -vvv 2>&1 \ 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 ```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 ### Use as a library
While not yet optimized for use as a library, you may find `pricehist`'s source You may find `pricehist`'s source classes useful in your own scripts:
classes useful in your own scripts:
```python ```
$ python $ python
Python 3.9.6 (default, Jun 30 2021, 10:22:16) Python 3.9.6 (default, Jun 30 2021, 10:22:16)
[GCC 11.1.0] on linux [GCC 11.1.0] on linux
@ -319,7 +294,7 @@ of the base.
Consider the following command: Consider the following command:
```bash ```
pricehist fetch coindesk BTC/USD --type close pricehist fetch coindesk BTC/USD --type close
``` ```