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
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
```