@mailwoman/corpus 9.4.0 → 10.1.0

package/out/fr/adapters/annuaire-education/adapter.d.ts

@@ -0,0 +1,236 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `fr-annuaire-education-overseas`: the schools, education offices and guidance centers of France's
+ * overseas jurisdictions, read from the education ministry's Annuaire de l'éducation.
+ *
+ * Input is JSON Lines, one record per line, as the OpenDataSoft export of the dataset
+ * `fr-en-annuaire-education` on `data.education.gouv.fr` serves it at
+ * `/api/explore/v2.1/catalog/datasets/fr-en-annuaire-education/exports/jsonl`. The export keys each
+ * record by the dataset's field names (`nom_etablissement`, `adresse_1`, `adresse_2`, `adresse_3`,
+ * `code_postal`, `nom_commune`, `code_departement`, `etat`), and {@linkcode AnnuaireRecord} declares
+ * the ones this adapter reads. `fetchAnnuaireEducationOverseas` asks the export for the overseas departments
+ * alone, and the adapter filters again, so a whole-country export reads the same.
+ *
+ * ## Which rows are read
+ *
+ * `code_departement` is the three-digit INSEE department: `971` to `976`, `977` Saint-Barthélemy,
+ * `978` Saint-Martin, `986` Wallis-et-Futuna, `987` French Polynesia and `988` New Caledonia. The
+ * jurisdiction is read through `COUNTRY_BY_INSEE_DEPARTMENT`, the table the BAN adapter uses. A
+ * metropolitan row is refused under {@linkcode AnnuaireRefusal.NotOverseas}, and a row whose `etat`
+ * is not `OUVERT` under {@linkcode AnnuaireRefusal.NotOpen}.
+ *
+ * ## Organizations only
+ *
+ * Every record is an education establishment or office. One private school among the overseas
+ * records writes its address care of a named person (`Chez …`), which places it at that person's
+ * premises, so a line opening with `Chez` refuses the row under {@linkcode AnnuaireRefusal.CareOfPerson}.
+ *
+ * ## The three address lines
+ *
+ * `adresse_1` is the street line, `adresse_2` a complement, and `adresse_3` La Poste's routing line
+ * when the publisher filled it. The publisher writes them as people typed them, so each is read by
+ * what it holds rather than by its position:
+ *
+ * - **A street.** `5 rue Maréchal Leclerc` opens with a number and a street-type word, and
+ *   `Rue Marcel Bonin` with the word alone. The word becomes `street_prefix` through
+ *   {@linkcode splitFrenchStreetType}, which reads the BAN reader's dictionary and then TRE-R35's
+ *   street types for the words it lacks (`quartier`, `lotissement`, `ZAC`). A number of `0` is the
+ *   publisher's placeholder for none. `Bourg` or `Village` written by itself refers to the
+ *   settlement's center and is read as a place.
+ * - **A district under a street.** A complement after a street line whose type word is not a
+ *   thoroughfare (`Quartier d'Orléans`, `BOIS DE NEFLES`, `Plaine Adam`) refers to the district the
+ *   street is in, and becomes `dependent_locality`.
+ * - **A place.** `MATA UTU`, `Gustavia`, `ATOLL DE TAKAROA` hold no number and no street-type word.
+ *   In these jurisdictions such a line gives the village, quarter or lieu-dit the school stands in,
+ *   so it becomes `dependent_locality`. A leading `Lieu-dit` is dropped from it.
+ * - **A building or a landmark.** `Lycée de Poindimié`, `ENCEINTE ECOLE DE TIAPA`, `PARKING MEGA`
+ *   locate the school by another site and are left out of the row, counted under
+ *   {@linkcode AnnuaireTrim.LinePremiseDescriptor}.
+ * - **A box.** `BP 4238`, `FAAA / BP 509`, `BP M2` becomes `po_box`, and the rest of the line is
+ *   read again as one of the shapes above.
+ *
+ * French Polynesia's complement line opens with the publisher's archipelago code (`IDV TAHITI`,
+ * `ISLV RAIATEA`, `TG RANGIROA`, `MARQ UA POU`, `AUSTRALES RIMATARA`), which is an administrative
+ * grouping rather than part of the address, so a remainder opening with one is left out and counted
+ * under {@linkcode AnnuaireTrim.ArchipelagoCode}.
+ *
+ * A digit the reading above cannot place refuses the row: `PK 4 APOOITI UTUROA RAIATEA` is a
+ * kilometer point, `TSOUNDZOU 2` and `ZUP 1` are numbered quarters this reader cannot tell from a
+ * building number. A complement that writes the same place as the street line or the locality is
+ * dropped, and a row left with two different place lines is refused under
+ * {@linkcode AnnuaireRefusal.PlaceLinesConflict} rather than guessing which one is the lieu-dit.
+ *
+ * The postcode, locality and `cedex` come from `adresse_3` where it parses as a routing line, and
+ * from `code_postal` and `nom_commune` otherwise. The codex layout of every jurisdiction here except
+ * French Polynesia prints `cedex`, so a Polynesian `CEDEX` row is refused as unrenderable.
+ *
+ * ## Identity and license
+ *
+ * The row id is content-addressed over the aligned components, and a second record rendering the
+ * same row is refused under {@linkcode AnnuaireRefusal.Duplicate}.
+ *
+ * The dataset's catalog record states `license` `Licence Ouverte v2.0 (Etalab)` with `license_url`
+ * `http://www.etalab.gouv.fr/wp-content/uploads/2017/04/ETALAB-Licence-Ouverte-v2.0.pdf`, and gives
+ * the publisher as `DNE - Ministère de l'Education Nationale`. That license states « Le « Réutilisateur
+ * » est libre de réutiliser l'« Information » : […] de l'adapter, la modifier, l'extraire et la
+ * transformer, pour créer des « Informations dérivées », des produits ou des services », « Sous
+ * réserve de : mentionner la paternité de l'« Information » : sa source (au moins le nom du «
+ * Concédant ») et la date de dernière mise à jour de l'« Information » réutilisée. » Every row
+ * records the license, and {@linkcode FR_ANNUAIRE_EDUCATION_ATTRIBUTION} is the credit, which the
+ * model card completes with the update date the fetch manifest records.
+ *
+ * The adapter honors `opts.limit`, `opts.signal` and `opts.country`, and counts every refusal
+ * under its reason in `opts.dropped`.
+ */
+import { type CanonicalRow, type CorpusAdapter } from "#types";
+/**
+ * Registry id for this adapter.
+ *
+ * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from.
+ */
+export declare const FR_ANNUAIRE_EDUCATION_ADAPTER_ID = "fr-annuaire-education-overseas";
+/**
+ * The license the dataset's catalog record states.
+ */
+export declare const FR_ANNUAIRE_EDUCATION_LICENSE = "Licence Ouverte 2.0";
+/**
+ * The credit Licence Ouverte 2.0 requires: the licensor's name, beside the date of the data's last update.
+ */
+export declare const FR_ANNUAIRE_EDUCATION_ATTRIBUTION = "Annuaire de l'\u00E9ducation, DNE - Minist\u00E8re de l'Education Nationale, via data.education.gouv.fr (fr-en-annuaire-education)";
+/**
+ * The overseas INSEE departments this adapter reads: every prefix in `COUNTRY_BY_INSEE_DEPARTMENT`
+ * except `984`, the French Southern Territories, which has no schools.
+ */
+export declare const FR_ANNUAIRE_EDUCATION_DEPARTEMENTS: readonly string[];
+/**
+ * Every jurisdiction this adapter can emit.
+ */
+export declare const FR_ANNUAIRE_EDUCATION_COUNTRIES: readonly string[];
+/**
+ * The fields of one export record this adapter reads.
+ *
+ * The export writes `null` for an empty field.
+ */
+export interface AnnuaireRecord {
+    identifiant_de_l_etablissement?: string | null;
+    nom_etablissement?: string | null;
+    adresse_1?: string | null;
+    adresse_2?: string | null;
+    adresse_3?: string | null;
+    code_postal?: string | null;
+    nom_commune?: string | null;
+    code_departement?: string | null;
+    etat?: string | null;
+}
+/**
+ * Why a record did not become a row.
+ */
+export declare const AnnuaireRefusal: {
+    /**
+     * The record's department is metropolitan or not one this adapter reads.
+     */
+    readonly NotOverseas: "row:not-overseas";
+    /**
+     * The establishment's `etat` is not `OUVERT`.
+     */
+    readonly NotOpen: "row:not-open";
+    /**
+     * An address line is written care of a person.
+     */
+    readonly CareOfPerson: "row:care-of-person";
+    /**
+     * Neither `adresse_3` nor `code_postal` gives a five-digit postcode.
+     */
+    readonly PostcodeAbsent: "row:postcode-absent";
+    /**
+     * Neither `adresse_3` nor `nom_commune` gives a locality.
+     */
+    readonly LocalityAbsent: "row:locality-absent";
+    /**
+     * A line holds a digit the reading cannot place as a house number, a box or a numbered street name.
+     */
+    readonly DigitUnplaced: "row:digit-unplaced";
+    /**
+     * A street-type word with no name after it, as `0 route` is.
+     */
+    readonly StreetNameAbsent: "row:street-name-absent";
+    /**
+     * The two lines give two different places, and the record does not mark either one as the lieu-dit.
+     */
+    readonly PlaceLinesConflict: "row:place-lines-conflict";
+    /**
+     * The record gives a locality and a venue without a street, a place or a box.
+     */
+    readonly DeliveryLineAbsent: "row:delivery-line-absent";
+    /**
+     * The jurisdiction's layout does not print every component the row carries.
+     */
+    readonly Unrenderable: "row:unrenderable";
+    /**
+     * Another record already produced this exact row.
+     */
+    readonly Duplicate: "row:duplicate";
+};
+export type AnnuaireRefusal = (typeof AnnuaireRefusal)[keyof typeof AnnuaireRefusal];
+/**
+ * Why an admitted row left out a line the record holds.
+ */
+export declare const AnnuaireTrim: {
+    /**
+     * A line locates a building or a landmark (`Lycée de Poindimié`) rather than a street or a place.
+     */
+    readonly LinePremiseDescriptor: "component:line:premise-descriptor";
+    /**
+     * A complement opens with French Polynesia's archipelago code, an administrative grouping.
+     */
+    readonly ArchipelagoCode: "component:dependent_locality:archipelago-code";
+};
+export type AnnuaireTrim = (typeof AnnuaireTrim)[keyof typeof AnnuaireTrim];
+/**
+ * What one record yielded: a row with the lines it left out, or the reason it yielded none.
+ */
+export type AnnuaireReading = {
+    readonly admitted: CanonicalRow;
+    readonly trimmed: readonly AnnuaireTrim[];
+} | {
+    readonly refused: AnnuaireRefusal;
+};
+/**
+ * One address line, read by what it holds.
+ */
+type LineReading = {
+    kind: "street";
+    street_prefix?: string;
+    street: string;
+    house_number?: string;
+} | {
+    kind: "place";
+    place: string;
+} | {
+    kind: "premise";
+} | {
+    kind: "archipelago";
+} | {
+    kind: "refused";
+    reason: AnnuaireRefusal;
+};
+/**
+ * Read one address line, after any post-office box has been taken out of it.
+ */
+export declare function readAnnuaireLine(line: string): LineReading;
+/**
+ * Read one export record into a row, or report why it yielded none.
+ *
+ * Exported because the refusal reasons are what this adapter is measured by.
+ */
+export declare function readAnnuaireRecord(record: AnnuaireRecord): AnnuaireReading;
+export declare function createAnnuaireEducationAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const annuaireEducationAdapter: CorpusAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/out/fr/adapters/annuaire-education/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../lib/fr/adapters/annuaire-education/adapter.ts"],"names":[],"mappings":"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"}