This repository helps you quickly set up and use your own OpenFisca country package.
You should NOT fork it but follow the set up instructions below.
Otherwise, you will have to clean up all tags when you deploy your own country package.
This set of instructions only needs to be followed once and will create your own copy of this boilerplate directory, customising it to the country you want to work on. You will need to have Git installed.
Click on the “Use this template” dropdown and select “Create a new repository”.
Set the repository name to openfisca-<your_country_name>
; use underscore _
as separator if there are spaces in the country name. For example, openfisca-new_zealand
or openfisca-france
.
After being redirected to your newly created repository, please allow a few minutes for the automatic setup to be executed. Once done, the title of the README file should be updated to OpenFisca <your_country_name>
.
If the automatic setup does not start within a few minutes, you can initiate it manually:
- Navigate to the “Actions” tab.
- Select the “First time setup” workflow.
- Click on “Run workflow” to start the setup process manually.
Download a copy of this repository, unzip it and cd
into it in a Terminal window.
Create a new repository on your favourite git host (Bitbucket, GitLab, …) with the name openfisca-<your_country_name>
. For example, openfisca-new_zealand
or openfisca-france
.
Execute the first-time-setup.sh
script to initialise the git repository. This performs numerous tasks including replacing all references to openfisca-country_template
with references to the new country package.
bash first-time-setup.sh
from the command linefirst-time-setup.sh
has run both it and these instructions are removed.Follow the instructions in the new repository's README.md.
The country whose law is modelled here has a very simple tax and benefit system.
These elements are described in different folders. All the modelling happens within the openfisca_country_template
folder.
parameters
folder.variables
folder.reforms
folder. This is optional: your country may exist without defining any reform.
40 %
for people earning more than 40000
. This reform project would apply starting from 2017-01-01
.The files that are outside from the openfisca_country_template
folder are used to set up the development environment.
Country packages are Python distributions. You can choose to distribute your package automatically via the predefined continuous deployment system on GitHub Actions, or manually.
This repository is configured with a continuous deployment system to automate the distribution of your package via pip
.
To activate the continuous deployment:
PYPI_TOKEN
.Once set up, changes to the main
branch will trigger an automated workflow to build and publish your package to PyPI, making it available for pip
installation.
If you prefer to manually manage the release and distribution of your package, follow the guidelines provided by the Python Packaging Authority.
This involves detailed steps on preparing your package, creating distribution files, and uploading them to PyPI.
This package requires Python 3.9. More recent versions should work, but are not tested.
All platforms that can execute Python are supported, which includes GNU/Linux, macOS and Microsoft Windows.
In order to limit dependencies conflicts, we recommend using a virtual environment with venv.
To create a virtual environment, launch a terminal on your computer, cd
into your directory and follow these instructions:
python3 -m venv .venv # create a new virtual environment in the “.venv” folder, which will contain all dependencies
source .venv/bin/activate # activate the venv
You can now operate in the venv you just created.
You can deactivate that venv at any time with deactivate
.
:tada: You are now ready to install this OpenFisca Country Package!
Two install procedures are available. Pick procedure A or B below depending on how you plan to use this Country Package.
Follow this installation if you wish to:
For more advanced uses, head to the Advanced Installation.
Inside your venv, check the prerequisites:
python --version # should print "Python 3.9.xx".
pip --version # should print at least 9.0.
# if not, run "pip install --upgrade pip"
Install the Country Package:
pip install openfisca-country_template
:warning: Please beware that installing the Country Package with pip
is dependent on its maintainers publishing said package.
:tada: This OpenFisca Country Package is now installed and ready!
Depending on what you want to do with OpenFisca, you may want to install yet other packages in your venv:
Follow this tutorial if you wish to:
First, make sure Git is installed on your machine.
Set your working directory to the location where you want this OpenFisca Country Package cloned.
Inside your venv, check the prerequisites:
python --version # should print "Python 3.9.xx".
Clone this Country Package on your machine:
git clone https://example.com/repository.git
cd repository_folder
pip install --upgrade pip build twine
pip install --editable .[dev] --upgrade
You can make sure that everything is working by running the provided tests with make test
.
:tada: This OpenFisca Country Package is now installed and ready!
If you are considering building a web application, you can use the packaged OpenFisca Web API with your Country Package.
To serve the Openfisca Web API locally, run:
openfisca serve --port 5000 --country-package openfisca_country_template
Or use the quick-start Make command:
make serve-local
To read more about the openfisca serve
command, check out its documentation.
You can make sure that your instance of the API is working by requesting:
curl "http://localhost:5000/spec"
This endpoint returns the Open API specification of your API.
:tada: This OpenFisca Country Package is now served by the OpenFisca Web API! To learn more, go to the OpenFisca Web API documentation.
You can test your new Web API by sending it example JSON data located in the situation_examples
folder.
curl -X POST -H "Content-Type: application/json" \
-d @./openfisca_country_template/situation_examples/couple.json \
http://localhost:5000/calculate