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

• Installation
  • Installez un environnement virtuel avec Pew
  • A. Installation minimale (pip install)
    • Installer OpenFisca-France-Dotations-Locales avec pip install
    • 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

Installation

Ce paquet requiert Python 3.11 et pip (ou pip dans un environnement conda).

Plateformes supportées :

• Distributions GNU/Linux (en particulier Debian and Ubuntu) ;
• Mac OS X ;
• Windows : Nous recommandons d'utiliser conda en association avec pip pour la facilité d'installation et sachant que la librairie d'OpenFisca-France-Dotations-Locales est publiée sur PyPi mais pas sur conda. OpenFisca fonctionne également dans le sous-système Windows pour Linux (WSL). Dans ce dernier cas, il suffit de suivre la procédure pour Linux car vous êtes alors dans un environnement Linux.

Pour les autres OS : si vous pouvez exécuter Python et Numpy, l'installation d'OpenFisca devrait fonctionner.

Installez un environnement virtuel avec Pew

Nous recommandons l'utilisation d'un environnement virtuel (virtualenv) avec un gestionnaire de virtualenv tel que Pew. Vous pouvez aussi utiliser le gestionnaire d'environnemnt officiel de Python : venv.

• Un virtualenv crée un environnement pour les besoins spécifiques du projet sur lequel vous travaillez.
• Un gestionnaire de virtualenv, tel que Pew, vous permet de facilement créer, supprimer et naviguer entre différents environnements.

Pour installer Pew, lancez une fenêtre de terminal et suivez ces instructions :

python --version # Python 3.11.0 ou plus récent devrait être installé sur votre ordinateur.
# Si non, téléchargez-le sur http://www.python.org et téléchargez pip.

pip install --upgrade pip
pip install pew

Créez un nouveau virtualenv nommé openfisca et configurez-le avec python 3.11 :

pew new openfisca --python=python3.11
# Si demandé, répondez "Y" à la question sur la modification du fichier de configuration de votre shell

Le virtualenv openfisca sera alors activé, c'est-à-dire que les commandes suivantes s'exécuteront directement dans l'environnement virtuel. Vous verrez dans votre terminal :

Installing setuptools, pip, wheel...done.
Launching subshell in virtual environment. Type 'exit' or 'Ctrl+D' to return.

Informations complémentaires :

• sortez du virtualenv en tapant exit (or Ctrl-D) ;
• re-rentrez en tapant pew workon openfisca dans votre terminal.

Bravo 🎉 Vous êtes prêt·e à installer 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.

A. Installation minimale (pip install)

Suivez cette installation si vous souhaitez :

• procéder à des calculs sur toutes les collectivités ;
• créer des simulations des dotations ;
• écrire une extension au-dessus de la législation française ;
• 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 avec pip install

Dans votre virtualenv, vérifiez les pré-requis :

python --version  # Devrait afficher "Python 3.11.xx".
# Si non, vérifiez que vous passez --python=python3.11 lors de la création de votre environnement virtuel.

pip --version  # Devrait afficher au moins 23.x
# Si non, exécutez "pip install --upgrade pip".

Installez OpenFisca-France-Dotations-Locales :

pip install openfisca-france-dotations-locales && pip install openfisca-core[web-api]

Note: Ou pip install openfisca-france-dotations-locales && pip install openfisca-core[web-api] pour installer l'API Web d'OpenFisca.

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 virtualenv :

• 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 Git est bien installé sur votre machine.

Dans votre virtualenv, assurez-vous que vous êtes dans le répertoire où vous souhaitez cloner OpenFisca-France-Dotations-Locales.

Vérifiez les pré-requis :

python --version  # Devrait afficher "Python 3.11.xx".
# Si non, vérifiez que vous passez --python=python3.11 lors de la création de votre environnement virtuel.

pip --version  # Devrait afficher au moins 23.x
# Si non, exécutez "pip install --upgrade pip".

Clonez OpenFisca-France-Dotations-Locales sur votre machine :

git clone git@git.leximpact.dev:leximpact/simulateur-dotations-communes/openfisca-france-dotations-locales.git
cd openfisca-france-dotations-locales
pip install --editable .[dev]

Note: Ou pip install --editable .[dev] && pip install openfisca-core[web-api] pour installer l'API Web d'OpenFisca.

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

pytest tests/test_base.py # Ces test peuvent prendre jusqu'à 60 secondes.

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

Prochaines étapes

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

Tests

Pour faire tourner les tests d'OpenFisca-France-Dotations-Locales, exécutez la commande suivante qui provient du le fichier Makefile :

make test

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 :

openfisca serve --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 en requêtant la commande suivante :

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

Ou tester 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

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).