OpenFisca-France-Dotations-Locales 6.1.0

[EN] OpenFisca Rules as Code model for France State endowments to local authorities. [FR] Modèle de microsimulation OpenFisca dédié aux dotations de l'État aux collectivités territoriales.

OpenFisca-France-Dotations-Locales

[EN] Introduction

OpenFisca is a versatile microsimulation free software. This repository contains the OpenFisca model of the State endowments to local authorities in France. Therefore, the working language here is French. You can however check the general OpenFisca documentation in English!

[FR] Introduction

OpenFisca est un logiciel libre de micro-simulation. Ce dépôt contient la modélisation des dotations de l'État aux collectivités territoriales. Pour plus d'information sur les fonctionnalités et la manière d'utiliser OpenFisca, vous pouvez consulter la documentation générale.

Sommaire

• Pré-requis d'installation
  • Installation du gestionnaire de paquets Python uv
• Installation d'OpenFisca-France-Dotations-Locales
  • A. Installation minimale (sans modification de la librairie)
    • Installer OpenFisca-France-Dotations-Locales (wheel)
    • Prochaines étapes
  • B. Installation avancée (GIT clone)
    • Cloner OpenFisca-France-Dotations-Locales avec Git
    • Prochaines étapes
• Tests
• Style
• Servir OpenFisca-France-Dotations-Locales avec l'API Web OpenFisca
• Stratégie de versionnement
• Contributeurs
• Références

Pré-requis d'installation

Ce paquet requiert Python 3.11 et nous conseillons l'emploi du gestionnaire de paquets et d'environnements Python uv.

uv vous permettra en particulier :

• d'assurer une installations dans un environnement virtuel dédié à OpenFisca-France-Dotations-Locales
• de gérer d'éventuelles évolutions de versions de Python.

Installation du gestionnaire de paquets Python uv

Le mode d'installation conseillé d'uv dépend de votre système d'exploitation :

Sur Linux et macOS :

Cette installation s'applique également si vous êtes sur Windows et utiliserez ce dépôt via WSL (Windows Subsystem for Linux).
Sur macOS et si vous employez le gestionnaire de paquets Homebrew, vous pouvez remplacer la commande curl proposée par la commande brew install uv.

curl -LsSf https://astral.sh/uv/install.sh | sh

Sur Windows :

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Pour toute question complémentaire sur l'installation d'uv, consulter la documentation d'installation officielle de l'outil.

Bravo 🎉 Vous êtes prêt·e à installer OpenFisca-France-Dotations-Locales !

Installation d'OpenFisca-France-Dotations-Locales

Nous proposons deux procédures d'installation. Choisissez l'installation A ou B ci-dessous en fonction de l'usage que vous souhaitez faire d'OpenFisca-France-Dotations-Locales.

Dans les deux cas, un environnement virtuel sera créé pour le dépôt. La procédure s'appuye sur l'environnement virtuel par défaut d'uv : un répertoire .venv/ sera créé à la racine de votre répertoire courant.

Afin de s'assurer de la version de Python choisie pour votre environnement virtuel, créer l'environnement virtuel en spécifiant explicitement la version souhaitée (ici 3.11) :

$ uv venv --python 3.11

Vous pouvez ensuite identifier le chemin de la version de la commande Python qui sera réellement employée avec :

$ uv python find
/Users/you/Documents/openfisca-france-dotations-locales/.venv/bin/python3  # exemple de réponse

De cet exemple, on peut retirer un chemin vers python3 et dans ce contexte, voici une commande permettant d'obtenir la version précise exécutée (sans déclencher d'installation complémentaire) : /Users/you/Documents/openfisca-france-dotations-locales/.venv/bin/python3 --version

A. Installation minimale (sans modification de la librairie)

Suivez cette installation si vous souhaitez :

• procéder à des calculs sur toutes les collectivités ;
• créer des simulations des dotations ;
• écrire une extension s'appuyant sur cette législation française nationale ;
• servir OpenFisca-France-Dotations-Locales avec l'API Web OpenFisca.

Pour pouvoir modifier OpenFisca-France-Dotations-Locales, consultez l'Installation avancée.

Installer OpenFisca-France-Dotations-Locales (wheel)

À cette étape nous considérons que vous avez initialisé un environnement virtuel tel que décrit ci-dessus. Cet environnement est enocre vide :

$ uv pip list
# on s'attend à une réponse vide indiquant qu'aucune dépendance n'a été installée

Installez OpenFisca-France-Dotations-Locales :

uv sync --no-dev --no-editable

où :

• --no-dev indique qu'on ne souhaite pas installer les dépendances auxilières du groupe dev dédiées à un usage en mode développement (modification de la librairie)
• --no-editable indique que l'on choisit d'installer la librairie (wheel) et non pas son code source en mode éditable

Il est possible d'observer les dépendances installées avec la commande suivante (les versions indiquées pourront évoluer dans le temps) :

$ uv pip list
Package                            Version
---------------------------------- -----------
...
flask                              2.3.3   # librairie permettant d'exécuter l'API web standard d'openfisca (via openfisca-core)
flask-cors                         3.0.10
gunicorn                           21.2.0
...
numpy                              1.24.4  # librairie au coeur du calcul openfisca
openfisca-core                     41.5.7
openfisca-france-dotations-locales 5.1.0   # librairie du calcul des dotations
...

Félicitations 🎉 OpenFisca-France-Dotations-Locales est prêt à être utilisé !

Prochaines étapes

• Apprenez à utiliser OpenFisca avec nos tutoriels (en anglais).
• Simulez le calcul des dotations avec les données officielles de la Direction générale des collectivités locales.
• Hébergez et servez votre instance d'OpenFisca-France-Dotations-Locales avec l'API Web OpenFisca.

En fonction de vos projets, vous pourriez bénéficier de l'installation des paquets suivants dans votre environnement virtuel :

• pour installer une extension ou écrire une législation au-dessus d'OpenFisca-France-Dotations-Locales, consultez la documentation sur les extensions (en anglais) ;
• pour représenter graphiquement vos résultats, essayez la bibliothèque matplotlib ;
• pour gérer vos données, découvrez la bibliothèque pandas.

B. Installation avancée (GIT clone)

Suivez cette installation si vous souhaitez :

• enrichir ou modifier la législation d'OpenFisca-France-Dotations-Locales ;
• contribuer au code source d'OpenFisca-France-Dotations-Locales.

Cloner OpenFisca-France-Dotations-Locales avec Git

Premièrement, assurez-vous que le logiciel de gestion de versions Git est bien installé sur votre machine.

Puis, récupérez une version du code sur votre machine en clonant OpenFisca-France-Dotations-Locales en local :

$ git clone [e-mail]:leximpact/simulateur-dotations-communes/openfisca-france-dotations-locales.git
$ cd openfisca-france-dotations-locales

où l'URL indiquée pour la librairie vous permettra un clone avec SSH.
ℹ️ Lorsque vous souhaiterez proposer des contributions à la librairie, une clef SSH personnelle devra être associée à votre compte et connue du GitLab git.leximpact.dev.

Installer les dépendances d'OpenFisca-France-Dotations-Locales

À cette étape nous considérons que vous avez initialisé un environnement virtuel tel que décrit plus haut. Cet environnement est enocre vide :

$ uv pip list
# on s'attend à une réponse vide indiquant qu'aucune dépendance n'a été installée

Pour installer OpenFisca-France-Dotations-Locales de manière à ce que vos éventuelles modifications de code soient prises en compte à l'exécution, nous l'installons en mode "éditable" et on inclut les dépendances utiles au développement :

uv sync --group dev --upgrade

Il est possible d'observer les dépendances installées avec la commande suivante (les versions indiquées pourront évoluer dans le temps) :

$ uv pip list
Package                            Version      Editable project location
---------------------------------- ------------ --------------------------------------------------------
...
flake8                             6.1.0   # librairie de vérification du style de code typique d'un usage en mode développement
flask                              2.3.3   # librairie permettant d'exécuter l'API web standard d'openfisca (via openfisca-core)
flask-cors                         3.0.10
...
gunicorn                           21.2.0
...
numpy                              1.24.4  # librairie au coeur du calcul openfisca
openfisca-core                     41.5.7
openfisca-france-dotations-locales 5.1.0        /Users/you/Documents/openfisca-france-dotations-locales   # librairie du calcul des dotations en mode éditable
...

Vous pouvez vous assurer que votre installation s'est bien passée en exécutant des tests.

Tester la bonne installation d'OpenFisca-France-Dotations-Locales

ℹ️ Toute commande que vous souhaiterez exécuter dans l'environnement virtuel, espace qui a connaissance des dépenances, devra être préfixée par uv run.

On favorise donc ici l'emploi d'uv run à l'activation de l'environnement virtuel par source .venv/bin/activate. Ceci se reflète en particulier dans le fichier Makefile qui vous offre des raccourcis vers les commandes les plus courantes.

Par exemple, ce test peut être exécuté :

$ uv run pytest tests/test_base.py 
============================= test session starts ==============================
platform darwin -- Python 3.11.13, pytest-8.4.2, pluggy-1.6.0
rootdir: /Users/you/Documents/openfisca-france-dotations-locales
configfile: pyproject.toml
plugins: anyio-4.12.1
collected 1 item                                                               

tests/test_base.py .                                                     [100%]

============================== 1 passed in 11.27s ==============================

🎉 OpenFisca-France-Dotations-Locales est prêt à être utilisé !

Prochaines étapes

• Pour enrichir ou faire évoluer la législation d'OpenFisca-France-Dotations-Locales, consulter Coding the Legislation (en anglais).
• Pour contribuer au code, consulter le Contribution Guidebook (en anglais) ainsi que le fichier de contribution de ce dépôt.

Tests

Afin de vérifier le résultat de tous les tests d'OpenFisca-France-Dotations-Locales, exécutez la commande suivante qui provient du le fichier Makefile (incluant déjà uv run) :

$ make test

En mode développement, pour exécuter un test unique en affichant les éventuels print lorsqu'il échoue, l'option -v doit être ajoutée. Par exemple :

$ uv run openfisca test -v tests/dotation_amenagement_communes_outre_mer/montant.yaml -n "Calcul du montant total de l'enveloppe DACOM"

Style

Ce dépôt adhère à un style de code précis, et on vous invite à le suivre pour que vos contributions soient intégrées au plus vite. L'analyse de style est déjà exécutée avec make test. Pour le faire tourner de façon indépendante :

$ make check-style

Puis, pour corriger les erreurs de style de façon automatique :

$ make format-style

Pour corriger les erreurs de style de façon automatique à chaque fois que vous faites un commit vous pouvez appliquer cette configuration :

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

Servir OpenFisca-France-Dotations-Locales avec l'API Web OpenFisca

Après avoir installé les dépendances additionnelles nécessaires à l'API Web, il est possible de servir OpenFisca-France-Dotations-Locales sur votre propre serveur avec :

$ uv run openfisca serve --country-package openfisca_france_dotations_locales --port 5000

Ou utilisez la commande pré-configurée :

make serve-local

Pour en savoir plus sur la commande openfisca serve et ses options, consultez la documentation de référence.

Testez votre installation depuis un second terminal et par requête avec la commande suivante :

curl "http://localhost:5000/spec"

Ou tester, depuis un seond terminal, un calcul sur un exemple déjà fourni avec :

curl -X POST -H "Content-Type: application/json" \
  -d @./openfisca_france_dotations_locales/situation_examples/communes_dsr.json \
  http://localhost:5000/calculate

🎉 Vous servez OpenFisca-France-Dotations-Locales via l'API Web OpenFisca !

Vous pouvez activer le suivi des visites sur votre instance via Matomo avec le Tracker API OpenFisca (en anglais).

Stratégie de versionnement

En complément de ce qui est déjà indiqué en anglais par le fichier de contribution.

Le code d'OpenFisca-France-Dotations-Locales est déployé de manière continue et automatique. Ainsi, à chaque fois que le code de la législation évolue sur la branche principale master, une nouvelle version est publiée.

De nouvelles versions sont donc publiées très régulièrement. Cependant, la différence entre deux versions consécutives étant réduite, les efforts d'adaptation pour passer de l'une à l'autre sont en général très limités.

Par ailleurs, OpenFisca-France-Dotations-Locales respecte les règles du versionnement sémantique. Tous les changements qui ne font pas l'objet d'une augmentation du numéro majeur de version sont donc garantis rétro-compatibles.

Par exemple, si mon application utilise la version 13.1.1, je sais qu'elle fonctionnera également avec la version 13.2.0. En revanche, il est possible qu'une adaptation soit nécessaire sur mon client pour pouvoir utiliser la version 14.0.0.

Enfin, les impacts et périmètres des évolutions sont tous documentés sur le CHANGELOG du package. Ce document permet aux contributeurs de suivre les évolutions et d'établir leur propre stratégie de mise à jour.

Contributeurs

Voir la liste des contributeurs.

Références

Ce code a été initialisé grâce aux travaux réalisés dans ces différents dépôts :

• travaux au hackathon #dataFin
• openfisca-collectivites-territoriales par @guillett
• analyse de la DSR par @magemax
• template du moteur openfisca

Il a été ou est réutilisé par :

• leximpact-server (LexImpact, Assemblée nationale) (jusqu'aux dotations 2021 et Projet de loi de finances 2022)
• dotations-locales-back (Incubateur des territoires, Agence nationale de la cohésion des territoires) (jusqu'aux dotations 2023)
• leximpact-dotations-back (LexImpact, Assemblée nationale) (à partir des dotations 2024)

Par ailleurs, ce code peut être testé avec les données ouvertes officielles de la Direction générale des collectivités locales (DGCL). Ceci est par exemple réalisé dans le dépôt data-exploration (LexImpact, Assemblée nationale) (succède à data-exploration, Incubateur des territoires de l'Agence nationale de la cohésion des territoires).