-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Add basic documentation and testing (#3)
- Minimal testing for the base functions - Basic documentation on how to use the package - Some bug fixes to make the client ids more consistent Co-authored-by: Brunno Vanelli <[email protected]>
- Loading branch information
Showing
9 changed files
with
267 additions
and
38 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,89 @@ | ||
# actualpy | ||
Python API implementation for Actual server - reference https://actualbudget.org/ | ||
|
||
Python API implementation for Actual server. | ||
|
||
[Actual Budget](https://actualbudget.org/) is a super fast and privacy-focused app for managing your finances. | ||
|
||
> **WARNING:** The [Javascript API](https://actualbudget.org/docs/api/) to interact with Actual server already exists, | ||
> and is battle-tested as it is the core of the Actual frontend libraries. If you intend to use a reliable and well | ||
> tested library, that is the way to go. | ||
# Installation | ||
|
||
Install it via Pip using the repository url: | ||
|
||
```bash | ||
pip install https://github.com/bvanelli/actualpy | ||
``` | ||
|
||
# Basic usage | ||
|
||
The most common usage would be downloading a budget to more easily build queries. This would you could handle the | ||
Actual database using SQLAlchemy instead of having to retrieve the data via the export. The following script will print | ||
every single transaction registered on the Actual budget file: | ||
|
||
```python | ||
from actual import Actual | ||
|
||
with Actual( | ||
base_url="http://localhost:5006", # Url of the Actual Server | ||
password="<your_password>", # Password for authentication | ||
file="<file_id_or_name>", # Set the file to work with. Can be either the file id or file name, if name is unique | ||
data_dir="<path_to_data_directory>" # Optional: Directory to store downloaded files. Will use a temporary if not provided | ||
) as actual: | ||
transactions = actual.get_transactions() | ||
for t in transactions: | ||
account_name = t.account.name if t.account else None | ||
category = t.category.name if t.category else None | ||
print(t.date, account_name, t.notes, t.amount, category) | ||
``` | ||
|
||
# Experimental features | ||
|
||
> **WARNING:** Experimental features do not have all the testing necessary to ensure correctness in comparison to the | ||
> files generated by the Javascript API. This means that this operations could in theory corrupt the data. Make sure | ||
> you have backups of your data before trying any of those operations. | ||
## Bootstraping a new server and uploading a first file | ||
|
||
The following script would generate a new empty budget on the Actual server, even if the server was not bootstrapped | ||
with an initial password. | ||
|
||
```python | ||
from actual import Actual | ||
|
||
with Actual(base_url="http://localhost:5006", password="mypass", bootstrap=True) as actual: | ||
actual.create_budget("My budget") | ||
actual.upload_budget() | ||
``` | ||
|
||
You will then have a freshly created new budget to use: | ||
|
||
![created-budget](./docs/static/new-budget.png) | ||
|
||
# Adding new transactions | ||
|
||
After you created your first budget (or when updating an existing budget), you can add new transactions by adding them | ||
using the `actual.add()` method. You cannot use the SQLAlchemy session directly because that adds the entries to your | ||
local database, but will not sync the results back to the server (that is only possible when reuploading the file). | ||
|
||
The method will make sure the local database is updated, but will also send a SYNC request with the added data so that | ||
it will be immediately available on the frontend: | ||
|
||
```python | ||
import decimal | ||
import datetime | ||
from actual import Actual | ||
from actual.database import Transactions | ||
|
||
with Actual(base_url="http://localhost:5006", password="mypass", file="My budget") as actual: | ||
act = actual.get_accounts()[0] # get first account | ||
t = Transactions.new(act.id, decimal.Decimal(10.5), datetime.date.today(), notes="My first transaction") | ||
actual.add(t) | ||
``` | ||
|
||
![added-transaction](./docs/static/added-transaction.png) | ||
|
||
# Contributing | ||
|
||
The goal is to have more features implemented and tested on the Actual API. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.