# OpenFisca Nouvelle Calédonie
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.
## Setting up your 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](https://git-scm.com) installed.
### Using GitHub (recommended for GitHub users)
1. Click on the
[“Use this template” dropdown and select “Create a new repository”](https://github.com/new?template_name=country-template&template_owner=openfisca).
2. 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`.
3. 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.
4. Follow the instructions in the new repository's README.md.
### Manual setup (recommended for users of other Git hosts)
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 (Bitbucket, GitLab, …)
with the name `openfisca-<your_country_name>`. For example,
`openfisca-new_zealand` or `openfisca-france`.
3. 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.
- To execute the script run `bash first-time-setup.sh` from the command line
- After the `first-time-setup.sh` has run both it and these instructions are
removed.
4. Follow the instructions in the new repository's `README.md.`
## 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. You can choose to distribute your
package automatically via the predefined continuous deployment system on GitHub
Actions, or manually.
### Automatic continuous deployment on GitHub
This repository is configured with a continuous deployment system to automate
the distribution of your package via `pip`.
#### Setting up continuous deployment
To activate the continuous deployment:
1. Create an account on [PyPI](https://pypi.org/) if you don't already have
one.
2. Generate a token in your PyPI account. This token will allow GitHub Actions
to securely upload new versions of your package to PyPI.
3. Add this token to your GitHub repository's secrets under the name
`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.
### Manual distribution
If you prefer to manually manage the release and distribution of your package,
follow the guidelines provided by the
[Python Packaging Authority](https://python-packaging-user-guide.readthedocs.io/tutorials/distributing-packages/#packaging-your-project).
This involves detailed steps on preparing your package, creating distribution
files, and uploading them to PyPI.
## Install Instructions for Users and Contributors
This package requires
[Python 3.11](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 .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.
### 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.11.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.11.xx".
```
Clone this Country Package on your machine:
```sh
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`.
> [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).
### C. Contributing
Follow this tutorial if you wish to:
- contribute to the source code.
_Note: This tutorial assumes you have already followed the instructions laid
out in section [B. Advanced Installation](#b-advanced-installation-git-clone)._
In order to ensure all published versions of this template work as expected,
new contributions are tested in an isolated manner on Github Actions.
Follow these steps to set up an isolated environment for testing your
contributions as Github Actions does.
#### Set up an isolated environment
First, make sur [Tox](https://tox.wiki/en/4.23.0/) is installed on your
machine.
We recommend using [pipx](<(https://pypi.org/project/pipx/)>) to install `tox`,
to avoid mixing isolated-testing dependencies testing with `virtualenv`.
```sh
pipx install tox
```
#### Testing your contribution in an isolated environment
You can make sure that your contributions will work as expected by running:
```sh
tox
```
You can also run these in parallel:
```sh
tox -p
```
:tada: Your contribution to OpenFisca Country Package is now ready for prime
time!
#### Next Steps
- Open a pull request to the `main` branch of this repository.
- Announce your changes as described in [CONTRIBUTING](CONTRIBUTING.md).
## 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 --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](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.
```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": null,
"name": "openfisca-nouvelle-caledonie",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "benefit, microsimulation, rac, rules-as-code, tax",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6d/a4/af723c2b69a04504e1fb728ef5d3346a0e869983f4a73a3dc145b9fd8b2a/openfisca_nouvelle_caledonie-13.2.2.tar.gz",
"platform": null,
"description": "# OpenFisca Nouvelle Cal\u00e9donie\n\nThis repository helps you quickly set up and use your own OpenFisca country\npackage.\n\n**You should NOT fork it** but follow the set up instructions below.\n\n> Otherwise, you will have to clean up all tags when you deploy your own\n> country package.\n\n## Setting up your Country Package\n\nThis set of instructions **only needs to be followed once** and will create\nyour own copy of this boilerplate directory, customising it to the country you\nwant to work on. You will need to have [Git](https://git-scm.com) installed.\n\n### Using GitHub (recommended for GitHub users)\n\n1. Click on the\n [\u201cUse this template\u201d dropdown and select \u201cCreate a new repository\u201d](https://github.com/new?template_name=country-template&template_owner=openfisca).\n\n2. Set the repository name to `openfisca-<your_country_name>`; use underscore\n `_` as separator if there are spaces in the country name. For example,\n `openfisca-new_zealand` or `openfisca-france`.\n\n3. After being redirected to your newly created repository, please allow a few\n minutes for the automatic setup to be executed. Once done, the title of the\n README file should be updated to `OpenFisca <your_country_name>`.\n\n> If the automatic setup does not start within a few minutes, you can initiate\n> it manually:\n>\n> - Navigate to the \u201cActions\u201d tab.\n> - Select the \u201cFirst time setup\u201d workflow.\n> - Click on \u201cRun workflow\u201d to start the setup process manually.\n\n4. Follow the instructions in the new repository's README.md.\n\n### Manual setup (recommended for users of other Git hosts)\n\n1. [Download a copy](https://github.com/openfisca/country-template/archive/master.zip)\n of this repository, unzip it and `cd` into it in a Terminal window.\n\n2. Create a new repository on your favourite git host (Bitbucket, GitLab, \u2026)\n with the name `openfisca-<your_country_name>`. For example,\n `openfisca-new_zealand` or `openfisca-france`.\n\n3. Execute the `first-time-setup.sh` script to initialise the git repository.\n This performs numerous tasks including replacing all references to\n `openfisca-country_template` with references to the new country package.\n\n - To execute the script run `bash first-time-setup.sh` from the command line\n - After the `first-time-setup.sh` has run both it and these instructions are\n removed.\n\n4. Follow the instructions in the new repository's `README.md.`\n\n## Writing the Legislation\n\nThe country whose law is modelled here has a very simple tax and benefit\nsystem.\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\n citizens of age who have no income.\n- On the first of December, 2016, it removed the income condition, providing\n all its adult citizens with a basic income.\n\nThese elements are described in different folders. All the modelling happens\nwithin 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\n is optional: your country may exist without defining any reform.\n - In this country, there is\n [a reform project](./openfisca_country_template/reforms/modify_social_security_taxation.py)\n aiming to modify the social security taxation, deleting the first bracket,\n raising the intermediary ones and adding a new bracket with a higher tax\n rate of `40 %` for people earning more than `40000`. This reform project\n would apply starting from `2017-01-01`.\n\nThe files that are outside from the `openfisca_country_template` folder are\nused to set up the development environment.\n\n## Packaging your Country Package for Distribution\n\nCountry packages are Python distributions. You can choose to distribute your\npackage automatically via the predefined continuous deployment system on GitHub\nActions, or manually.\n\n### Automatic continuous deployment on GitHub\n\nThis repository is configured with a continuous deployment system to automate\nthe distribution of your package via `pip`.\n\n#### Setting up continuous deployment\n\nTo activate the continuous deployment:\n\n1. Create an account on [PyPI](https://pypi.org/) if you don't already have\n one.\n2. Generate a token in your PyPI account. This token will allow GitHub Actions\n to securely upload new versions of your package to PyPI.\n3. Add this token to your GitHub repository's secrets under the name\n `PYPI_TOKEN`.\n\nOnce set up, changes to the `main` branch will trigger an automated workflow to\nbuild and publish your package to PyPI, making it available for `pip`\ninstallation.\n\n### Manual distribution\n\nIf you prefer to manually manage the release and distribution of your package,\nfollow the guidelines provided by the\n[Python Packaging Authority](https://python-packaging-user-guide.readthedocs.io/tutorials/distributing-packages/#packaging-your-project).\n\nThis involves detailed steps on preparing your package, creating distribution\nfiles, and uploading them to PyPI.\n\n## Install Instructions for Users and Contributors\n\nThis package requires\n[Python 3.11](https://www.python.org/downloads/release/python-390/). More\nrecent versions should work, but are not tested.\n\nAll platforms that can execute Python are supported, which includes GNU/Linux,\nmacOS and Microsoft Windows.\n\n### Setting-up a Virtual Environment with venv\n\nIn order to limit dependencies conflicts, we recommend using a\n[virtual environment](https://www.python.org/dev/peps/pep-0405/) with\n[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\n 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\nyour directory and follow these instructions:\n\n```sh\npython3 -m venv .venv # create a new virtual environment in the \u201c.venv\u201d folder, which will contain all dependencies\nsource .venv/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\nhow you plan to use this Country Package.\n\n### A. Minimal Installation (Pip Install)\n\nFollow this installation if you wish to:\n\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\n[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.11.xx\".\n```\n\n```sh\npip --version # should print at least 9.0.\n# if not, run \"pip install --upgrade pip\"\n```\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\ndependent 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\n [tutorials](https://openfisca.org/doc/).\n- To serve this Country Package, serve the\n [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\nother packages in your venv:\n\n- To install extensions or write on top of this Country Package, head to the\n [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\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\nCountry Package cloned.\n\nInside your venv, check the prerequisites:\n\n```sh\npython --version # should print \"Python 3.11.xx\".\n```\n\nClone this Country Package on your machine:\n\n```sh\ngit clone https://example.com/repository.git\ncd repository_folder\npip install --upgrade pip build twine\npip install --editable .[dev] --upgrade\n```\n\nYou can make sure that everything is working by running the provided tests with\n`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\n [Coding the legislation](https://openfisca.org/doc/coding-the-legislation/index.html)\n section to know how to write legislation.\n- To contribute to the code, read our\n [Contribution Guidebook](https://openfisca.org/doc/contribute/index.html).\n\n### C. Contributing\n\nFollow this tutorial if you wish to:\n\n- contribute to the source code.\n\n_Note: This tutorial assumes you have already followed the instructions laid\nout in section [B. Advanced Installation](#b-advanced-installation-git-clone)._\n\nIn order to ensure all published versions of this template work as expected,\nnew contributions are tested in an isolated manner on Github Actions.\n\nFollow these steps to set up an isolated environment for testing your\ncontributions as Github Actions does.\n\n#### Set up an isolated environment\n\nFirst, make sur [Tox](https://tox.wiki/en/4.23.0/) is installed on your\nmachine.\n\nWe recommend using [pipx](<(https://pypi.org/project/pipx/)>) to install `tox`,\nto avoid mixing isolated-testing dependencies testing with `virtualenv`.\n\n```sh\npipx install tox\n```\n\n#### Testing your contribution in an isolated environment\n\nYou can make sure that your contributions will work as expected by running:\n\n```sh\ntox\n```\n\nYou can also run these in parallel:\n\n```sh\ntox -p\n```\n\n:tada: Your contribution to OpenFisca Country Package is now ready for prime\ntime!\n\n#### Next Steps\n\n- Open a pull request to the `main` branch of this repository.\n- Announce your changes as described in [CONTRIBUTING](CONTRIBUTING.md).\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\nOpenFisca Web API with your Country Package.\n\nTo serve the Openfisca Web API locally, run:\n\n```sh\nopenfisca serve --port 5000 --country-package openfisca_country_template\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\n[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/)\nof your API.\n\n:tada: This OpenFisca Country Package is now served by the OpenFisca Web API!\nTo learn more, go to the\n[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\n`situation_examples` folder.\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": null,
"summary": "OpenFisca Rules as Code model for Nouvelle Cal\u00e9donie.",
"version": "13.2.2",
"project_urls": {
"Changelog": "https://github.com/openfisca/openfisca-nouvelle_caledonie/blob/main/CHANGELOG.md",
"Documentation": "https://openfisca.org/doc",
"Homepage": "https://github.com/openfisca/openfisca-nouvelle_caledonie",
"Issues": "https://github.com/openfisca/openfisca-nouvelle_caledonie/issues",
"Repository": "https://github.com/openfisca/openfisca-nouvelle_caledonie"
},
"split_keywords": [
"benefit",
" microsimulation",
" rac",
" rules-as-code",
" tax"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b91c41fcf6fe2ee9d38ba2c2ee8277cb99df39326c79cb593cf28d4d211352b",
"md5": "34a001ac5999c3a1c586f22e2d40ed13",
"sha256": "f1b2808c174c9bbbdd3c1d6ce87ca1fa2ea648ec683a4106cdec7cca8a811f35"
},
"downloads": -1,
"filename": "openfisca_nouvelle_caledonie-13.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34a001ac5999c3a1c586f22e2d40ed13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 227350,
"upload_time": "2025-07-26T16:16:34",
"upload_time_iso_8601": "2025-07-26T16:16:34.121453Z",
"url": "https://files.pythonhosted.org/packages/4b/91/c41fcf6fe2ee9d38ba2c2ee8277cb99df39326c79cb593cf28d4d211352b/openfisca_nouvelle_caledonie-13.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6da4af723c2b69a04504e1fb728ef5d3346a0e869983f4a73a3dc145b9fd8b2a",
"md5": "a4d2c6ad126fdb7c296879808bfe1ef2",
"sha256": "92932df54c8d12042873e72be7ae8e862f6d37c06cabbb38cf18693d59f89b84"
},
"downloads": -1,
"filename": "openfisca_nouvelle_caledonie-13.2.2.tar.gz",
"has_sig": false,
"md5_digest": "a4d2c6ad126fdb7c296879808bfe1ef2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 86528,
"upload_time": "2025-07-26T16:16:35",
"upload_time_iso_8601": "2025-07-26T16:16:35.375906Z",
"url": "https://files.pythonhosted.org/packages/6d/a4/af723c2b69a04504e1fb728ef5d3346a0e869983f4a73a3dc145b9fd8b2a/openfisca_nouvelle_caledonie-13.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 16:16:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openfisca",
"github_project": "openfisca-nouvelle_caledonie",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openfisca-nouvelle-caledonie"
}
JSON
