Skip to content

birth_dates

birth_dates

Shared parsing and rendering for structured and free-text birth dates.

Functions:

Name Description
birth_date_is_supported

Return whether value contains one complete, deterministic date.

shift_birth_date

Shift a parseable birth date by a small nonzero number of days, or return None.

random_birth_date

Return a random birth date between 1930 and 2010, written with pattern or as ISO 8601.

birth_date_is_supported(value)

Return whether value contains one complete, deterministic date.

Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/birth_dates.py
def birth_date_is_supported(value: str) -> bool:
    """Return whether ``value`` contains one complete, deterministic date."""
    return _parse_birth_date(value, None, _MONTH_FIRST_LOCALE) is not None

shift_birth_date(original, pattern, rng, *, locale)

Shift a parseable birth date by a small nonzero number of days, or return None.

The shift is drawn from a normal distribution with a 30-day standard deviation and never exceeds 180 days, so the original date does not survive while ages and the column's distribution stay close to the original.

The plan's pattern only has to cover 99% of a column, so each value is tried against the pattern first, then ISO 8601, common numeric formats, and strict complete natural-language dates. Numeric formats are tried month first for en_US and day first for every other locale. Relative expressions such as "yesterday" or an age such as "30 years" are not fixed dates and are not parsed. The replacement uses the pattern when one is configured, else the numeric format that parsed, else ISO 8601. None means the value could not be parsed; the caller then generates a random birth date so the original never survives.

A date within the shift range of either end of the calendar, such as the placeholders 0001-01-01 and 9999-12-31, is returned unchanged: nobody is born on it, so it keeps its meaning as a placeholder.

Example

With pattern "%m/%d/%Y", "02/14/1990" shifts to a date such as "11/03/1989", "1990-02-14" also shifts and is written as %m/%d/%Y, and "08/2010" returns None.

Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/birth_dates.py
def shift_birth_date(original: str, pattern: str | None, rng: Random, *, locale: str) -> str | None:
    """Shift a parseable birth date by a small nonzero number of days, or return ``None``.

    The shift is drawn from a normal distribution with a 30-day standard deviation and never
    exceeds 180 days, so the original date does not survive while ages and the column's
    distribution stay close to the original.

    The plan's pattern only has to cover 99% of a column, so each value is tried
    against the pattern first, then ISO 8601, common numeric formats, and strict
    complete natural-language dates. Numeric formats are tried month first for
    ``en_US`` and day first for every other ``locale``. Relative expressions such as ``"yesterday"``
    or an age such as ``"30 years"`` are not fixed dates and are not parsed. The replacement uses the pattern when one
    is configured, else the numeric format that parsed, else ISO 8601. ``None``
    means the value could not be parsed; the caller then generates a random
    birth date so the original never survives.

    A date within the shift range of either end of the calendar, such as the
    placeholders ``0001-01-01`` and ``9999-12-31``, is returned unchanged: nobody
    is born on it, so it keeps its meaning as a placeholder.

    Example:
        With pattern ``"%m/%d/%Y"``, ``"02/14/1990"`` shifts to a date such as
        ``"11/03/1989"``, ``"1990-02-14"`` also shifts and is written as
        ``%m/%d/%Y``, and ``"08/2010"`` returns ``None``.
    """
    parsed = _parse_birth_date(original, pattern, locale)
    if parsed is None:
        return None
    # The bounds have no timezone, so compare the wall-clock value; the shift keeps any timezone.
    if not _EARLIEST_SHIFTABLE <= parsed.value.replace(tzinfo=None) <= _LATEST_SHIFTABLE:
        return original
    shifted = parsed.value + timedelta(days=_shift_days(rng))
    if parsed.output_pattern is not None:
        return shifted.strftime(parsed.output_pattern)
    return shifted.date().isoformat()

random_birth_date(pattern, rng)

Return a random birth date between 1930 and 2010, written with pattern or as ISO 8601.

The date is taken at midnight UTC, so a pattern with %z or %Z still renders a timezone and the value parses with that pattern.

Example

With pattern "%Y-%m-%d %z", the result looks like "1974-06-02 +0000".

Source code in src/nemo_safe_synthesizer/pii_replacer/replacement/birth_dates.py
def random_birth_date(pattern: str | None, rng: Random) -> str:
    """Return a random birth date between 1930 and 2010, written with ``pattern`` or as ISO 8601.

    The date is taken at midnight UTC, so a pattern with ``%z`` or ``%Z`` still renders a timezone and the
    value parses with that pattern.

    Example:
        With pattern ``"%Y-%m-%d %z"``, the result looks like ``"1974-06-02 +0000"``.
    """
    value = _RANDOM_BIRTH_DATE_START + timedelta(days=rng.randrange(_RANDOM_BIRTH_DATE_DAYS + 1))
    if pattern is None:
        return value.isoformat()
    return datetime.combine(value, time(), tzinfo=UTC).strftime(pattern)