Implement firstname decoding.

README.md

@@ -62,6 +62,9 @@ codicefiscale.decode("CCCFBA85D03L219P")
 #         "province": "TO",
 #         "code": "L219",
 #     },
+#     "firstname_options": [
+#         "Fabio",
+#     ],
 #     "omocodes": [
 #         "CCCFBA85D03L219P",
 #         "CCCFBA85D03L21VE",
@@ -86,6 +89,9 @@ codicefiscale.decode("CCCFBA85D03L219P")
 # }
 ```
 
+> [!TIP]
+> **Name suggestions**: The `firstname_options` field contains a list of possible first names matching the encoded firstname code. For Italian birthplaces, in approximately **60% of cases**, it returns a single name, providing near-certain identification. In other cases, it returns a list of possible names. For foreign birthplaces, the list is empty.
+
 #### Check
 ```python
 codicefiscale.is_valid("CCCFBA85D03L219P")

src/codicefiscale/__init__.py

@@ -1,3 +1,16 @@
+from codicefiscale.codicefiscale import (
+    decode,
+    decode_firstname,
+    decode_raw,
+    encode,
+    encode_birthdate,
+    encode_birthplace,
+    encode_cin,
+    encode_firstname,
+    encode_lastname,
+    is_omocode,
+    is_valid,
+)
 from codicefiscale.metadata import (
     __author__,
     __copyright__,
@@ -14,4 +27,15 @@
     "__license__",
     "__title__",
     "__version__",
+    "decode",
+    "decode_firstname",
+    "decode_raw",
+    "encode",
+    "encode_birthdate",
+    "encode_birthplace",
+    "encode_cin",
+    "encode_firstname",
+    "encode_lastname",
+    "is_omocode",
+    "is_valid",
 ]

src/codicefiscale/codicefiscale.py

@@ -5,7 +5,7 @@
 from datetime import datetime, timedelta
 from itertools import combinations
 from re import Pattern
-from typing import Any, Literal
+from typing import Any, Literal, cast
 
 from dateutil import parser as date_parser
 from slugify import slugify
@@ -82,7 +82,15 @@
         _OMOCODIA_SUBS_INDEXES_COMBINATIONS.append(list(combo))
 
 
-_DATA: dict[str, dict[str, list[dict[str, Any]]]] = get_indexed_data()
+_DATA: dict[str, Any] | None = None
+
+
+def _get_data() -> dict[str, Any]:
+    global _DATA
+    if _DATA is None:
+        _DATA = get_indexed_data()
+    return _DATA
+
 
 CODICEFISCALE_RE: Pattern[str] = re.compile(
     r"^"
@@ -144,17 +152,18 @@ def _get_date(
 def _get_birthplace(
     birthplace: str,
     birthdate: datetime | str | None = None,
-) -> dict[str, dict[str, Any]] | None:
+) -> dict[str, Any] | None:
     birthplace_unicode_slug = slugify(birthplace, allow_unicode=True)
     birthplace_slug = slugify(birthplace)
     birthplace_code = birthplace_slug.upper()
-    birthplaces_options = _DATA["municipalities"].get(
+    data = _get_data()
+    birthplaces_options = data["municipalities"].get(
         birthplace_unicode_slug,
-        _DATA["municipalities"].get(
+        data["municipalities"].get(
             birthplace_slug,
-            _DATA["countries"].get(
+            data["countries"].get(
                 birthplace_slug,
-                _DATA["codes"].get(
+                data["codes"].get(
                     birthplace_code,
                 ),
             ),
@@ -165,23 +174,23 @@ def _get_birthplace(
 
     birthdate_date = _get_date(birthdate)
     if not birthdate_date:
-        return birthplaces_options[0].copy()
+        return cast(dict[str, Any], birthplaces_options[0].copy())
 
     # search birthplace that has been created before / deleted after birthdate
     for birthplace_option in birthplaces_options:
         date_created = _get_date(birthplace_option["date_created"]) or datetime.min
         date_deleted = _get_date(birthplace_option["date_deleted"]) or datetime.max
         # print(birthdate_date, date_created, date_deleted)
         if birthdate_date >= date_created and birthdate_date <= date_deleted:
-            return birthplace_option.copy()
+            return cast(dict[str, Any], birthplace_option.copy())
 
     return _get_birthplace_fallback(birthplaces_options, birthdate_date)
 
 
 def _get_birthplace_fallback(
     birthplaces_options: list[dict[str, Any]],
     birthdate_date: datetime,
-) -> dict[str, dict[str, Any]] | None:
+) -> dict[str, Any] | None:
     # avoid wrong birthplace code error when birthdate falls in
     # missing date-range in the data-source even if birthplace code is valid
     birthplaces_options_count = len(birthplaces_options)
@@ -280,6 +289,43 @@ def encode_firstname(firstname: str) -> str:
     return firstname_code
 
 
+def decode_firstname(
+    firstname_code: str, gender: Literal["m", "M", "f", "F"] | None = None
+) -> list[str] | None:
+    """
+    Decodes firstname code to possible italian first names.
+
+    Returns a list of possible names that encode to the given code.
+    Only works for common italian names.
+
+    :param firstname_code: The 3-character firstname code
+    :type firstname_code: string
+    :param gender: Optional gender filter ('M' or 'F')
+    :type gender: string | None
+
+    :returns: List of possible first names, or None if not found
+    :rtype: list[str] | None
+    """
+    firstname_code_upper = firstname_code.upper()
+    data = _get_data()
+    names_by_gender = cast(
+        dict[str, list[str]] | None, data["names"].get(firstname_code_upper)
+    )
+
+    if not names_by_gender:
+        return None
+
+    if gender:
+        gender_upper = gender.upper()
+        if gender_upper in ("M", "F"):
+            gender_names = names_by_gender.get(gender_upper, [])
+            return gender_names if gender_names else None
+
+    # return all names (both genders) if no gender specified
+    all_names = names_by_gender.get("M", []) + names_by_gender.get("F", [])
+    return sorted(set(all_names)) if all_names else None
+
+
 def encode_birthdate(
     birthdate: datetime | str | None,
     gender: Literal["m", "M", "f", "F"],
@@ -448,7 +494,7 @@ def decode_raw(code: str) -> dict[str, str]:
     return data
 
 
-def decode(code: str) -> dict[str, Any]:
+def decode(code: str) -> dict[str, Any]:  # noqa: C901
     """
     Decodes the italian fiscal code.
 
@@ -466,11 +512,10 @@ def decode(code: str) -> dict[str, Any]:
     birthdate_month = _MONTHS.index(raw["birthdate_month"]) + 1
     birthdate_day = int(raw["birthdate_day"].translate(_OMOCODIA_DECODE_TRANS))
 
+    gender: Literal["M", "F"] = "M"
     if birthdate_day > 40:
         birthdate_day -= 40
         gender = "F"
-    else:
-        gender = "M"
 
     current_year = datetime.now().year
     current_year_century_prefix = str(current_year)[0:-2]
@@ -517,12 +562,19 @@ def decode(code: str) -> dict[str, Any]:
             f"expected {cin_check!r}, found {cin!r}"
         )
 
+    # add possible first names if birthplace is in Italy (not foreign country)
+    firstname_options = None
+    is_foreign = birthplace and birthplace.get("province") == "EE"
+    if not is_foreign:
+        firstname_options = decode_firstname(raw["firstname"], gender)
+
     data = {
         "code": code,
         "omocodes": _get_omocodes(code),
         "gender": gender,
         "birthdate": birthdate,
         "birthplace": birthplace,
+        "firstname_options": firstname_options or [],
         "raw": raw,
     }
 

src/codicefiscale/data.py

@@ -2,7 +2,6 @@
 
 import os
 import sys
-from datetime import datetime
 from typing import Any
 
 import fsutil
@@ -33,23 +32,31 @@ def get_countries_data() -> Any:
     return deleted_countries + countries
 
 
-def get_indexed_data() -> dict[
-    str, dict[str, list[dict[str, bool | datetime | str | list[str]]]]
-]:
+def get_names_data() -> Any:
+    names = get_data("names.json")
+    return names
+
+
+def get_indexed_data() -> dict[str, Any]:
+    from codicefiscale.codicefiscale import encode_firstname
+
     municipalities = get_municipalities_data()
     countries = get_countries_data()
-    data: dict[str, dict[str, list[dict[str, bool | datetime | str | list[str]]]]] = {
+    names = get_names_data()
+
+    data: dict[str, Any] = {
         "municipalities": {},
         "countries": {},
         "codes": {},
+        "names": {},
     }
 
     for municipality in municipalities:
         code = municipality["code"]
         province = municipality["province"].lower()
         municipality_unicode_slug = slugify(municipality["name"], allow_unicode=True)
-        names = [municipality_unicode_slug] + municipality["name_slugs"]
-        for name in names:
+        municipality_names = [municipality_unicode_slug] + municipality["name_slugs"]
+        for name in municipality_names:
             name_and_province = f"{name}-{province}"
             data["municipalities"].setdefault(name, [])
             data["municipalities"].setdefault(name_and_province, [])
@@ -60,11 +67,21 @@ def get_indexed_data() -> dict[
 
     for country in countries:
         code = country["code"]
-        names = country["name_slugs"]
-        for name in names:
+        country_names = country["name_slugs"]
+        for name in country_names:
             data["countries"].setdefault(name, [])
             data["countries"][name].append(country)
         data["codes"].setdefault(code, [])
         data["codes"][code].append(country)
 
+    for gender, gender_names in names.items():
+        for name in gender_names:
+            code = encode_firstname(name)
+            data["names"].setdefault(code, {"M": set(), "F": set()})
+            data["names"][code][gender].add(name)
+
+    for code in data["names"]:
+        data["names"][code]["M"] = sorted(data["names"][code]["M"])
+        data["names"][code]["F"] = sorted(data["names"][code]["F"])
+
     return data