OpenFisca-France

OpenFisca-France uses a continuous deployment model where new versions are published automatically whenever the legislation code evolves on the master branch.

Key aspects of the versioning strategy:

• Semantic Versioning (SemVer): The project follows SemVer rules. Changes that do not increment the major version are guaranteed to be backward-compatible.
• Compatibility Example: If your application is built for version 13.1.1, it is guaranteed to work with 13.2.0. However, moving to 14.0.0 may require client-side adaptations.
• Change Tracking: All impacts and scopes of changes are documented in the CHANGELOG.md file, which should be used to plan update strategies.

Use this minimal installation method if you want to perform large-scale population calculations, create fiscal simulations, write extensions (like Paris or Rennes), or host your own OpenFisca-France Web API instance. This method installs the package without the source code.

Requirements:

• Python 3.9+
• pip or uv (recommended)

Supported Platforms:

• GNU/Linux (Debian/Ubuntu recommended)
• macOS
• Windows (via WSL recommended; uv is recommended over conda for Windows users)

uv init
uv add openfisca-france
uv add openfisca-core[web-api]

# Verify installation
uv run openfisca -h

Use this advanced installation method if you intend to modify the French legislation or contribute directly to the OpenFisca-France codebase.

Steps:

1. Clone the repository.
2. Verify the installation by running the basic tests.

git clone https://github.com/openfisca/openfisca-france.git
cd openfisca-france

# Verify installation
uv run pytest tests/test_basics.py

You can host the OpenFisca-France Web API on your own server using the uv package manager.

To start the server, run:

uv run openfisca serve

For detailed information regarding the uv run openfisca serve command and its available options, refer to the OpenFisca Python API reference documentation.

Once the server is running, you can explore the available endpoints via the OpenFisca Web API Swagger UI.

OpenFisca-France enforces a specific code style. You can check for style violations or automatically fix them using the provided make commands.

To ensure your contributions are accepted quickly, it is recommended to set up a pre-commit hook that automatically formats your code before every commit.

# Check for style errors
uv run make check-style

# Automatically fix style errors
uv run make format-style

# Setup automatic formatting on git commit
touch .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

tee -a .git/hooks/pre-commit << END
#!/bin/sh
#
# Automatically format your code before committing.
exec make format-style
END

You can query the French tax and benefit system without installing anything by using the public Web API. This is useful for:

• Accessing parameters (e.g., the gross hourly SMIC amount).
• Consulting calculation formulas (e.g., the calculation of the base family allowance).
• Performing calculations on a specific situation (e.g., calculating the cost of labor).

All endpoints are described in the Swagger documentation, which also includes the Legislation Explorer to list all available parameters and variables.

To associate subcommunes (communes associées) with their parent commune depcom codes, you must combine the 20110914_zonage.csv file (which lacks arrondissement and subcommune data) with the INSEE list of communes (france2014.txt) using the extract_arrondissements_and_communes_associees.py script.

1. Obtain france2014.txt from the INSEE website.
2. Run the extraction script to generate a mapping of commune depcom codes by subcommune depcom code.

python extract_subcommunes.py france2014.txt > commune_depcom_by_subcommune_depcom.json

After starting the server, you can verify that it is working correctly by querying a parameter endpoint using curl.

Run the following command to retrieve the hourly minimum wage (SMIC) data:

curl "http://localhost:5000/parameter/marche_travail.salaire_minimum.smic.smic_b_horaire"

You should receive a JSON response containing the parameter description, ID, and a mapping of dates to values (e.g., hourly gross SMIC rates).

To run the test suite, use the make test command. You can run tests in parallel to speed up execution, provided you are using openfisca-core version 44.0.1 or higher.

If the tests consume too much memory, use the --num-workers flag to limit parallel processes.

# Run tests in parallel
uv run make test openfisca_args="--in-parallel"

# Run tests with limited parallel workers
uv run make test openfisca_args="--in-parallel --num-workers 2"

# Run tests with a specific Python version
uv run --python 3.12.3 make test

To upgrade the project's dependencies to their latest compatible versions, use the uv lock command.

uv lock --upgrade