Metadata-Version: 2.4
Name: OpenFisca-Core-test
Version: 46.0.3
Summary: A versatile microsimulation free software
Author-email: OpenFisca Team <contact@openfisca.org>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/openfisca/openfisca-core
Project-URL: Documentation, https://openfisca.org/doc/
Project-URL: Repository, https://github.com/openfisca/openfisca-core.git
Keywords: benefit,microsimulation,social,tax
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7.0,>=6.0.1
Requires-Dist: PyYAML<7.0,>=6.0.2; python_version >= "3.13"
Requires-Dist: StrEnum<0.5.0,>=0.4.8
Requires-Dist: dpath<3.0,>=2.2.0
Requires-Dist: numexpr<3.0,>=2.10.1
Requires-Dist: numpy<=3,>=1.24.2; python_version < "3.12"
Requires-Dist: numpy<=3,>=2.0.2; python_version >= "3.12"
Requires-Dist: pendulum<4.0.0,>=3.0.0
Requires-Dist: psutil<6.0,>=5.9.4
Requires-Dist: pytest<9.0,>=8.3.3
Requires-Dist: sortedcontainers<3.0,>=2.4.0
Requires-Dist: typing_extensions<5.0,>=4.16.0
Provides-Extra: web-api
Requires-Dist: Flask<4.0,>=2.2.3; extra == "web-api"
Requires-Dist: Flask-Cors<4.0,>=3.0.10; extra == "web-api"
Requires-Dist: gunicorn<22.0,>=21.0; extra == "web-api"
Requires-Dist: Werkzeug<4.0,>=2.2.3; extra == "web-api"
Provides-Extra: template
Requires-Dist: openfisca-country-template<9,>=8; extra == "template"
Requires-Dist: openfisca-extension-template<3,>=2.0.7; extra == "template"
Dynamic: license-file

# OpenFisca Core

[![PyPi Downloads](https://img.shields.io/pypi/dm/openfisca-core?label=pypi%2Fdownloads&style=for-the-badge)](https://pepy.tech/project/openfisca-core)
[![PyPi Version](https://img.shields.io/pypi/v/openfisca-core.svg?label=pypi%2Fversion&style=for-the-badge)](https://pypi.python.org/pypi/openfisca-core)

[![Python](https://img.shields.io/pypi/pyversions/openfisca-core.svg?label=python&style=for-the-badge)](https://pypi.python.org/pypi/openfisca-core)
[![Contributors](https://img.shields.io/github/contributors/openfisca/openfisca-core.svg?style=for-the-badge)](https://github.com/openfisca/openfisca-core/graphs/contributors)

[![Newsletter](https://img.shields.io/badge/newsletter-subscribe!-informational.svg?style=for-the-badge)](mailto:contact%40openfisca.org?subject=Subscribe%20to%20your%20newsletter%20%7C%20S'inscrire%20%C3%A0%20votre%20newsletter&body=%5BEnglish%20version%20below%5D%0A%0ABonjour%2C%0A%0AVotre%C2%A0pr%C3%A9sence%C2%A0ici%C2%A0nous%C2%A0ravit%C2%A0!%20%F0%9F%98%83%0A%0AEnvoyez-nous%20cet%20email%20pour%20que%20l'on%20puisse%20vous%20inscrire%20%C3%A0%20la%20newsletter.%20%0A%0AAh%C2%A0!%20Et%20si%20vous%20pouviez%20remplir%20ce%20petit%20questionnaire%2C%20%C3%A7a%20serait%20encore%20mieux%C2%A0!%0Ahttps%3A%2F%2Fgoo.gl%2Fforms%2F45M0VR1TYKD1RGzX2%0A%0AAmiti%C3%A9%2C%0AL%E2%80%99%C3%A9quipe%20OpenFisca%0A%0A%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%20ENGLISH%20VERSION%20%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%0A%0AHi%2C%20%0A%0AWe're%20glad%20to%20see%20you%20here!%20%F0%9F%98%83%0A%0APlease%20send%20us%20this%20email%2C%20so%20we%20can%20subscribe%20you%20to%20the%20newsletter.%0A%0AAlso%2C%20if%20you%20can%20fill%20out%20this%20short%20survey%2C%20even%20better!%0Ahttps%3A%2F%2Fgoo.gl%2Fforms%2FsOg8K1abhhm441LG2%0A%0ACheers%2C%0AThe%20OpenFisca%20Team)
[![Twitter](https://img.shields.io/badge/twitter-follow%20us!-9cf.svg?style=for-the-badge)](https://twitter.com/intent/follow?screen_name=openfisca)
[![Slack](https://img.shields.io/badge/slack-join%20us!-blueviolet.svg?style=for-the-badge)](mailto:contact%40openfisca.org?subject=Join%20you%20on%20Slack%20%7C%20Nous%20rejoindre%20sur%20Slack&body=%5BEnglish%20version%20below%5D%0A%0ABonjour%2C%0A%0AVotre%C2%A0pr%C3%A9sence%C2%A0ici%C2%A0nous%C2%A0ravit%C2%A0!%20%F0%9F%98%83%0A%0ARacontez-nous%20un%20peu%20de%20vous%2C%20et%20du%20pourquoi%20de%20votre%20int%C3%A9r%C3%AAt%20de%20rejoindre%20la%20communaut%C3%A9%20OpenFisca%20sur%20Slack.%0A%0AAh%C2%A0!%20Et%20si%20vous%20pouviez%20remplir%20ce%20petit%20questionnaire%2C%20%C3%A7a%20serait%20encore%20mieux%C2%A0!%0Ahttps%3A%2F%2Fgoo.gl%2Fforms%2F45M0VR1TYKD1RGzX2%0A%0AN%E2%80%99oubliez%20pas%20de%20nous%20envoyer%20cet%20email%C2%A0!%20Sinon%2C%20on%20ne%20pourra%20pas%20vous%20contacter%20ni%20vous%20inviter%20sur%20Slack.%0A%0AAmiti%C3%A9%2C%0AL%E2%80%99%C3%A9quipe%20OpenFisca%0A%0A%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%20ENGLISH%20VERSION%20%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%0A%0AHi%2C%20%0A%0AWe're%20glad%20to%20see%20you%20here!%20%F0%9F%98%83%0A%0APlease%20tell%20us%20a%20bit%20about%20you%20and%20why%20you%20want%20to%20join%20the%20OpenFisca%20community%20on%20Slack.%0A%0AAlso%2C%20if%20you%20can%20fill%20out%20this%20short%20survey%2C%20even%20better!%0Ahttps%3A%2F%2Fgoo.gl%2Fforms%2FsOg8K1abhhm441LG2.%0A%0ADon't%20forget%20to%20send%20us%20this%20email!%20Otherwise%20we%20won't%20be%20able%20to%20contact%20you%20back%2C%20nor%20invite%20you%20on%20Slack.%0A%0ACheers%2C%0AThe%20OpenFisca%20Team)

[OpenFisca](https://openfisca.org/doc/) is a versatile microsimulation free software. Check the [online documentation](https://openfisca.org/doc/) for more details.

This package contains the core features of OpenFisca, which are meant to be used by country packages such as [OpenFisca-France](https://github.com/openfisca/openfisca-france). Bootstrapping your own country package should not take more than 5 minutes: check our [country package template](https://github.com/openfisca/country-template).

## Environment

OpenFisca runs on Python. See [pyproject.toml](pyproject.toml) for supported versions.

OpenFisca also relies strongly on NumPy. The last four minor versions should work, but only the latest/stable is tested.

## Installation

If you're developing your own country package, you don't need to explicitly install OpenFisca-Core. It just needs to appear [in your package dependencies](https://github.com/openfisca/openfisca-france/blob/100.0.0/setup.py#L60).
If you want to contribute to OpenFisca-Core itself, welcome!
To install it locally we recommend to use [uv](https://docs.astral.sh/uv/getting-started/).

### Installing `openfisca-core` with `uv`

This installation requires [Python](https://www.python.org/downloads/) and [GIT](https://git-scm.com) installations.

To install `openfisca-core` locally in development mode run the following commands in a shell terminal:

```bash
git clone https://github.com/openfisca/openfisca-core.git
cd openfisca-core
make test
```

## Testing

Install the test dependencies:

```
make install-deps install-edit install-test
```

> For integration testing purposes, `openfisca-core` relies on
> [country-template](https://github.com/openfisca/country-template.git) and
> [extension-template](https://github.com/openfisca/extension-template.git).
> Because these packages rely at the same time on `openfisca-core`, they need
> to be installed separately.

To run the entire test suite:

```sh
make test
```

If you have many tests, you could run them in parallel :
```sh
make test-core openfisca_args="--in-parallel"
```

You could add an option  `--num-workers=4` to limit to 4 threads. Default is your CPU Core number minus 1.

Be aware that this add overhead so use it only for huge test suite.

To run all the tests defined on a test file:

```sh
pytest tests/core/test_parameters.py
```

To run a single test:

```sh
pytest tests/core/test_parameters.py -k test_parameter_for_period
```

## Types

This repository relies on MyPy for optional dynamic & static type checking.

As NumPy introduced the `typing` module in 1.20.0, to ensure type hints do not break the code at runtime, we run the checker against the last four minor NumPy versions.

Type checking is already run with `make test`. To run the type checker alone:

```sh
make check-types
```

## Style

This repository adheres to a [certain coding style](STYLEGUIDE.md), and we invite you to follow it for your contributions to be integrated promptly.

Style checking is already run with `make test`. To run the style checker alone:

```sh
make check-style
```

To automatically style-format your code changes:

```sh
make format-style
```

To automatically style-format your code changes each time you commit:

```sh
touch .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

tee -a .git/hooks/pre-commit << END
#!/bin/bash
#
# Automatically format your code before committing.
# Change .venv/bin/activate if your virtual environment is located elsewhere.
source .venv/bin/activate
exec make format-style
exec make check-style
END
```

## Documentation

OpenFisca’s toolchain checks whether documentation builds correctly and updates it automatically with each contribution to this repository.

In the meantime, please take a look at our [contributing guidelines](CONTRIBUTING.md) for some general tips on how to document your contributions, and at our official documentation's [repository](https://github.com/openfisca/openfisca-doc/blob/main/README.md) to in case you want to know how to build it by yourself —and improve it!

## Serving the API

OpenFisca-Core provides a Web-API. It is by default served on the `5000` port.

To run it with the mock country package `openfisca_country_template` and another port value such as `2000`, run:

```sh
openfisca serve --country-package openfisca_country_template --port 2000
```

To read more about the `openfisca serve` command, check out its [documentation](https://openfisca.org/doc/openfisca-python-api/openfisca_serve.html).

By default, the Web API uses 3 workers to avoid [this issue](http://stackoverflow.com/questions/11150343/slow-requests-on-local-flask-server). Without it, AJAX requests from Chrome sometimes take more than 20s to process. You can change the number of workers by specifying a `--workers k` option.

You can test that the API is running by executing the command:

```sh
curl http://localhost:2000/parameters
```
For more information about endpoints and input formatting, see the [official documentation](https://openfisca.org/doc/openfisca-web-api).
