# OpenFisca Country-Template
This repository helps you quickly bootstrap and use your own OpenFisca country package.
**You should NOT fork it but [download a copy](https://github.com/openfisca/country-template/archive/master.zip) of it** and follow the bootstrapping instructions below.
> Otherwise, you will have to clean up all tags when you deploy your own country package.
## Bootstrapping your Country Package
This set of instructions will create your own copy of this boilerplate directory and customise it to the country you want to work on. You will need to have [Git](https://git-scm.com) installed.
1. [Download a copy](https://github.com/openfisca/country-template/archive/master.zip) of this repository, unzip it and `cd` into it in a Terminal window.
2. Create a new repository on your favourite git host (Github, Bitbucket, GitLab, etc) with the name openfisca-your_country_name. For example, `openfisca-france`.
3. Set up the two following variables and execute the `bootstrap.sh` script to initialise the git repository and replace all references to `openfisca_country_template` with references to your new country package in the code base:
```sh
export COUNTRY_NAME=France # set the name of your country here; you should keep all capitals, and replace any spaces in the name by underscores
export REPOSITORY_URL=https://github.com/YOUR_ORGANISATION/OpenFisca-$COUNTRY_NAME # set here the URL of the repository you created in step 2.
./bootstrap.sh
```
4. Push your changes to your git host:
```sh
git push origin master
```
That's it, you're all set!
## Writing the Legislation
The country whose law is modelled here has a very simple tax and benefit system.
- It has a flat rate tax whose rates increase every year.
- On the first of December, 2015, it introduced a basic income for all its citizens of age who have no income.
- On the first of December, 2016, it removed the income condition, providing all its adult citizens with a basic income.
These elements are described in different folders. All the modelling happens within the `openfisca_country_template` folder.
- The rates are in the `parameters` folder.
- The formulas are in the `variables` folder.
- This country package comes also with *reforms* in the `reforms` folder. This is optional: your country may exist without defining any reform.
- In this country, there is [a reform project](./openfisca_country_template/reforms/modify_social_security_taxation.py) aiming to modify the social security taxation, deleting the first bracket, raising the intermediary ones and adding a new bracket with a higher tax rate of `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.
## Packaging your Country Package for Distribution
Country packages are python distributions. To distribute your package via `pip`, follow the steps given by the [Python Packaging Authority](https://python-packaging-user-guide.readthedocs.io/tutorials/distributing-packages/#packaging-your-project).
## Install Instructions for Users and Contributors
This package requires [Python 3.9](https://www.python.org/downloads/release/python-390/). 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.
### Setting-up a Virtual Environment with venv
In order to limit dependencies conflicts, we recommend using a [virtual environment](https://www.python.org/dev/peps/pep-0405/) with [venv](https://docs.python.org/3/library/venv.html).
- A [venv](https://docs.python.org/3/library/venv.html) is a project specific environment created to suit the needs of the project you are working on.
To create a virtual environment, launch a terminal on your computer, `cd` into your directory and follow these instructions:
```sh
python3 -m venv openfisca # create a new venv called “openfisca”
source openfisca/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.
### A. Minimal Installation (Pip Install)
Follow this installation if you wish to:
- run calculations on a large population;
- create tax & benefits simulations;
- write an extension to this legislation (e.g. city specific tax & benefits);
- serve your Country Package with the OpenFisca Web API.
For more advanced uses, head to the [Advanced Installation](#advanced-installation-git-clone).
#### Install this Country Package with Pip Install
Inside your venv, check the prerequisites:
```sh
python --version # should print "Python 3.9.xx".
```
```sh
pip --version # should print at least 9.0.
# if not, run "pip install --upgrade pip"
```
Install the Country Package:
```sh
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!
#### Next Steps
- To learn how to use OpenFisca, follow our [tutorials](https://openfisca.org/doc/).
- To serve this Country Package, serve the [OpenFisca web API](#serve-your-country-package-with-the-openFisca-web-api).
Depending on what you want to do with OpenFisca, you may want to install yet other packages in your venv:
- To install extensions or write on top of this Country Package, head to the [Extensions documentation](https://openfisca.org/doc/contribute/extensions.html).
- To plot simulation results, try [matplotlib](http://matplotlib.org/).
- To manage data, check out [pandas](http://pandas.pydata.org/).
### B. Advanced Installation (Git Clone)
Follow this tutorial if you wish to:
- create or change this Country Package's legislation;
- contribute to the source code.
#### Clone this Country Package with Git
First, make sure [Git](https://www.git-scm.com/) 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:
```sh
python --version # should print "Python 3.9.xx".
```
```sh
pip --version # should print at least 9.0.
# if not, run "pip install --upgrade pip"
```
Clone this Country Package on your machine:
```sh
git clone https://github.com/openfisca/openfisca-country-template.git
cd openfisca-country-template
pip install --editable .[dev]
```
You can make sure that everything is working by running the provided tests with `make test`.
> [Learn more about tests](https://openfisca.org/doc/coding-the-legislation/writing_yaml_tests.html)
:tada: This OpenFisca Country Package is now installed and ready!
#### Next Steps
- To write new legislation, read the [Coding the legislation](https://openfisca.org/doc/coding-the-legislation/index.html) section to know how to write legislation.
- To contribute to the code, read our [Contribution Guidebook](https://openfisca.org/doc/contribute/index.html).
## Serve this Country Package with the OpenFisca Web API
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:
```sh
openfisca serve --port 5000
```
Or use the quick-start Make command:
```
make serve-local
```
To read more about the `openfisca serve` command, check out its [documentation](https://openfisca.org/doc/openfisca-python-api/openfisca_serve.html).
You can make sure that your instance of the API is working by requesting:
```sh
curl "http://localhost:5000/spec"
```
This endpoint returns the [Open API specification](https://www.openapis.org/) 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](https://openfisca.org/doc/openfisca-web-api/index.html).
You can test your new Web API by sending it example JSON data located in the `situation_examples` folder.
Substitute your package's country name for `openfisca_country_template` below:
```sh
curl -X POST -H "Content-Type: application/json" \
-d @./openfisca_country_template/situation_examples/couple.json \
http://localhost:5000/calculate
```
Raw data
{
"_id": null,
"home_page": "https://github.com/openfisca/country-template",
"name": "OpenFisca-Country-Template",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "benefit microsimulation social tax",
"author": "OpenFisca Team",
"author_email": "contact@openfisca.org",
"download_url": "https://files.pythonhosted.org/packages/c9/94/b50ebb8e33780fcffedc796353688adde56732294c82db7bbcae033ecb15/OpenFisca-Country-Template-6.0.3.tar.gz",
"platform": null,
"description": "# OpenFisca Country-Template\n\nThis repository helps you quickly bootstrap and use your own OpenFisca country package.\n\n**You should NOT fork it but [download a copy](https://github.com/openfisca/country-template/archive/master.zip) of it** and follow the bootstrapping instructions below.\n\n> Otherwise, you will have to clean up all tags when you deploy your own country package.\n\n\n## Bootstrapping your Country Package\n\nThis set of instructions will create your own copy of this boilerplate directory and customise it to the country you want to work on. You will need to have [Git](https://git-scm.com) installed.\n\n1. [Download a copy](https://github.com/openfisca/country-template/archive/master.zip) of this repository, unzip it and `cd` into it in a Terminal window.\n\n2. Create a new repository on your favourite git host (Github, Bitbucket, GitLab, etc) with the name openfisca-your_country_name. For example, `openfisca-france`.\n\n3. Set up the two following variables and execute the `bootstrap.sh` script to initialise the git repository and replace all references to `openfisca_country_template` with references to your new country package in the code base:\n\n```sh\nexport COUNTRY_NAME=France # set the name of your country here; you should keep all capitals, and replace any spaces in the name by underscores\nexport REPOSITORY_URL=https://github.com/YOUR_ORGANISATION/OpenFisca-$COUNTRY_NAME # set here the URL of the repository you created in step 2.\n./bootstrap.sh\n```\n\n4. Push your changes to your git host:\n\n```sh\ngit push origin master\n```\n\nThat's it, you're all set!\n\n## Writing the Legislation\n\nThe country whose law is modelled here has a very simple tax and benefit system.\n\n- It has a flat rate tax whose rates increase every year.\n- On the first of December, 2015, it introduced a basic income for all its citizens of age who have no income.\n- On the first of December, 2016, it removed the income condition, providing all its adult citizens with a basic income.\n\nThese elements are described in different folders. All the modelling happens within the `openfisca_country_template` folder.\n\n- The rates are in the `parameters` folder.\n- The formulas are in the `variables` folder.\n- This country package comes also with *reforms* in the `reforms` folder. This is optional: your country may exist without defining any reform.\n - In this country, there is [a reform project](./openfisca_country_template/reforms/modify_social_security_taxation.py) aiming to modify the social security taxation, deleting the first bracket, raising the intermediary ones and adding a new bracket with a higher tax rate of `40 %` for people earning more than `40000`. This reform project would apply starting from `2017-01-01`.\n\nThe files that are outside from the `openfisca_country_template` folder are used to set up the development environment.\n\n## Packaging your Country Package for Distribution\n\nCountry packages are python distributions. To distribute your package via `pip`, follow the steps given by the [Python Packaging Authority](https://python-packaging-user-guide.readthedocs.io/tutorials/distributing-packages/#packaging-your-project).\n\n## Install Instructions for Users and Contributors\n\nThis package requires [Python 3.9](https://www.python.org/downloads/release/python-390/). More recent versions should work, but are not tested.\n\nAll platforms that can execute Python are supported, which includes GNU/Linux, macOS and Microsoft Windows.\n\n### Setting-up a Virtual Environment with venv\n\nIn order to limit dependencies conflicts, we recommend using a [virtual environment](https://www.python.org/dev/peps/pep-0405/) with [venv](https://docs.python.org/3/library/venv.html).\n\n- A [venv](https://docs.python.org/3/library/venv.html) is a project specific environment created to suit the needs of the project you are working on.\n\nTo create a virtual environment, launch a terminal on your computer, `cd` into your directory and follow these instructions:\n\n```sh\npython3 -m venv openfisca # create a new venv called \u201copenfisca\u201d\nsource openfisca/bin/activate # activate the venv\n```\n\nYou can now operate in the venv you just created.\n\nYou can deactivate that venv at any time with `deactivate`.\n\n:tada: You are now ready to install this OpenFisca Country Package!\n\nTwo install procedures are available. Pick procedure A or B below depending on how you plan to use this Country Package.\n\n### A. Minimal Installation (Pip Install)\n\nFollow this installation if you wish to:\n- run calculations on a large population;\n- create tax & benefits simulations;\n- write an extension to this legislation (e.g. city specific tax & benefits);\n- serve your Country Package with the OpenFisca Web API.\n\nFor more advanced uses, head to the [Advanced Installation](#advanced-installation-git-clone).\n\n#### Install this Country Package with Pip Install\n\nInside your venv, check the prerequisites:\n\n```sh\npython --version # should print \"Python 3.9.xx\".\n```\n\n```sh\npip --version # should print at least 9.0.\n# if not, run \"pip install --upgrade pip\"\n```\nInstall the Country Package:\n\n```sh\npip install openfisca_country_template\n```\n\n:warning: Please beware that installing the Country Package with `pip` is dependent on its maintainers publishing said package.\n\n:tada: This OpenFisca Country Package is now installed and ready!\n\n#### Next Steps\n\n- To learn how to use OpenFisca, follow our [tutorials](https://openfisca.org/doc/).\n- To serve this Country Package, serve the [OpenFisca web API](#serve-your-country-package-with-the-openFisca-web-api).\n\nDepending on what you want to do with OpenFisca, you may want to install yet other packages in your venv:\n- To install extensions or write on top of this Country Package, head to the [Extensions documentation](https://openfisca.org/doc/contribute/extensions.html).\n- To plot simulation results, try [matplotlib](http://matplotlib.org/).\n- To manage data, check out [pandas](http://pandas.pydata.org/).\n\n### B. Advanced Installation (Git Clone)\n\nFollow this tutorial if you wish to:\n- create or change this Country Package's legislation;\n- contribute to the source code.\n\n#### Clone this Country Package with Git\n\nFirst, make sure [Git](https://www.git-scm.com/) is installed on your machine.\n\nSet your working directory to the location where you want this OpenFisca Country Package cloned.\n\nInside your venv, check the prerequisites:\n\n```sh\npython --version # should print \"Python 3.9.xx\".\n```\n\n```sh\npip --version # should print at least 9.0.\n# if not, run \"pip install --upgrade pip\"\n```\nClone this Country Package on your machine:\n\n```sh\ngit clone https://github.com/openfisca/openfisca-country-template.git\ncd openfisca-country-template\npip install --editable .[dev]\n```\n\nYou can make sure that everything is working by running the provided tests with `make test`.\n\n> [Learn more about tests](https://openfisca.org/doc/coding-the-legislation/writing_yaml_tests.html)\n\n:tada: This OpenFisca Country Package is now installed and ready!\n\n#### Next Steps\n\n- To write new legislation, read the [Coding the legislation](https://openfisca.org/doc/coding-the-legislation/index.html) section to know how to write legislation.\n- To contribute to the code, read our [Contribution Guidebook](https://openfisca.org/doc/contribute/index.html).\n\n## Serve this Country Package with the OpenFisca Web API\n\nIf you are considering building a web application, you can use the packaged OpenFisca Web API with your Country Package.\n\nTo serve the Openfisca Web API locally, run:\n\n```sh\nopenfisca serve --port 5000\n```\n\nOr use the quick-start Make command:\n\n```\nmake serve-local\n```\n\nTo read more about the `openfisca serve` command, check out its [documentation](https://openfisca.org/doc/openfisca-python-api/openfisca_serve.html).\n\nYou can make sure that your instance of the API is working by requesting:\n\n```sh\ncurl \"http://localhost:5000/spec\"\n```\n\nThis endpoint returns the [Open API specification](https://www.openapis.org/) of your API.\n\n:tada: This OpenFisca Country Package is now served by the OpenFisca Web API! To learn more, go to the [OpenFisca Web API documentation](https://openfisca.org/doc/openfisca-web-api/index.html).\n\nYou can test your new Web API by sending it example JSON data located in the `situation_examples` folder.\n\nSubstitute your package's country name for `openfisca_country_template` below:\n\n```sh\ncurl -X POST -H \"Content-Type: application/json\" \\\n -d @./openfisca_country_template/situation_examples/couple.json \\\n http://localhost:5000/calculate\n```\n",
"bugtrack_url": null,
"license": "http://www.fsf.org/licensing/licenses/agpl-3.0.html",
"summary": "OpenFisca tax and benefit system for Country-Template",
"version": "6.0.3",
"project_urls": {
"Homepage": "https://github.com/openfisca/country-template"
},
"split_keywords": [
"benefit",
"microsimulation",
"social",
"tax"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cd644c00f4bcc0ae61a66e7ac7c99f091181e42d9b14cc6df04e0499b58b0580",
"md5": "fc4c65cb30778d28dbfa662629480b73",
"sha256": "1c15f39125d46b23fa5daa0de36158929e4b982dc15414cb660bde91231a080a"
},
"downloads": -1,
"filename": "OpenFisca_Country_Template-6.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc4c65cb30778d28dbfa662629480b73",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 52909,
"upload_time": "2023-09-15T15:50:58",
"upload_time_iso_8601": "2023-09-15T15:50:58.258877Z",
"url": "https://files.pythonhosted.org/packages/cd/64/4c00f4bcc0ae61a66e7ac7c99f091181e42d9b14cc6df04e0499b58b0580/OpenFisca_Country_Template-6.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c994b50ebb8e33780fcffedc796353688adde56732294c82db7bbcae033ecb15",
"md5": "ff0c2fff275902676b550029476f31ce",
"sha256": "187d2a91d5f265a3a02c2b5d32b5ee50114531f48a975859eee5d36a2d1691ef"
},
"downloads": -1,
"filename": "OpenFisca-Country-Template-6.0.3.tar.gz",
"has_sig": false,
"md5_digest": "ff0c2fff275902676b550029476f31ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 34546,
"upload_time": "2023-09-15T15:51:00",
"upload_time_iso_8601": "2023-09-15T15:51:00.916248Z",
"url": "https://files.pythonhosted.org/packages/c9/94/b50ebb8e33780fcffedc796353688adde56732294c82db7bbcae033ecb15/OpenFisca-Country-Template-6.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-15 15:51:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openfisca",
"github_project": "country-template",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openfisca-country-template"
}
JSON
