Merge pull request #3 from dnbasta/dev

Dev

.gitignore

@@ -2,7 +2,7 @@
 .idea
 .DS_Store
 env*/
-config.yaml
+*.yaml
 dist/
 live.py
 .pytest_cache/

README.md

@@ -2,6 +2,7 @@
 
 [![GitHub Release](https://img.shields.io/github/release/dnbasta/ynab-split-budget?style=flat)]() 
 [![Github Release](https://img.shields.io/maintenance/yes/2100)]()
+[![Monthly downloads](https://img.shields.io/pypi/dm/ynab-split-budget)]()
 
 This library enables cost sharing across two YNAB budgets. It requires two dedicated accounts in each budget to which
 each budget owner can transfer amounts from their own budget. Each transfer is considered as its opposite in the other 
@@ -18,99 +19,84 @@ account.
 ```bash
 pip install ynab-split-budget
 ```
+## Usage
+### 1. Create a transaction
+Create a transaction in the budget and add a specific flag in a specific color to be used for the splits. The 
+transaction needs to be cleared in order to be considered by this library. By default, the transaction will be split 
+in half, but you can specify a different split by adding `@x%` for percentage or `@x` for specific amount in the memo 
+of the transaction. The amount you specify in this split will be transferred to your sharing account. You can also 
+create a plain transfer to the shared account which will be completely allocated to the partner account.
 
-## Create config
-Create a config `dict` with the below structure. 
-```py
-CONFIG = {
-    '<user_name>': {
-        'budget': '<budget_id>',
-        'account': '<account_id>',
-        'token': '<ynab_token>',
-        'flag': '<color>'},
-    '<partner_name>': {
-        'budget': '<budget_id>',
-        'account': '<account_id>',
-        'token': '<ynab_token>',
-        'flag': '<color>'}
-}
-```
+### 2. Initialize library
 You can find the ID of the budget and of the account if you go to https://app.ynab.com/ and open the target account by
 clicking on the name on the left hand side menu. The URL does now contain both IDs 
 `https://app.ynab.com/<budget_id>/accounts/<account_id>`
 Possible colors for the flag value are `red`, `orange`, `yellow`, `green`, `blue` and `purple`
+```py
+from ynabsplitbudget import YnabSplitBudget, User
 
-Alternatively you can save the config in a yaml file with the below structure and provide the path to the library 
-when initializing
-```yaml
-<user_name>:
-  token: <ynab_token>
-  budget: <budget_id>
-  account: <account_id>
-  flag: <color>
-<partner_name>:
-  token: <ynab_token>
-  budget: <budget_id>
-  account: <account_id>
-  flag: <color>
-```
+user = User(name='<name>', token='<token>', budget_id='<budget_id>', 
+            account_id='<account_id', flag_color='<flag_color>')
 
-## Usage
-### 1. Create a transaction
-Create a transaction in your budget and add the defined color flag. Only cleared transactions will be considered. 
-By default, the transaction will be split in half, but you can specify a different split by adding `@x%` for 
-percentage or `@x` for specific amount in the memo of the transaction. The amount you specify in this split will be 
-transferred to your sharing account. You can also create a plain transfer to the shared account which will be 
-completely allocated to the partner account.
-### 2. Initialize and run the split functionality
+partner = User(name='<name>', token='<token>', budget_id='<budget_id>', 
+               account_id='<account_id', flag_color='<flag_color>')
 
+split_budget = YnabSplitBudget(user=user, partner=partner)
+```
+### 3. Split transactions
+Call the `split()` method of the instance. It will split flagged transactions in the budget into a subtransaction with
+the original category and a transfer to the split account. By default, the transfer transactions will show up as 
+uncleared in the split account. The optional `clear` parameter allows to automatically clear the transactions in 
+the split account. The function returns the updated transactions after applying the split.
 ```py
-from ynabsplitbudget import YnabSplitBudget
+split_budget.split()
+```
 
-# initialize from config dict
-ynab_split_budget = YnabSplitBudget(config=CONFIG, user='<user_name>')
-# or alternatively from yaml
-ynab_split_budget = YnabSplitBudget.from_yaml(path='path/to/config.yaml', user='<user_name')
+### 4. Push new splits to partner split account
+Calling the `push()` function will insert new transactions from user split account into split account of partner to keep
+both accounts in sync. By default, the function will compare and insert transactions of the last 30 days. Optionally it 
+takes a `since` parameter in the form of `datetime.date` to set a timeframe different from 30 days. 
 
-ynab_split_budget.split_transactions()
-```
-### 3. Clear the newly split transaction
-Using the YNAB web interface go to your split account and clear the newly split transaction over there. This can 
-currently not be automated as YNAB API can't clear split transactions at this point in time.
-### 4. Run the insert functionality
-By default the library will compare and insert transactions of the last 30 days. If you would like to do it for a 
-different timeframe you can provide a `since` argument to the function with a value from `datetime.date`
 ```py
-ynab_split_budget.insert_complements()
+split_budget.push()
 ```
 ## Advanced Usage
 ### Check Balances
-Additionally you can check if the cleared balances in both accounts match. If they don't match you will get back a 
-`BalancesDontMatch` Error which also gives you the two values of the balances.
+The `raise_on_balances_off()` function compares the cleared balances in both split accounts. If they don't match it 
+will raise a `BalancesDontMatch` error which includes the values of the balances.
 ```py
-ynab_split_budget.raise_on_balances_off()
+split_budget.raise_on_balances_off()
 ```
 ### Delete Orphaned Complements
-If you delete a transaction in your share account you can use this function to delete the respective complement on 
-your partners shared account. It does return a list with the deleted transactions. By default the library will 
-compare transactions of the last 30 days. If you would like to do it for a different timeframe you can provide a 
-`since` argument to the function with a value from `datetime.date`
+The `delete_orphans()` function deletes orphaned transactions in the partner split account, which don't have a 
+corresponding transaction in the user split account any more. It does return a list with the deleted transactions. 
+By default, the function compares transactions of the last 30 days. Optionally it takes a `since` parameter in the 
+form of `datetime.date` to set a timeframe different from 30 days.
 ```py
-ynab_split_budget.delete_orphaned_complements()
+split_budget.delete_orphans()
+```
+### Reconcile split account
+The `reconcile()` function allows to reconcile the split account. It does check if the balances match before reconciling
+and will an `BalancesDontMatch` error if they don't.
+```py 
+split_budget.reconcile()
 ```
+
 ### Show Logs
-The library logs information about the result of the methods on the 'INFO' level. If you want to see these logs 
-import the logging module and set it to the level `INFO`. You can also access the logger for advanced configuration 
-via the `logger` attribute of your `YnabSplitBudget`instance.
+The library logs information about the result of the methods at the 'INFO' level. The logs can be made visible by 
+importing the logging module and set it to the level `INFO`. The logger itself can also be accessed via the `logger` 
+attribute of the instance.
 ```py
 import logging
 
 logging.basicConfig(level='INFO')
 ```
-### Run via bash commands
-You can run this package also from bash with the following commands
+### Run via bash
+You can run this library also from bash with the following basic structure
+```bash
+$ python -m ynabsplitbudget -u <path/user.yaml> -p <path/partner.yaml> --split
+```
+For a complete list of available bash options please use
 ```bash
-$ python -m ynabsplitbudget -c <path/config.yaml#user_name> -s | --split-transactions
-$ python -m ynabsplitbudget -c <path/config.yaml#user_name> -i | --insert-complements [-d | --since-date "YYYY-mm-dd"]
-$ python -m ynabsplitbudget -c <path/config.yaml#user_name> -b | --check-balances
+$ python -m ynabsplitbudget -h | -- help
 ```