Initial commit with v1.0.0 release

.gitignore

@@ -0,0 +1,10 @@
+*.sw*
+Session.vim
+*.egg-info/
+__pycache__/
+build/
+dist/
+*.egg
+*.zip
+tags
+*.~lock*

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Matthew Mitchell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,149 @@
+# PyCryptax
+
+Pycryptax calculates income and capital gains using transactions and price
+data from CSV files which can include cryptoassets such as Bitcoin. Capital
+gains are calculated according to section 104 holding; 30-day bed and
+breakfasting; and same-day rules. Guidance is available through an [HMRC
+publication
+online](https://www.gov.uk/government/publications/tax-on-cryptoassets/cryptoassets-for-individuals).
+
+To install the program you must have Python 3. You can install using pip
+(remember to use `sudo` if needed):
+
+    pip3 install pycryptax
+
+Alternatively you can run the following command in the project's root directory:
+
+    python3 setup.py install
+
+After installation, the `pycryptax` command should be available and you may run
+`pycryptax --help` to view an overview of the usage. See below for more details
+on how to use the software.
+
+## Disclaimer
+
+**Do not rely on this software for accuracy. Anything provided by this software
+does not constitute advice in any form. The software is provided "as is",
+without warranty of any kind. Use at your own risk. See the LICENSE file for
+more details.**
+
+## Providing Data
+
+Transaction data for income and gains need to be provided in CSV files contained
+within particular directories. Prices are kept in `./prices`, capital gain/loss
+trades in `./gains` and income transactions in `./income`. These directories
+should be found within the present working directory or the directory provided
+by the `--dir` command line option.
+
+CSV files can be produced by any decent spreadsheet software. Spreadsheet
+software can be used to manipulate exported price, exchange and wallet data into
+the correct format.
+
+Empty rows are allowed. Additional columns for comments etc. are allowed and
+ignored.
+
+Please see the `./examples` directory which contains an example of how data
+should be provided.
+
+### Price data
+
+Inside the `./prices` directory, CSV files containing price data for asset pairs
+can be provided. This price data is used to convert asset amounts into the
+reporting/account currency for which the tax calculation is being done (`gbp` by
+default).
+
+Each file should be formatted as `XXX_YYY.csv` where `XXX` is the base currency,
+and `YYY` is the quote currency. For example `btc_gbp.csv` would contain the GBP
+prices of 1 bitcoin.
+
+These files can be chained together to combine conversions. For example
+`btc_usd.csv` and `usd_gbp.csv` would allow conversion of bitcoin to GBP by
+converting to USD first. The software only allows conversions to be done through
+a single chain and they can only be done from the base currency to the quoted
+currency so `gbp_btc.csv` would allow conversions of GBP to bitcoin but not
+bitcoin to GBP.
+
+Each file should contain a list of daily prices for the asset pair. If a price
+is not available for a specifc date, then the soonest earlier date available is
+used instead.
+
+The price csv files should use the following columns:
+
+| Column | Description                                                         |
+| ------ | ------------------------------------------------------------------- |
+| DATE   | The date of the price formatted as YYYY-MM-DD                       |
+| PRICE  | A decimal number of the price of the base asset in the quoted asset |
+
+### Income data
+
+Transactions for all revenues (positive amounts) and expenses (negative amounts)
+can be provided under the `./income` directory in as many CSV files as desired.
+The CSV files can be named anything as long as they end in `.csv`. Transactional
+data should be provided with the following columns:
+
+| Column | Description                                                                  |
+| ------ | ---------------------------------------------------------------------------- |
+| DATE   | The date of the transaction formatted as YYYY-MM-DD                          |
+| ASSET  | The asset transacted, in the same format provided by the prices CSV filename |
+| AMOUNT | The amount of the asset received/debited (positive) or sent/credited (negative) |
+| NOTE   | A note to be provided when outputing transactions                            |
+
+### Capital Gain/Loss data
+
+Trades between assets, and other acquisitions or disposals can be provided in
+the `./gains` directory in as many CSV files as desired. The CSV files can be
+named anything as long as they end in `.csv`.
+
+If one asset is being traded for another, then they should be provided on the
+same row. Sometimes assets are acquired or disposed without a counter asset. In
+this case, only the single asset should be provided and the other cells should be
+empty.
+
+If you are selling or buying an asset against the reporting currency (GBP by
+default), then the amount of the reporting currency should be provided as a
+corresponding buy/sell asset like any other asset would. For example if you sold
+2 bitcoin for £12,000, then put `btc` as the sell asset, `gbp` as the buy asset,
+`2` as the sell amount and `12000` as the buy amount.
+
+Asset names should be in the same format as in the price CSV filenames.
+
+Trades should be provided with the following columns:
+
+| Column      | Description                                                               |
+| ----------- | ------------------------------------------------------------------------- |
+| DATE        | The date of the trade, acquistion and/or disposal formatted as YYYY-MM-DD |
+| SELL ASSET  | The asset being sold/sent/disposed, or empty if none                      |
+| BUY ASSET   | The asset being bought/received/acquired or empty if none                 |
+| SELL AMOUNT | The amount of the SELL ASSET being disposed or empty if none              |
+| BUY ASSET   | The amount of the BUY ASSET being acquired or empty if none               |
+
+## Running Calculations
+
+Please run `pycryptax -h` for usage details.
+
+When running a calculation you must either be in the directory containing the
+`prices`, `income` and/or `gains` directories, or provide it using the `--dir`
+option.
+
+Calcuations are done for a particular period of time. The start and end dates
+need to be provided in the `YYYY-MM-DD` format. For example, to calculate income
+for the 2009-2010 tax year in the `./examples` directory:
+
+    pycryptax income 2009-04-06 2010-04-05 -d ./examples
+
+The following actions are allowed:
+
+- **income:** Produces the revenue and expenditure for each asset and in
+  total.
+- **gain:** Produces the gain and loss for each asset and in total. Also
+  displays the status of the section 104 holding at the end of the
+calculation period.
+- **txs:** Outputs in CSV format each income tax transaction with revenue and
+  expenditure calculations shown in the reporting asset (GBP by default).
+- **disposals:** Outputs in CSV format each disposal, including the
+  calculated costs and proceeds which HMRC may ask for.
+
+If you do not want to report calculations in GBP or have named GBP something
+other than `gbp`, then the `--reportingcurrency` option can be used to specify a
+different asset.
+

examples/README.md

@@ -0,0 +1,97 @@
+# Calculation Examples
+
+The capital gains example is included with the `./gains/exampleTrades.csv` file,
+and the income example is included with the `./income/exampleIncome.csv` file.
+Multiple CSV files can be given in the `./gains/` and `./income/` directories.
+Prices are found within `./prices` for the example `foo` and `bar` assets.
+
+The income for the 2009 to 2010 (Apr 6 to Apr 5) tax year should equate to a
+profit of 55. The 2010 to 2011 tax year should equate to a loss of 22.5.
+
+## Capital Gains Calculation Walkthrough
+
+On the 1st of January 2010, a total of 800 foo coins are purchased for a total
+of £1,600 with the following transactions:
+
+1. 200 for £550
+2. 400 for £750
+3. 200 at a market price of £1.5
+
+The transactions are considered as one, ie. 800 coins for £1,600 @ £2.
+
+On the same day, a disposal is made of 300 coins for £700. This presents a gain
+of £100.  The remaining 500 coins for £1,000 are added to a section 104 holding.
+
+On the 1st of February 150 coins are purchased for £450 at £3.  On the 1st of
+February 50 coins are disposed for £200 at £4.  On the 2nd of January 300 coins
+are disposed for £450 at £1.5
+
+Firstly the disposal on the 1st of Feb is matched against the acquisition. A
+gain of £50 is made on 50 coins, leaving 100 coins purchased at £3. Next the
+disposal on the 2nd of Jan is matched to the acquisition on the 1st of Feb due
+to it being within 30 days afterwards. This matches 100 coins at a cost of £3,
+sold at £1.5, leaving a loss of £150, and 200 coins remaining. These 200 coins
+are matched against the section 104 holding at a cost of £2, leaving a loss of
+£100. The holding is reduced to 300 coins for £600.
+
+On the 2nd of February a total of 300 coins are purchased for £1200 at £4.
+
+The section 104 holding is increased to 600 coins for £1,800. This is outside
+the 30 day period of the disposal made in January, so it does not get matched.
+
+On the 1st of April 300 coins are disposed for £1,200 at £4.  On the 1st of
+April 100 coins are purchased for £300 at £3.  On the 1st of May 600 coins are
+purchased for £3,000 at £5.  On the 1st of May 200 coins are disposed for £1,200
+at £6.
+
+Firstly 100 coins disposed in April are matched against the coins purchased on
+the same day, at a £100 gain. The 200 coins disposed in May are matched against
+the same-day purchase for a £200 gain. The remaining 200 coins disposed in April
+are matched against the remaining 400 purchased in May, leaving a loss of £200.
+Of the coins purchased in May, 200 are added to the holding with £1,000. The new
+holding equals 800 coins and £2,800.
+
+On the 1st of July 250 coins are disposed for £2,500 at £10.  On the 1st of July
+50 coins are purchased for £600 at £12.  On the 2nd of July 200 coins are
+purchased for £800 at £4.  On the 2nd of July 100 coins are disposed for £1,100
+at £11.  On the 3rd of July 300 coins are purchased for £1,800 at £6.
+
+The disposal is matched against all three acquisitions but the same-day disposal
+on the 2nd must be matched first, and the most recent purchases are matched
+first.
+
+1. The disposal on the 2nd is matched to 100 coins on the same day, leaving a
+   gain of £700 and 100 purchased coins remaining on the 2nd.
+2. The 50 coins purchased on the 1st is matched to the coins disposed on that
+   day, leaving a £100 loss, and a £200 disposal remaining.
+3. The remaining 100 coins from the 2nd are matched to the remaining 200 on the
+   1st for a £600 gain, leaving 100 coins from the 1st.
+4. The remaining 100 coins is matched to the 300 coins on the 3rd for a gain of
+   £400.
+5. This leaves 200 remaining on the 3rd, increasing the holding to 1,000 coins
+   and £4,000.
+
+On the 1st of September 100 coins are disposed for £1,000 at £10 On the 2nd of
+September 300 coins are disposed for £1,800 at £6 On the 3rd of September 50
+coins are purchased for £200 at £4 On the 4th of September 150 coins are
+purchased for £300 at £2
+
+The acquisitions are matched against the earlier disposal on the 1st. 50 from
+the 3rd are matched at £4 for a £300 gain. 50 from the 4th are matched for a
+gain of £400. Then the remaining 100 from the 4th is matched to the disposal on
+the 2nd, for a gain of £400. The remaining 200 on the 2nd are matched against
+the holding at a cost of £4, leaving a gain of £400. The holding is reduced to
+800 coins and £3,200.
+
+300 coins are sold on the 5th of September for £1,000, making a loss of £200.
+This is done in three transactions:
+
+1. 100 coins for £300
+2. 150 coins for £500
+3. 50 coins at a market price of £4
+
+The final holding is at 500 coins and £2,000.
+
+The total gain throughout 2010 is £2,900. However, in the UK the tax year starts
+on the 6th of April. The 09/10 tax year would have a loss of £200 and the 10/11
+tax year would have a gain of £3,100.

examples/gains/exampleTrades.csv

@@ -0,0 +1,32 @@
+DATE,SELL ASSET,SELL AMOUNT,BUY ASSET,BUY AMOUNT,EXP GAIN
+,,,,,
+2010-01-01,gbp,550,foo,200,
+2010-01-01,gbp,750,foo,400,
+2010-01-01,,,foo,200,
+2010-01-01,foo,300,gbp,700,100
+,,,,,
+2010-01-02,foo,300,gbp,450,-250
+2010-02-01,gbp,450,foo,150,
+2010-02-01,foo,50,gbp,200,50
+,,,,,
+2010-02-02,gbp,1200,foo,300,
+,,,,,
+2010-04-01,foo,300,gbp,1200,-100
+2010-04-01,gbp,300,foo,100,
+2010-05-01,gbp,3000,foo,600,
+2010-05-01,foo,200,gbp,1200,200
+,,,,,
+2010-07-01,foo,250,gbp,2500,900
+2010-07-01,gbp,600,foo,50,
+2010-07-02,gbp,800,foo,200,
+2010-07-02,foo,100,gbp,1100,700
+2010-07-03,gbp,1800,foo,300,
+,,,,,
+2010-09-01,foo,100,gbp,1000,700
+2010-09-02,foo,300,gbp,1800,800
+2010-09-03,gbp,200,foo,50,
+2010-09-04,gbp,300,foo,150,
+,,,,,
+2010-09-05,foo,100,gbp,300,-200
+2010-09-05,foo,150,gbp,500,
+2010-09-05,foo,50,,,

examples/income/exampleIncome.csv

@@ -0,0 +1,8 @@
+DATE,ASSET,AMOUNT,NOTE
+2010-01-01,foo,100,100*1.5 = +150
+2010-02-01,bar,2,2*10 = +20
+2010-02-02,bar,-5,-5*20 = -100
+2010-04-05,foo,-10,-10*1.5 = -15
+2010-05-06,bar,0.5,0.5*20 = +10
+2010-08-31,foo,5,5*1.5 = +7.5
+2010-09-01,foo,-10,-10*4 = -40

examples/prices/bar_gbp.csv

@@ -0,0 +1,3 @@
+DATE,PRICE
+2010-01-01,10
+2010-02-02,20

examples/prices/foo_gbp.csv

@@ -0,0 +1,3 @@
+DATE,PRICE
+2010-01-01,1.5
+2010-09-01,4