@tricoteuses/assemblee/README.md

Retrieve, clean up & handle French Assemblée nationale's open data

# Tricoteuses-Assemblee

## _Retrieve, clean up & handle French Assemblée nationale's open data_

_Tricoteuses Légifrance_ is free and open source software.

- [software repository](https://git.tricoteuses.fr/logiciels/tricoteuses-assemblee)
- [GNU Affero General Public License version 3 or greater](https://git.tricoteuses.fr/logiciels/tricoteuses-assemblee/-/tree/master/LICENSE.md)

## documentation

- [Architecture](doc/architecture.md)
- [TypeScript API](doc/api/)
  - Main interfaces:
    - [Acteur : personne physique élue ou nommée dans des organes](doc/api/README/interfaces/Acteur.md)
    - [Amendement](doc/api/README/interfaces/Amendement.md)
    - [CompteRendu : compte-rendu d'un débat parlementaire](doc/api/README/interfaces/CompteRendu.md)
    - [Document : texte d'un projet de loi, d'une proposition de loi, d'un rapport, etc](doc/api/README/interfaces/Document.md)
    - [DossierParlementaire : Dossier de suivi d'un projet ou d'une proposition de loi, d'une résolution, etc](doc/api/README/interfaces/DossierParlementaire.md)
    - [Organe : commission, groupe politique, groupe d'étude, groupe d'amitié, etc](doc/api/README/interfaces/Organe.md)
    - [Question : question au Gouvernement](doc/api/README/interfaces/Question.md)
    - [Reunion : séance publique, réunion de commission, de groupe d'étude, etc](doc/api/README/interfaces/Reunion.md)
    - [Scrutin : vote de chaque député lors d'un scrutin public](doc/api/README/interfaces/Scrutin.md)
- [JSON Schemas](src/schemas)

## Requirements

- Node >= 18

## Installation

```bash
git clone https://git.tricoteuses.fr/logiciels/tricoteuses-assemblee
cd tricoteuses-assemblee/
```

```bash
npm install
```

## Download and clean data

### Basic usage

Create a folder where the data will be downloaded and run the following command to download, reorganize and clean the data.

```bash
mkdir ../assemblee-data/

# Download and clean open data
npm run data:download ../assemblee-data
```

Data from other sources is also available :

```bash
# Retrieval of députés' pictures from Assemblée nationale's website
npm run data:retrieve_deputes_photos ../assemblee-data

# Retrieval of sénateurs' pictures from Assemblée nationale's website
npm run data:retrieve_senateurs_photos ../assemblee-data

# Retrieval of pending amendments from Assemblée nationale's website (waiting to be processed by Assemblée services)
npm run data:retrieve_pending_amendements ../assemblee-data
```

_Notes_:

- Reorganized files (generated by the _data:reorganize_data_ command) are also available in [Tricoteuses / Data / Données brutes de l'Assemblée](https://git.en-root.org/tricoteuses/data/assemblee-brut). They are updated on a regular basis.
- Split & cleaned files (generated by the _data:clean_data_ command) are also available in [Tricoteuses / Data / Données nettoyées de l'Assemblée](https://git.en-root.org/tricoteuses/data/assemblee-nettoye) with the `_nettoye` suffix. They are updated on a regular basis.

### Filtering options

Downloading and cleaning all the data is long and takes up a lot of disk space. It is possible to choose the type of data that you want to retrieve to reduce the load.

To download only a type of dataset, use the _--categories_ option (shortcut _-k_) :

```bash
# Available options : ActeursEtOrganes, Agendas, Amendements, DossiersLegislatifs, Photos, Scrutins, Questions, ComptesRendusSeances
npm run data:download ../assemblee-data -- --categories Amendements
```

To download a specific or multiple legislatures, use the *--legislature* option (shortcut *-l*):
```bash
# Available options : 14, 15, 16, 17
npm run data:download ../assemblee-data -- -l 16 -l 17

```

If you use such options, use them in all subsequent commands too (_data:regorganize_data_ and _data:clean_data_).

## Download using Docker

A Docker image that downloads and cleans the data all at once is available. Build it locally or run it from the container registry.
Use the environment variables `LEGISLATURE` and `CATEGORIES` if needed.

```bash
docker run --pull always --name tricoteuses-assemblee -v ../assemblee-data:/app/assemblee-data -e LEGISLATURE=17 -d git.tricoteuses.fr/logiciels/tricoteuses-assemblee:latest
```

## Using the data

Once the data is downloaded and cleaned, you can use loaders to retrieve it.
To use loaders in your project, you can install the _@tricoteuses/assemblee_ package, and import the iterator functions that you need.

```bash
npm install @tricoteuses/assemblee
```

```js
import {
  iterLoadAssembleeActeurs,
  iterLoadAssembleeOrganes,
  iterLoadAssembleeReunions,
  iterLoadAssembleeScrutins,
  iterLoadAssembleeDocuments,
  iterLoadAssembleeDossiersParlementaires,
  iterLoadAssembleeAmendements,
  iterLoadAssembleeQuestions,
  iterLoadAssembleeComptesRendus,
} from "@tricoteuses/assemblee/loaders";

// Pass data directory and legislature as arguments
for (const { acteur } of iterLoadAssembleeActeurs("../assemblee-data", 17)) {
  console.log(acteur.uid)
}
```

## Generating schemas and documentation (for contributors only)

View instructions [here](https://git.tricoteuses.fr/logiciels/tricoteuses-assemblee/-/blob/master/src/types)