Aerarium: Managing Your Finances

• Python 3.6

• A database: in theory, any database supported by SQLAlchemy will work. However, due to restricted capabilities of upgrading existing tables, SQLite is not supported; upgrading Aerarium might fail when using SQLite.

  Depending on your database, you might need to install additional SQL drivers. For additional information, see the documentation of SQLAlchemy. For MySQL, the PyMySQL driver is included in the requirements.

TODO

Aerarium allows configuration in two ways: you can either use environment variables or use a .env file in the instance folder. All configuration options are explained in the included example file instance/example.env. To use your own settings, simply rename this file to .env. All the options can also directly be used as environment variables instead.

Your contribution is greatly appreciated!

If you have ideas for new features or want to report a bug you can create a new issue on GitHub.

Do you want to see Aerarium in your language, but you don't know how to or don't want to set up an entire development environment? In this case, you can create a new issue on GitHub. Please include the language you want to translate into, the country if you want to translate into a country-specific dialect (e.g. Brazilian Portuguese), and the name under which you want to appear in the list of translators. Also, shortly explain why you are suited to translate into that language. I will then send you a translation file in the Gettext format. You can edit this file either in a text editor or a special editor (for example, the free Poedit that is available for all major systems). Once you are done with your translation, send the file back to me. I will then add it to the project.

If you do not want to wait for me to implement your requests you can implement those changes yourself and submit a pull request.

Ensure your system fulfills the requirements. Additionally, you will also need pipenv for Python 3.6. Then execute the following commands in your terminal (on Unix systems; assuming your executable for Python in the required version is called python3) to set up your development environment:

git clone https://github.com/BMeu/Aerarium.git
cd Aerarium
pipenv install --dev
pipenv shell
export FLASK_APP=aerarium.py

Now, set up your configuration. Once you have done that, finish the setup by preparing the database and compiling the translations:

flask db upgrade
flask translate compile

You can run a local test server on your PC to directly test your changes:

export DEBUG=1
flask run

All flask commands require that the environment variable FLASK_APP is set to aerarium.py.

If you want to add a new language run:

flask translate init LANGUAGE

In order to update translations with newly added texts run:

flask translate update

If you changed a translation you can compile the changes with the following command:

flask translate compile

If you add a new language do not forget to add yourself to the list of translators below.

When you submit a pull request, please ensure that your changes fulfill the following points:

• No linter errors:

  flake8

• Functions, methods and class members specify full type hints (except for cls and self).

• All packages, modules, classes, methods, functions, members, etc. are fully documented.

• The documentation builds without errors:

  sphinx-apidoc -o docs/source/api app app/configuration
  sphinx-build -b html docs/source docs/build

• All tests pass:

  python -m unittest discover -v -s tests -p "*_test.py" -t .

• All functions and methods have a unit test, no matter how trivial the code may seem (one unit test per scenario).

• The tests reach a code coverage of 100% (exceptions may be discussed individually):

  coverage run -m unittest discover -v -s tests -p "*_test.py" -t .
  coverage report

• Imports are structured in four blocks in the following order, with a blank line separating each block:

  1. Type imports, e.g. from typing import Optional
  2. System libraries, e.g. from threading import Thread
  3. Third-party libraries, e.g. from flask import render_template
  4. Project modules, e.g. from app.authorization import User

• Each import is on its own line, ordered alphabetically, e.g.

  from flask import render_template
  from flask import url_for
  from flask_login import login_user

  but not

  from flask_login import login_user
  from flask import url_for, render_template

  This makes it easier to find imports and spot changes in commits.

• All texts that are displayed to the user must be localizable. If you added, changed, or deleted some of those texts put a note in the pull request, so the translators can be informed, and update the translation files:

  flask translate update

Aerarium is developed by Bastian Meyer <bastian@bastianmeyer.eu> and is licensed under the MIT License. For details, see the attached LICENSE file.