This package contains the core features of OpenFisca, which are meant to be used by country packages such as OpenFisca-France. Bootstrapping your own country package should not take more than 5 minutes: check our country package template.
OpenFisca runs on Python 3.7. More recent versions should work, but are not tested.
Backward compatibility with Python 2.7 is maintained for now, but will be dropped from January 1st, 2019.
If you're developping your own country package, you don't need to explicitly install OpenFisca-Core. It just needs to appear in your package dependencies.
If you want to contribute to OpenFisca-Core itself, welcome! To install it locally in development mode:
git clone https://github.com/openfisca/openfisca-core.git cd openfisca-core pip install --editable .[dev]
To run the entire test suite:
To run all the tests defined on a test file:
To run a single test:
This repository adheres to a certain coding style, and we invite you to follow it for your contributions to be integrated promptly.
Style checking is already run with
make test. To run the style checker alone:
To automatically style-format your code changes:
To automatically style-format your code changes each time you commit:
touch .git/hooks/pre-commit chmod +x .git/hooks/pre-commit tee -a .git/hooks/pre-commit << END #!/bin/sh # # Automatically format your code before committing. exec make format-style END
Serving the API
OpenFisca-Core provides a Web-API. It is by default served on the
To run it with the mock country package
openfisca_country_template and another port value such as
openfisca serve --country-package openfisca_country_template --port 2000
To read more about the
openfisca serve command, check out its documentation.
By default, the Web API uses 3 workers to avoid this issue. Without it, AJAX requests from Chrome sometimes take more than 20s to process. You can change the number of workers by specifying a
--workers k option.
You can test that the API is running by executing the command:
For more information about endpoints and input formatting, see the official documentation.
The OpenFisca Web API comes with an optional tracker which allows you to measure the usage of the API.
The tracker is not installed by default. To install it, run:
pip install openfisca_core[tracker] # Or `pip install --editable ".[tracker]"` for an editable installation
The tracker is activated when these two options are set:
--tracker-url: An URL ending with
piwik.php. It defines the Piwik instance that will receive the tracking information. To use the main OpenFisca Piwik instance, use
--tracker-idsite: An integer. It defines the identifier of the tracked site on your Piwik instance. To use the main OpenFisca piwik instance, use
--tracker-token: A string. It defines the Piwik API Authentification token to differentiate API calls based on the user IP. Otherwise, all API calls will seem to come from your server. The Piwik API Authentification token can be found in your Piwik interface, when you are logged.
For instance, to run the Web API with the mock country package
openfisca_country_template and the tracker activated, run:
openfisca serve --country-package openfisca_country_template --port 5000 --tracker-url https://stats.data.gouv.fr/piwik.php --tracker-idsite 4 --tracker-token $TRACKER_TOKEN