Metadata-Version: 2.4
Name: OpenFisca-France-Dotations-Locales
Version: 6.0.2
Summary: [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.
Author: Dotations Locales Team, 2022 & 2023 @ Agence nationale de la cohésion des territoires
Author-email: LexImpact Team <leximpact@assemblee-nationale.fr>
Project-URL: Homepage, https://git.leximpact.dev/leximpact/openfisca-france-dotations-locales
Project-URL: Repository, https://git.leximpact.dev/leximpact/openfisca-france-dotations-locales
Project-URL: Documentation, https://openfisca.org/doc
Project-URL: Issues, https://git.leximpact.dev/leximpact/simulateur-dotations-communes/openfisca-france-dotations-locales/-/issues
Project-URL: Changelog, https://git.leximpact.dev/leximpact/simulateur-dotations-communes/openfisca-france-dotations-locales/-/blob/master/CHANGELOG.md
Keywords: rac,rules-as-code,model,microsimulation,France,local,tax,endowment,dotations,territoires
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: OpenFisca-Core[web-api]<42.0,>=27.0
Dynamic: license-file

# OpenFisca-France-Dotations-Locales

[![Twitter](https://img.shields.io/badge/twitter-follow%20us!-9cf.svg?style=flat)](https://twitter.com/intent/follow?screen_name=openfisca)
[![Slack](https://img.shields.io/badge/slack-join%20us!-blueviolet.svg?style=flat)](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)
[![Python](https://img.shields.io/pypi/pyversions/openfisca-france-dotations-locales.svg)](https://pypi.org/project/OpenFisca-France-Dotations-Locales/)
[![PyPi](https://img.shields.io/pypi/v/openfisca-france-dotations-locales.svg?style=flat)](https://pypi.org/project/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](https://openfisca.org/doc/) in English!

## [FR] Introduction

[OpenFisca](https://www.openfisca.fr/) 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](https://openfisca.org/doc/).

## Sommaire

- [Pré-requis d'installation](#pré-requis-dinstallation)
  - [Installation du gestionnaire de paquets Python `uv`](#installation-du-gestionnaire-de-paquets-python-uv)
- [Installation d'OpenFisca-France-Dotations-Locales](#installation-dopenfisca-france-dotations-locales)
  - [A. Installation minimale (sans modification de la librairie)](#a-installation-minimale-sans-modification-de-la-librairie)
    - [Installer OpenFisca-France-Dotations-Locales (wheel)](#installer-openfisca-france-dotations-locales-wheel)
    - [Prochaines étapes](#prochaines-étapes)
  - [B. Installation avancée (GIT clone)](#b-installation-avancée-git-clone)
    - [Cloner OpenFisca-France-Dotations-Locales avec Git](#cloner-openfisca-france-dotations-locales-avec-git)
    - [Prochaines étapes](#prochaines-étapes-1)
- [Tests](#tests)
- [Style](#style)
- [Servir OpenFisca-France-Dotations-Locales avec l'API Web OpenFisca](#servir-openfisca-france-dotations-locales-avec-lapi-web-openfisca)
- [Stratégie de versionnement](#stratégie-de-versionnement)
- [Contributeurs](#contributeurs)
- [Références](#références)

## Pré-requis d'installation

Ce paquet requiert [Python 3.11](https://www.python.org/downloads/release/python-3110/) et nous conseillons l'emploi du gestionnaire de paquets et d'environnements Python [uv](https://docs.astral.sh/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)](https://learn.microsoft.com/fr-fr/windows/wsl/).  
> 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`.

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

**Sur Windows :**

```shell
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](https://www.vie-publique.fr/en-bref/301038-omnibus-numerique-vers-une-simplification-des-regles-de-lue).

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`) :

```sh
$ 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 : 

```sh
$ 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](https://openfisca.org/doc/architecture.html#extensions-packages) s'appuyant sur cette législation française nationale ;
- servir OpenFisca-France-Dotations-Locales avec l'[API Web OpenFisca](https://openfisca.org/doc/openfisca-web-api/index.html).

Pour pouvoir modifier OpenFisca-France-Dotations-Locales, consultez l'[Installation avancée](#b-installation-avancée-git-clone).

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

```sh
$ 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 :

```sh
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) : 
```sh
$ 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](https://openfisca.org/doc/) (en anglais).
- Simulez le calcul des dotations avec les [données officielles de la Direction générale des collectivités locales](http://www.dotations-dgcl.interieur.gouv.fr/consultation/criteres_repartition.php).
- Hébergez et servez votre instance d'OpenFisca-France-Dotations-Locales avec l'[API Web OpenFisca](#servez-openfisca-france-avec-lapi-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](https://openfisca.org/doc/contribute/extensions.html) (en anglais) ;
- pour représenter graphiquement vos résultats, essayez la bibliothèque [matplotlib](http://matplotlib.org/) ;
- pour gérer vos données, découvrez la bibliothèque [pandas](http://pandas.pydata.org/).

### 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](https://www.git-scm.com/) 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 :

```sh
$ git clone git@git.leximpact.dev: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 :
```sh
$ 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 :

```sh
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) :

```sh
$ 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é :
```sh
$ 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](https://openfisca.org/doc/coding-the-legislation/index.html)_ (en anglais).
- Pour contribuer au code, consulter le _[Contribution Guidebook](https://openfisca.org/doc/contribute/index.html)_ (en anglais) ainsi que le [fichier de contribution](./CONTRIBUTING.md) 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](./Makefile) (incluant déjà `uv run`) :

```sh
$ 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 : 

```sh
$ 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 :

```sh
$ make check-style
```

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

```sh
$ 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 :

```sh
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 :

```sh
$ 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](https://openfisca.org/doc/openfisca-python-api/openfisca_serve.html).

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

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

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

```sh
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](https://github.com/openfisca/tracker)_ (en anglais).

## Stratégie de versionnement

> En complément de ce qui est déjà indiqué en anglais par le [fichier de contribution](./CONTRIBUTING.md).

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](http://semver.org/). 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](CHANGELOG.md) 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](https://git.leximpact.dev/leximpact/simulateur-dotations-communes/openfisca-france-dotations-locales/-/graphs/master?ref_type=heads).

## 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](https://github.com/leximpact/dataFin)
* [openfisca-collectivites-territoriales par @guillett](https://github.com/guillett/openfisca-collectivites-territoriales)
* [analyse de la DSR par @magemax](https://github.com/magemax/dsr)
* [template du moteur openfisca](https://github.com/openfisca/country-template)

Il a été ou est réutilisé par : 
* [leximpact-server (LexImpact, Assemblée nationale)](https://git.leximpact.dev/leximpact/simulateur-dotations-communes/leximpact-server) (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)](https://gitlab.com/incubateur-territoires/startups/dotations-locales/dotations-locales-back) (jusqu'aux dotations 2023)
* [leximpact-dotations-back (LexImpact, Assemblée nationale)](https://git.leximpact.dev/leximpact/simulateur-dotations-communes/leximpact-dotations-back) (à partir des dotations 2024)

Par ailleurs, ce code peut être testé avec les [données ouvertes officielles](http://www.dotations-dgcl.interieur.gouv.fr/consultation/criteres_repartition.php) 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)](https://git.leximpact.dev/leximpact/simulateur-dotations-communes/data-exploration) (succède à [data-exploration, Incubateur des territoires de l'Agence nationale de la cohésion des territoires](https://gitlab.com/incubateur-territoires/startups/dotations-locales/data-exploration)).
