Refactor: Updating geographic reference data (#21)

# Context

* In reference to issue #17, according to the Code Officiel Géographique
(COG) a reference document published by l’Institut national de la
statistique et des études économiques (Insee) which brings the
codifications of a series of Insee codes, constituting some of the
geographical codes of France.

* Typically each year, these codes/data change over time. As a result,
certain values may be valid in the COG for 2023 but become invalid in
the COG for 2024 for example.

* The purpose of this PR is to validate a given value against a
specified given COG, representing the year of the Code Officiel
Géographique's publication (In this case we have juste the reference
data of 2023 and 2024) .

Example: `Pays(Millesime.A2023).is_valid("Mayotte")`


# Refactoring
* canton, commune, département, numéro département,  pays, région
* code commune insee, code pays, code région

# Other thoughts

* Despite a great overlap between code_commune sets for 2023, and 2024,
the two sets have been defined separately by now. In the future, and
with the extension to new vintages (Millésimes), there will be a need to
optimize the memory usage.
* There is a need to find a reliable data source for _lower-case_
country (pays) lists for each COG, as the official list seems to be all
uppercase.
* Postal codes are not covered by Insee's COG but by La Poste (see [open
data
page](https://www.data.gouv.fr/fr/datasets/base-officielle-des-codes-postaux/#/information)).
No change has been done on this yet.

---------

Co-authored-by: Pierre Camilleri <[email protected]>

Makefile

@@ -33,5 +33,5 @@ test: ## Runs all tests
 	@ poetry run pytest
 
 .PHONY: generate-docs
-generate-docs: ## Generate validators.md documentation
+generate-docs: ## Generate formats.md documentation
 	@ poetry run python3 ./utils/generate_docs.py

docs/formats.md

@@ -2,19 +2,19 @@
 
 | class name                   | name                   | decription                    |
 | ---------------------------- | ---------------------- | ----------------------------- |
-| Canton | Nom de canton | Vérifie que le nom de canton est un canton ou pseudo-canton français valide |
-| CodeCommuneInsee | Code commune INSEE | Vérifie que le code commune correspond bien à un code commune INSEE |
+| Canton | Nom de canton | Vérifie que le nom de canton est un canton ou pseudo-canton français valide pour un Code Officiel Géographique donné |
+| CodeCommuneInsee | Code commune INSEE | Vérifie que le code commune correspond bien à un code commune INSEE pour un Code Officiel Géographique donné |
 | CodeFantoir | Code fantoir | Vérifie les codes fantoirs valides |
-| CodePaysISO2 | Codes ISO2 Pays | Code ISO 2 de pays selon COG2024 |
-| CodePaysISO3 | Codes ISO3 Pays | Code ISO 3 de pays selon COG2024 |
+| CodePaysISO2 | Codes ISO2 Pays | Code ISO 2 de pays pour un Code Officiel Géographique donné |
+| CodePaysISO3 | Codes ISO3 Pays | Code ISO 3 de pays pour un Code Officiel Géographique donné |
 | CodePostal | Code postal | Vérifie que le code postal est bien un code postal français |
-| CodeRegion | Code région | Vérifie qu'il s'agit d'un code région selon le code officiel géographique 2024 |
-| Commune | Nom de commune | Vérifie que le nom correspond à un nom de commune française (ne vérifie pas l'accentuation, la casse, la ponctuation) |
+| CodeRegion | Code région | Vérifie qu'il s'agit d'un code région pour un Code Officiel Géographique donné |
+| Commune | Nom de commune | Vérifie que le nom correspond à un nom de commune française pour un Code Officiel Géographique donné(ne vérifie pas l'accentuation, la casse, la ponctuation) |
 | CoordonneesGPSFrancaises | Coordonnées GPS françaises | Check that GPS coordinates are in a bounding box approximating France (including DOM) |
-| Departement | Nom de département | Vérifie les départements français valides (code officiel géographique 2020) |
+| Departement | Nom de département | Vérifie les départements français, collectivités et territoires d'outre-mer valides pour un Code Officiel Géographique donné |
 | NomenclatureActe | Nomenclature des actes | Document de référence dans les spécifications SCDL :<br>        http://www.moselle.gouv.fr/content/download/1107/7994/file/nomenclature.pdf<br><br>        Dans la nomenclature Actes, les valeurs avant le '/' sont :<br><br>        Commande publique<br>        Urbanisme<br>        Domaine et patrimoine<br>        Fonction publique<br>        Institutions et vie politique<br>        Libertés publiques et pouvoirs de police<br>        Finances locales<br>        Domaines de compétences par thèmes<br>        Autres domaines de compétences<br><br>        La validation devra accepter minuscules et majuscules, accents et sans accents ... |
-| NumeroDepartement | Numéro du département | Vérifie que le numéro de département correspond bien à un numéro de département français |
-| Pays | Pays et territoires étrangers | Nom de pays et territoires étrangers selon COG2024 |
-| Region | Nom de région | Vérifie les régions françaises valides (code officiel géographique 2020) |
+| NumeroDepartement | Numéro du département | Vérifie que le numéro de département correspond bien à un numéro de département français, collectivités et territoires d'outre-mer pour un Code Officiel Géographique donné |
+| Pays | Pays et territoires étrangers | Nom de pays et territoires étrangers pour un Code Officiel Géographique donné |
+| Region | Nom de région | Vérifie les régions françaises valides pour un Code Officiel Géographique donné |
 | Siren | SIREN | Check french SIREN number validity, but does not check if SIREN number exists. |
 | Siret | SIRET | Check french SIRET number validity, but does not check if SIRET number exists. |

src/frformat/geo/canton.py

@@ -1,9 +1,13 @@
-from frformat import enum_format
-from frformat.geo.canton_set import CANTON_SET
+from typing import Dict, Set
 
-name = "Nom de canton"
-description = (
-    "Vérifie que le nom de canton est un canton ou pseudo-canton français valide"
-)
+from frformat import geo_enum_format
+from frformat.geo.canton_set import CANTON_SET_COG_2023, CANTON_SET_COG_2024
+from frformat.geo_enum_format import Millesime
 
-Canton = enum_format.new("Canton", name, description, CANTON_SET)
+name = "Nom de canton"
+description = "Vérifie que le nom de canton est un canton ou pseudo-canton français valide pour un Code Officiel Géographique donné"
+all_cog_versions: Dict[Millesime, Set[str]] = {
+    Millesime.A2023: CANTON_SET_COG_2023,
+    Millesime.A2024: CANTON_SET_COG_2024,
+}
+Canton = geo_enum_format.new("Canton", name, description, all_cog_versions)