From a6d566f469340e4b7af8b6d7cd217790e881fe82 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 16 Oct 2024 14:56:49 +0200 Subject: [PATCH 1/8] build: add tox --- Makefile | 25 ++++----- pyproject.toml | 147 +++++++++++++++++++++++++++++++------------------ 2 files changed, 103 insertions(+), 69 deletions(-) diff --git a/Makefile b/Makefile index 7414e72..9479391 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,7 @@ uninstall: clean: rm -rf build dist find . -name '*.pyc' -exec rm \{\} \; + find . -type d -name '__pycache__' -exec rm -r {} + deps: pip install --upgrade pip build twine @@ -24,30 +25,24 @@ build: clean deps pip uninstall --yes openfisca-country-template find dist -name "*.whl" -exec pip install --force-reinstall {}[dev] \; -check-syntax-errors: - python -m compileall -q . - -format-style: +format: @# Do not analyse .gitignored files. @# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764. - ruff format `git ls-files | grep "\.py$$"` - isort `git ls-files | grep "\.py$$"` black `git ls-files | grep "\.py$$"` + isort `git ls-files | grep "\.py$$"` + pyproject-fmt pyproject.toml + ruff format `git ls-files | grep "\.py$$"` -check-style: +lint: @# Do not analyse .gitignored files. @# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764. - ruff check `git ls-files | grep "\.py$$"` - isort --check `git ls-files | grep "\.py$$"` black --check `git ls-files | grep "\.py$$"` - -check-yaml: - @# Do not analyse .gitignored files. - @# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764. + isort --check `git ls-files | grep "\.py$$"` + ruff check `git ls-files | grep "\.py$$"` yamllint `git ls-files | grep "\.yaml$$"` -test: clean check-syntax-errors check-style - openfisca test --country-package openfisca_country_template openfisca_country_template/tests +test: clean + PYTEST_ADDOPTS="--import-mode importlib" openfisca test --country-package openfisca_country_template openfisca_country_template/tests serve-local: build openfisca serve --country-package openfisca_country_template diff --git a/pyproject.toml b/pyproject.toml index 7aade14..afc3c48 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,45 +1,73 @@ +[build-system] +build-backend = "setuptools.build_meta" + +requires = [ "setuptools>=61" ] + [project] -name = "openfisca-country_template" +name = "openfisca-country-template" version = "7.1.6" -dependencies = [ - "openfisca-core[web-api] >= 43", -] -requires-python = ">=3.9" -authors = [] -maintainers = [] description = "OpenFisca Rules as Code model for Country-Template." readme = "README.md" -keywords = ["microsimulation", "tax", "benefit", "rac", "rules-as-code"] +keywords = [ "benefit", "microsimulation", "rac", "rules-as-code", "tax" ] +maintainers = [ ] +authors = [ ] +requires-python = ">=3.9" classifiers = [ "Development Status :: 5 - Production/Stable", "License :: OSI Approved :: GNU Affero General Public License v3", "Operating System :: POSIX", "Programming Language :: Python", + "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", "Topic :: Scientific/Engineering :: Information Analysis", ] -[project.optional-dependencies] -dev = [ - "black >=24.8.0, <25.0", - "isort >=5.13.2, <6.0", - "ruff >=0.6.9, <1.0", - "ruff-lsp >=0.0.57, <1.0", - "yamllint >=1.35.1" +dependencies = [ + "openfisca-core[web-api]>=43", ] - -[project.urls] -Homepage = "https://github.com/openfisca/country-template" -Repository = "https://github.com/openfisca/country-template" -Documentation = "https://openfisca.org/doc" -Issues = "https://github.com/openfisca/country-template/issues" -Changelog = "https://github.com/openfisca/country-template/blob/main/CHANGELOG.md" - +optional-dependencies.dev = [ + "black>=24.8,<25", + "isort>=5.13.2,<6", + "pyproject-fmt>=2.3.1,<3", + "ruff>=0.6.9,<1", + "ruff-lsp>=0.0.57,<1", + "yamllint>=1.35.1", +] +urls.Changelog = "https://github.com/openfisca/country-template/blob/main/CHANGELOG.md" +urls.Documentation = "https://openfisca.org/doc" +urls.Homepage = "https://github.com/openfisca/country-template" +urls.Issues = "https://github.com/openfisca/country-template/issues" +urls.Repository = "https://github.com/openfisca/country-template" [tool.black] -target_version = ["py39", "py310", "py311"] +target_version = [ "py39", "py310", "py311" ] + +[tool.ruff] +target-version = "py39" +format.docstring-code-line-length = 72 +format.docstring-code-format = true +lint.select = [ "ALL" ] +lint.ignore = [ + "ANN", + "COM812", + "D101", + "D104", + "I001", + "ISC001", + "N801", + "N805", + "N806", + "PLR2004", + "PTH100", + "PTH118", + "PTH120", + "PTH123", +] +lint.pydocstyle.convention = "google" [tool.isort] case_sensitive = true @@ -48,10 +76,10 @@ force_alphabetical_sort_within_sections = false group_by_package = true honor_noqa = true include_trailing_comma = true -known_first_party = ["openfisca_country_template"] -known_openfisca = ["openfisca_core", "openfisca_extension_template"] -known_typing = ["*collections.abc*", "*typing*", "*typing_extensions*"] -known_types = ["*types*"] +known_first_party = [ "openfisca_country_template" ] +known_openfisca = [ "openfisca_core", "openfisca_extension_template" ] +known_typing = [ "*collections.abc*", "*typing*", "*typing_extensions*" ] +known_types = [ "*types*" ] multi_line_output = 3 profile = "black" py_version = 39 @@ -66,37 +94,48 @@ sections = [ "LOCALFOLDER", ] +[tool.pyproject-fmt] +column_width = 79 +indent = 4 + [tool.pytest.ini_options] -addopts = "--exitfirst --showlocals --doctest-modules" +addopts = "--exitfirst --showlocals --doctest-modules --disable-warnings" testpaths = [ "openfisca_country_template/tests" ] python_files = "**/*.py" -filterwarnings = ["ignore::DeprecationWarning"] -[tool.ruff] -target-version = "py39" +[tool.tox] +requires = [ "tox>=4.20" ] +env_list = [ "py39", "py310", "py311", "lint", "dist" ] -[tool.ruff.format] -docstring-code-format = true -docstring-code-line-length = 72 +[tool.tox.env_run_base] +allowlist_externals = [ "make" ] +commands = [ [ "make", "test" ] ] +commands_pre = [ + [ + "pip", + "install", + "--find-links", + ".", + "openfisca_country_template", + ], +] -[tool.ruff.lint] -ignore = [ - "ANN", - "COM812", - "D101", - "D104", - "I001", - "ISC001", - "N801", - "N805", - "N806", - "PLR2004", - "PTH100", - "PTH118", - "PTH120", - "PTH123", +[tool.tox.env.lint] +allowlist_externals = [ "make" ] +basepython = [ "py39" ] +commands = [ [ "make", "lint" ] ] +commands_pre = [ + [ + "pip", + "install", + "--find-links", + ".", + "openfisca_country_template[dev]", + ], ] -select = ["ALL"] -[tool.ruff.lint.pydocstyle] -convention = "google" +[tool.tox.env.dist] +basepython = [ "py39" ] +commands = [ [ "twine", "check", "dist/*" ] ] +commands_pre = [ [ "python", "-m", "build" ] ] +deps = [ "build", "twine" ] From 07903a9f8f744c51279d701413b89e59dd3b1558 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 16 Oct 2024 15:04:47 +0200 Subject: [PATCH 2/8] ci: add tox to ci --- .github/workflows/validate.yml | 36 +++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 56087b8..e29b0c0 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -14,29 +14,36 @@ jobs: needs: [ build ] steps: - uses: actions/checkout@v4 - with: - fetch-depth: 0 # Fetch all the tags + + - name: Install Tox + run: pipx install tox - name: Set up Python uses: actions/setup-python@v5 with: python-version: 3.9.12 - - name: Restore build - uses: actions/cache@v4 - with: - path: ${{ env.pythonLocation }} - key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }} + - name: Lint files + run: tox -r -e lint - - run: make check-syntax-errors + test-yaml: + runs-on: ubuntu-22.04 + needs: [ build ] + steps: + - uses: actions/checkout@v4 - - name: Lint Python files - run: make check-style + - name: Install Tox + run: pipx install tox - - name: Lint YAML tests - run: make check-yaml + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.9.12 - test-yaml: + - name: Test files + run: tox -r -e py39 + + test-dist: runs-on: ubuntu-22.04 needs: [ build ] steps: @@ -53,7 +60,8 @@ jobs: path: ${{ env.pythonLocation }} key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }} - - run: make test + - name: Test the built package + run: twine check dist/* test-api: runs-on: ubuntu-22.04 From 5756f4a7971f594b46f3023c34d522411778cef3 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 16 Oct 2024 15:13:27 +0200 Subject: [PATCH 3/8] ci: fix restore build --- .github/workflows/validate.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index e29b0c0..719eab4 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -54,14 +54,16 @@ jobs: with: python-version: 3.9.12 - - name: Restore build + - name: Restore built package uses: actions/cache@v4 with: - path: ${{ env.pythonLocation }} - key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }} + path: dist + key: release-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }} - name: Test the built package - run: twine check dist/* + run: | + pip install twine + twine check dist/* test-api: runs-on: ubuntu-22.04 From f080bfe886dd1cf0bf45c4d63f41fc408c2985e2 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 16 Oct 2024 15:22:43 +0200 Subject: [PATCH 4/8] chore: typo --- pyproject.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index afc3c48..425626a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,5 @@ [build-system] build-backend = "setuptools.build_meta" - requires = [ "setuptools>=61" ] [project] From 22baf3fadb5598d23583f4dd79ca3215d8c7976b Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 16 Oct 2024 15:27:25 +0200 Subject: [PATCH 5/8] chore: fix wrong supported versions --- pyproject.toml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 425626a..d289adb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,8 +20,6 @@ classifiers = [ "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Programming Language :: Python :: 3.13", "Topic :: Scientific/Engineering :: Information Analysis", ] @@ -96,6 +94,7 @@ sections = [ [tool.pyproject-fmt] column_width = 79 indent = 4 +max_supported_python = "3.11" [tool.pytest.ini_options] addopts = "--exitfirst --showlocals --doctest-modules --disable-warnings" From 54f6510c777d858f803835a2db993677015016f3 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Fri, 18 Oct 2024 11:59:30 +0200 Subject: [PATCH 6/8] docs: add tox instructions --- CHANGELOG.md | 2 +- CONTRIBUTING.md | 104 +++++++++++++++-------- README.md | 215 +++++++++++++++++++++++++++++++++++++----------- 3 files changed, 237 insertions(+), 84 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index af454e3..d9e1563 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -478,7 +478,7 @@ name: Housing tax * Minor change. * Details: - - Make boostrap script portable. + - Make bootstrap script portable. ## 3.2.0 - [#43](https://github.com/openfisca/country-template/pull/43) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f8ff68..4479a6d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,36 +1,45 @@ -> This file defines the rules to follow to contribute to your repository. -> The rules suggested here are what we generally use for OpenFisca country packages. -> You can of course edit them, and you should probably remove this block :) +> This file defines the rules to follow to contribute to your repository. The +> rules suggested here are what we generally use for OpenFisca country +> packages. You can of course edit them, and you should probably remove this +> block :) Thank you for wanting to contribute to OpenFisca! :smiley: -TL;DR: [GitHub Flow](https://guides.github.com/introduction/flow/), [SemVer](http://semver.org/). - +TL;DR: [GitHub Flow](https://guides.github.com/introduction/flow/), +[SemVer](http://semver.org/). ## Pull requests -We follow the [GitHub Flow](https://guides.github.com/introduction/flow/): all code contributions are submitted via a pull request towards the `main` branch. +We follow the [GitHub Flow](https://guides.github.com/introduction/flow/): all +code contributions are submitted via a pull request towards the `main` branch. -Opening a Pull Request means you want that code to be merged. If you want to only discuss it, send a link to your branch along with your questions through whichever communication channel you prefer. +Opening a Pull Request means you want that code to be merged. If you want to +only discuss it, send a link to your branch along with your questions through +whichever communication channel you prefer. ### Peer reviews All pull requests must be reviewed by someone else than their original author. -> In case of a lack of available reviewers, one may review oneself, but only after at least 24 hours have passed without working on the code to review. - -To help reviewers, make sure to add to your PR a **clear text explanation** of your changes. +> In case of a lack of available reviewers, one may review oneself, but only +> after at least 24 hours have passed without working on the code to review. -In case of breaking changes, you **must** give details about what features were deprecated. +To help reviewers, make sure to add to your PR a **clear text explanation** of +your changes. -> You must also provide guidelines to help users adapt their code to be compatible with the new version of the package. +In case of breaking changes, you **must** give details about what features were +deprecated. +> You must also provide guidelines to help users adapt their code to be +> compatible with the new version of the package. ## Advertising changes ### Version number -We follow the [semantic versioning](http://semver.org/) spec: any change impacts the version number, and the version number conveys API compatibility information **only**. +We follow the [semantic versioning](http://semver.org/) spec: any change +impacts the version number, and the version number conveys API compatibility +information **only**. Examples: @@ -48,14 +57,18 @@ Examples: ### Changelog -openfisca-country_template changes must be understood by users who don't necessarily work on the code. The Changelog must therefore be as explicit as possible. +openfisca-country_template changes must be understood by users who don't +necessarily work on the code. The Changelog must therefore be as explicit as +possible. Each change must be documented with the following elements: -- On the first line appears as a title the version number, as well as a link towards the Pull Request introducing the change. The title level must match the incrementation level of the version. - +- On the first line appears as a title the version number, as well as a link + towards the Pull Request introducing the change. The title level must match + the incrementation level of the version. > For instance : +> > # 13.0.0 - [#671](https://example.com/repository/pull/671) > > ## 13.2.0 - [#676](https://example.com/repository/pull/676) @@ -63,36 +76,59 @@ Each change must be documented with the following elements: > ### 13.1.5 - [#684](https://example.com/repository/pull/684) - The second line indicates the type of the change. The possible types are: - - `Tax and benefit system evolution`: Calculation improvement, fix, or update. Impacts the users interested in calculations. - - `Technical improvement`: Performances improvement, installing process change, formula syntax change… Impacts the users who write legislation and/or deploy their own instance. - - `Crash fix`: Impact all reusers. - - `Minor change`: Refactoring, metadata… Has no impact on users. -- In the case of a `Tax and benefit system evolution`, the following elements must then be specified: - - The periods impacted by the change. To avoid any ambiguity, the start day and/or the end day of the impacted periods must be precised. For instance, `from 01/01/2017` is correct, but `from 2017` is not, as it is ambiguous: it is not clear wheter 2017 is included or not in the impacted period. - - The tax and benefit system areas impacted by the change. These areas are described by the relative paths to the modified files, without the `.py` extension. +- `Tax and benefit system evolution`: Calculation improvement, fix, or update. + Impacts the users interested in calculations. + +- `Technical improvement`: Performances improvement, installing process change, + formula syntax change… Impacts the users who write legislation and/or deploy + their own instance. + +- `Crash fix`: Impact all reusers. + +- `Minor change`: Refactoring, metadata… Has no impact on users. + +- In the case of a `Tax and benefit system evolution`, the following elements + must then be specified: + + - The periods impacted by the change. To avoid any ambiguity, the start day + and/or the end day of the impacted periods must be precised. For instance, + `from 01/01/2017` is correct, but `from 2017` is not, as it is ambiguous: + it is not clear whether 2017 is included or not in the impacted period. + - The tax and benefit system areas impacted by the change. These areas are + described by the relative paths to the modified files, without the `.py` + extension. > For instance : +> > - Impacted periods: Until 31/12/2015. > - Impacted areas: `benefits/healthcare/universal_coverage` -- Finally, for all cases except `Minor Change`, the changes must be explicited by details given from a user perspective: in which case was an error or a problem was noticed ? What is the new available feature ? Which new behaviour is adopted. +- Finally, for all cases except `Minor Change`, the changes must be described + in an explicit manner by details given from a user perspective: in which case + was an error or a problem was noticed ? What is the new available feature ? + Which new behaviour is adopted. > For instance: > -> * Details : +> - Details : > - These variables now return a yearly amount (instead of monthly): > - `middle_school_scholarship` > - `high_school_scholarship` -> - _The previous monthly amounts were just yearly amounts artificially divided by 12_ +> - _The previous monthly amounts were just yearly amounts artificially +> divided by 12_ > > or : > -> * Details : -> - Use OpenFisca-Core `12.0.0` -> - Change the syntax used to declare parameters: -> - Remove "fuzzy" attribute -> - Remove "end" attribute -> - All parameters are assumed to be valid until and end date is explicitely specified with an `` tag - -When a Pull Request contains several disctincts changes, several paragraphs may be added to the Changelog. To be properly formatted in Markdown, these paragraphs must be separated by ``. +> - Details : +> +> * Use OpenFisca-Core `12.0.0` +> * Change the syntax used to declare parameters: +> - Remove "fuzzy" attribute +> - Remove "end" attribute +> - All parameters are assumed to be valid until and end date is explicitly +> specified with an `` tag + +When a Pull Request contains several distinct changes, several paragraphs may +be added to the Changelog. To be properly formatted in Markdown, these +paragraphs must be separated by ``. diff --git a/README.md b/README.md index bf9ffe7..315a8fa 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,35 @@ # OpenFisca Country-Template -This repository helps you quickly set up and use your own OpenFisca country package. +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. +> 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. +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). +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-`; use underscore `_` as separator if there are spaces in the country name. For example, `openfisca-new_zealand` or `openfisca-france`. +2. Set the repository name to `openfisca-`; 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 `. +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 `. -> If the automatic setup does not start within a few minutes, you can initiate it manually: +> 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. @@ -27,71 +38,106 @@ This set of instructions **only needs to be followed once** and will create your ### 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. +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-`. For example, `openfisca-new_zealand` or `openfisca-france`. +2. Create a new repository on your favourite git host (Bitbucket, GitLab, …) + with the name `openfisca-`. 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. -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. + - 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. +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. +- 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. +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. +- 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. +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`. +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`. +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. +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. +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. +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. +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). +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. +- 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: +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 @@ -104,17 +150,20 @@ 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. +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). +For more advanced uses, head to the +[Advanced Installation](#advanced-installation-git-clone). #### Install this Country Package with Pip Install @@ -128,29 +177,37 @@ python --version # should print "Python 3.11.xx". 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. +: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). +- 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). +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. @@ -158,7 +215,8 @@ Follow this tutorial if you wish to: 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. +Set your working directory to the location where you want this OpenFisca +Country Package cloned. Inside your venv, check the prerequisites: @@ -175,7 +233,8 @@ 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`. +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) @@ -183,12 +242,65 @@ You can make sure that everything is working by running the provided tests with #### 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). +- 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. +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: @@ -202,7 +314,8 @@ 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). +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: @@ -210,11 +323,15 @@ 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](https://www.openapis.org/) of your API. +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). +: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. +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" \ From e71da75cf36e55b0bffdbe7b27da98ba2702aa7e Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Fri, 18 Oct 2024 12:04:16 +0200 Subject: [PATCH 7/8] style: remove black --- Makefile | 6 ++---- pyproject.toml | 6 +----- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index 9479391..e9ddc22 100644 --- a/Makefile +++ b/Makefile @@ -28,21 +28,19 @@ build: clean deps format: @# Do not analyse .gitignored files. @# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764. - black `git ls-files | grep "\.py$$"` + ruff format `git ls-files | grep "\.py$$"` isort `git ls-files | grep "\.py$$"` pyproject-fmt pyproject.toml - ruff format `git ls-files | grep "\.py$$"` lint: @# Do not analyse .gitignored files. @# `make` needs `$$` to output `$`. Ref: http://stackoverflow.com/questions/2382764. - black --check `git ls-files | grep "\.py$$"` isort --check `git ls-files | grep "\.py$$"` ruff check `git ls-files | grep "\.py$$"` yamllint `git ls-files | grep "\.yaml$$"` test: clean - PYTEST_ADDOPTS="--import-mode importlib" openfisca test --country-package openfisca_country_template openfisca_country_template/tests + openfisca test --country-package openfisca_country_template openfisca_country_template/tests serve-local: build openfisca serve --country-package openfisca_country_template diff --git a/pyproject.toml b/pyproject.toml index d289adb..63f56ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,7 +27,6 @@ dependencies = [ "openfisca-core[web-api]>=43", ] optional-dependencies.dev = [ - "black>=24.8,<25", "isort>=5.13.2,<6", "pyproject-fmt>=2.3.1,<3", "ruff>=0.6.9,<1", @@ -40,9 +39,6 @@ urls.Homepage = "https://github.com/openfisca/country-template" urls.Issues = "https://github.com/openfisca/country-template/issues" urls.Repository = "https://github.com/openfisca/country-template" -[tool.black] -target_version = [ "py39", "py310", "py311" ] - [tool.ruff] target-version = "py39" format.docstring-code-line-length = 72 @@ -97,7 +93,7 @@ indent = 4 max_supported_python = "3.11" [tool.pytest.ini_options] -addopts = "--exitfirst --showlocals --doctest-modules --disable-warnings" +addopts = "--exitfirst --showlocals --doctest-modules --disable-warnings --import-mode importlib" testpaths = [ "openfisca_country_template/tests" ] python_files = "**/*.py" From 3430b7f607efbce0acd6fb15be3b6297e28600e0 Mon Sep 17 00:00:00 2001 From: Mauko Quiroga Date: Wed, 16 Oct 2024 15:20:40 +0200 Subject: [PATCH 8/8] chore: version bump --- CHANGELOG.md | 7 +++++++ pyproject.toml | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d9e1563..f09762b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +### 7.1.7 [#158](https://github.com/openfisca/country-template/pull/158) + +* Technical improvement. +* Details: + - Run tests in absolute isolation + - Uses `tox` to test builds in isolation + ### 7.1.6 [#156](https://github.com/openfisca/country-template/pull/156) * Minor change. diff --git a/pyproject.toml b/pyproject.toml index 63f56ea..ee8ae04 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ requires = [ "setuptools>=61" ] [project] name = "openfisca-country-template" -version = "7.1.6" +version = "7.1.7" description = "OpenFisca Rules as Code model for Country-Template." readme = "README.md" keywords = [ "benefit", "microsimulation", "rac", "rules-as-code", "tax" ]