decoupage_administratif 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04b92f3a97be9ce20975c76881ed509aa608d086ffe3782e433b59ac09d2bcc9
+  data.tar.gz: 7006ac29d38e8ddb3d96b2959c9b77256a3949ae295020e0eb90461d0f33d36a
+SHA512:
+  metadata.gz: 3c92fc51aa2605f90ec9bf5f7b60e5b42b3acd8f1b0d06792dba10e22bd26daa354e2b4aff324b19e35b2d30fb3ce2611169400ae7dca0f4eb993723d39d72de
+  data.tar.gz: af795631f1346c222f2533a5a269557aed1305240bb2f25ff207f96a8298cf0d9db8fa03525f2acec7bf91889758b0a13492d620db157c3b274c443a74d31f92

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,55 @@
+require:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'db/schema.rb'
+    - 'bin/*'
+    - 'pkg/**/*'
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+# RSpec specific configurations
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NamedSubject:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/SpecFilePathFormat:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-26
+
+### Added
+- Initial release of the DecoupageAdministratif gem
+- Support for French administrative divisions:
+  - **Communes**: Access to 35,000+ French municipalities with codes, names, and types
+  - **Départements**: All French departments with their communes
+  - **Régions**: All French regions with departments and communes
+  - **EPCIs**: Intercommunal cooperation establishments with member communes
+- Query API inspired by ActiveRecord:
+  - `find(code)`: Find by code, raises error if not found
+  - `find_by(attribute: value)`: Find first match, returns nil if not found
+  - `where(criteria)`: Filter with exact or partial matching
+  - `all`: Get all records
+- Advanced search capabilities:
+  - Search territories by INSEE codes
+  - Find complete territories (departments, regions, EPCIs) from commune codes
+  - Support for partial matching and case-insensitive searches
+- Territory intersection methods:
+  - `territory_intersects_with_insee_codes?`: Check if territory contains any of the given INSEE codes
+  - `territory_insee_codes`: Get all INSEE codes for a territory
+- Flexible data configuration:
+  - Embedded data files included in the gem
+  - Optional custom data directory via `DECOUPAGE_DATA_DIR` environment variable
+  - Automatic fallback to user directory or Rails tmp
+  - Rake task to update data from official @etalab/decoupage-administratif package
+- Performance optimizations:
+  - Class-level caching for communes and departments
+  - Efficient search algorithms for large datasets
+- Full test coverage with RSpec
+- YARD documentation for all public methods
+- RBS type signatures for type safety
+- Rubocop linting configuration

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Lucien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,320 @@
+# DecoupageAdministratif
+English version below
+
+Gem Ruby permettant d’accéder facilement aux données du découpage administratif français (régions, départements, communes, EPCI) à partir des jeux de données de Datagouv : <https://github.com/datagouv/decoupage-administratif>.
+
+## Territoires couverts 
+- Régions
+- Départements
+- Communes
+- EPCI (Établissements Publics de Coopération Intercommunale)
+
+## Installation
+
+Ajoutez la gem à votre Gemfile :
+
+    bundle add decoupage_administratif
+
+Ou installez-la directement :
+
+    gem install decoupage_administratif
+
+Mise à jour des données (optionnel) :
+
+    rake decoupage_administratif:update
+
+### Configuration
+
+**Données embarquées :** La gem inclut maintenant les données par défaut et fonctionne directement sans installation additionnelle.
+
+**Données personnalisées :** Vous pouvez utiliser des données plus récentes en les téléchargeant :
+
+```bash
+# Mettre à jour vers les dernières données (optionnel)
+rake decoupage_administratif:update
+```
+
+**Répertoire personnalisé :**
+```bash
+# Via variable d'environnement
+export DECOUPAGE_DATA_DIR=/path/to/your/data/directory
+rake decoupage_administratif:update
+```
+
+```ruby
+# Via code (pour Rails)
+# config/initializers/decoupage_administratif.rb
+DecoupageAdministratif::Config.data_directory = Rails.root.join('tmp', 'decoupage_data')
+```
+
+**Ordre de priorité :**
+1. Données dans le répertoire personnalisé (`DECOUPAGE_DATA_DIR`)
+2. Données dans `~/.local/share/decoupage_administratif/`
+3. **Données embarquées dans la gem** (fallback automatique)
+
+## Utilisation
+
+Exemple d’utilisation basique :
+
+```ruby
+# Lister toutes les régions
+DecoupageAdministratif::Region.all
+
+# Trouver une commune par code INSEE
+# Une commune a un commune_type qui peut être `commune-actuelle`, `commune-deleguee` (anciennes communes) ou `commune-associee` (anciennes communes avec un statut spécial)
+commune = DecoupageAdministratif::Commune.find('75056')
+puts commune.nom # => "Paris"
+
+# Lister les départements d'une région
+DecoupageAdministratif::Region.find('84').departements
+
+# Lister toutes les communes actuelles d’un département
+departement = DecoupageAdministratif::Departement.find('72')
+puts departement.communes
+
+# Trouver un EPCI par son SIREN
+epci = DecoupageAdministratif::Epci.find('200054781')
+puts epci.nom
+
+# Lister les communes d’un EPCI
+puts epci.communes
+
+# Rechercher une commune par nom (insensible à la casse)
+DecoupageAdministratif::Commune.where('paris', case_insensitive: true)
+
+# Lister les départements d'une région
+region = DecoupageAdministratif::Region.find_by(nom: 'Bretagne')
+puts region.departements
+```
+
+### Extensions territoriales
+
+La gem propose des méthodes pour vérifier la correspondance entre territoires et listes de codes INSEE :
+
+```ruby
+# Vérifier si un territoire contient au moins une commune d'une liste
+commune_codes = ['75001', '75002', '69001']
+departement = DecoupageAdministratif::Departement.find('75')
+departement.territory_intersects_with_insee_codes?(commune_codes) # => true
+
+# Obtenir tous les codes INSEE des communes d'un territoire
+departement.territory_insee_codes # => ["75001", "75002", "75003", ...]
+```
+
+## Développement
+
+Build la gem après avoir cloné le dépôt :
+
+    gem build decoupage_administratif.gemspec
+
+Installer la gem localement :
+
+    bundle exec rake install
+
+Vérifier la version installée :
+
+    ruby -r 'decoupage_administratif' -e 'puts DecoupageAdministratif::VERSION'
+
+Mettre à jour les données (optionnel) :
+
+    rake decoupage_administratif:update
+
+Pour lancer les tests :
+
+    rake spec
+
+Pour une console interactive :
+
+    bin/console
+
+Puis importer la gem :
+
+    require 'decoupage_administratif'
+
+Pour publier une nouvelle version :
+
+- Mettez à jour le numéro de version dans `lib/decoupage_administratif/version.rb`
+- Exécutez :
+
+      bundle exec rake release
+
+### Yard
+
+Cette gem utilise [Yard](https://yardoc.org/) pour la documentation. Pour générer la documentation, exécutez :
+
+    yard doc
+
+pour lancer le serveur de documentation, exécutez :
+
+    yard server
+
+Vous pouvez ensuite accéder à la documentation à l'adresse : <http://localhost:8808>.
+
+## Contribution
+
+Les issues et pull requests sont les bienvenues sur : <https://github.com/BetaGouv/decoupage_administratif>
+
+## Licence
+
+Ce projet est sous licence [MIT](https://opensource.org/licenses/MIT).
+
+Données : © Etalab, disponibles sous licence ouverte.
+
+## English version
+
+Ruby gem to easily access French administrative division data (regions, departments, municipalities, EPCI) from official datasets: <https://github.com/datagouv/decoupage-administratif>.
+
+## Covered territories
+- Regions
+- Departments
+- Municipalities (communes)
+- EPCI (Public Establishments for Inter-municipal Cooperation)
+
+## Installation
+
+Add the gem to your Gemfile:
+
+    bundle add decoupage_administratif
+
+Or install it directly:
+
+    gem install decoupage_administratif
+
+Update data files (optional):
+
+    rake decoupage_administratif:update
+
+### Configuration
+
+**Embedded data:** The gem now includes default data and works directly without additional installation.
+
+**Custom data:** You can use more recent data by downloading it:
+
+```bash
+# Update to latest data (optional)
+rake decoupage_administratif:update
+```
+
+**Custom directory:**
+```bash
+# Via environment variable
+export DECOUPAGE_DATA_DIR=/path/to/your/data/directory
+rake decoupage_administratif:update
+```
+
+```ruby
+# Via code (for Rails)
+# config/initializers/decoupage_administratif.rb
+DecoupageAdministratif::Config.data_directory = Rails.root.join('tmp', 'decoupage_data')
+```
+
+**Priority order:**
+1. Data in custom directory (`DECOUPAGE_DATA_DIR`)
+2. Data in `~/.local/share/decoupage_administratif/`
+3. **Embedded data in the gem** (automatic fallback)
+
+## Usage
+
+Basic usage example:
+
+```ruby
+# List all regions
+DecoupageAdministratif::Region.all
+
+# Find a municipality by INSEE code
+# A municipality has a `commune_type` which can be :commune_actuelle (current municipalities), :commune_deleguee (former municipalities), or :commune_associee (former municipalities with a special status)
+commune = DecoupageAdministratif::Commune.find('75056')
+puts commune.nom # => "Paris"
+
+# List departments of a region
+DecoupageAdministratif::Region.find('84').departements
+
+# List all current municipalities of a department
+departement = DecoupageAdministratif::Departement.find('72')
+puts departement.communes
+
+# Find an EPCI by its SIREN
+epci = DecoupageAdministratif::Epci.find('200054781')
+puts epci.nom
+
+# List municipalities of an EPCI
+puts epci.communes
+
+# Search for a municipality by name (case-insensitive)
+DecoupageAdministratif::Commune.where('paris', case_insensitive: true)
+
+# List departments of a region
+region = DecoupageAdministratif::Region.find_by(nom: 'Bretagne')
+puts region.departements
+```
+
+### Territory extensions
+
+The gem provides methods to check intersections between territories and INSEE code lists:
+
+```ruby
+# Check if a territory intersects with municipality INSEE codes
+commune_codes = ['75001', '75002', '69001']
+departement = DecoupageAdministratif::Departement.find('75')
+departement.territory_intersects_with_insee_codes?(commune_codes) # => true
+
+# Get all INSEE codes of municipalities in a territory
+departement.territory_insee_codes # => ["75001", "75002", "75003", ...]
+```
+
+## Development
+
+Build the gem after cloning the repository:
+    gem build decoupage_administratif.gemspec
+
+Install the gem locally:
+
+    bundle exec rake install
+
+Check the installed version:
+
+    ruby -r 'decoupage_administratif' -e 'puts DecoupageAdministratif::VERSION'
+
+Update the data:
+
+    rake decoupage_administratif:update
+
+To run the tests:
+    rake spec
+
+For an interactive console :
+
+    bin/console
+
+Then import the gem :
+
+    require 'decoupage_administratif'
+
+To publish a new version :
+
+- Update the version number in `lib/decoupage_administratif/version.rb`
+- Run :
+
+      bundle exec rake release
+
+### Yard
+
+This gem uses [Yard](https://yardoc.org/) for documentation. To generate the documentation, run:
+
+    yard doc
+
+to start the documentation server, run:
+
+    yard server
+
+You can then access the documentation at: <http://localhost:8808>.
+
+## Contribution
+
+Issues and pull requests are welcome at : <https://github.com/BetaGouv/decoupage_administratif>
+
+## License
+
+This project is licensed under the [MIT](https://opensource.org/licenses/MIT) license.
+
+Data : © Etalab, available under open license.

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+import "lib/tasks/install.rake"