Isikukood

Small Estonian social security number library (I know they're not really SSNs but I don't have a better English name for them)

Installation

Simply run the following:

pip install isikukood

Table of Contents

• functions
  • ordernumber_from_ssn
  • gender_from_ssn
  • gender_marker
  • birthdate_from_ssn
  • insert_checksum
  • calculate_checksum
  • enum
• isikukood
  • Isikukood
    • from_ssn
    • construct
    • construct
    • construct
• assertions
  • assert_ordernumber_range
  • assert_numeric
  • assert_gender
  • assert_first_digit
  • assert_year_range
  • assert_existing_date
  • assert_constructor_list
  • assert_valid_ssn
  • assert_correct_checksum
  • assert_enum_arguments

---

functions

---

ordernumber_from_ssn

def ordernumber_from_ssn(ssn: str) -> int

Extract the order number from the given SSN.

Examples:

    >>>isikukood.ordernumber_from_ssn('50001010006')
    0
    >>>isikukood.ordernumber_from_ssn('50001010105')
    10

---

gender_from_ssn

def gender_from_ssn(ssn: str) -> str

Extract the gender from the given SSN.

Examples:

   >>>isikukood.gender_from_ssn('50001010006')
   'm'
   >>>isikukood.gender_from_ssn('60001010007')
   'f'

Returns:

• str - Either 'm' or 'f'.

---

gender_marker

def gender_marker(yyyy: int, gender: str) -> str

Find the suitable gender marker (first digit), given gender and year of birth.

Examples:

    >>>isikukood.gender_marker(2000, 'm')
    '5'
    >>>isikukood.gender_marker(1999, 'm')
    '3'

Arguments:

• yyyy int - Year of birth.
• gender str - Either 'm' or 'f'.

Returns:

• int - A number between 1 and 8 (inclusive).

Raises:

• ValueError - When either one of the arguments is invalid.

---

birthdate_from_ssn

def birthdate_from_ssn(ssn: str) -> str

Find the birthdate, given an SSN.

Examples:

    >>>isikukood.birthdate_from_ssn('50001010006')
    '2000-01-01'

Arguments:

• ssn str - Estonian SSN.

Returns:

• str - Corresponding birthdate in ISO 8601 (yyyy-mm-dd).

---

insert_checksum

def insert_checksum(ssn: str) -> str

Examples:

    >>>isikukood.insert_checksum('5000101000x')
    '50001010006'

Arguments:

• ssn str - Estonian SSN, can be either 10 or 11 digits.

Returns:

• str - The given SSN but with the 11th digit replaced with a newly calculated checksum.

Raises:

• ValueError - When the given SSN is not 10 or 11 digits in length.

---

calculate_checksum

def calculate_checksum(ssn: str) -> int

Calculate the given SSN's checksum as per https://et.wikipedia.org/wiki/Isikukood#Kontrollnumber

Examples:

    >>>isikukood.calculate_checksum('5000101000')
    6

Arguments:

• ssn str - Estonian SSN. May or may not already contain the checksum digit (can be either 10 or 11 digits).

Returns:

• int - Corresponding checksum.

---

enum

def enum(genders: List[str] = None,
         days: List[int] = None,
         months: List[int] = None,
         years: List[int] = None,
         onums: List[int] = None) -> List[str]

Generate all valid Estonian SSNs possible with the given arguments.

Examples:

    >>>isikukood.enum(days=[1], months=[1], years=[2000], onums=[0, 1, 2])
    ['50001010006', '50001010017', '50001010028', '60001010007', '60001010018', '60001010029']

Arguments:

• genders List[str] - A list in which each element is either 'm' or 'f'. Defaults to ['m', 'f'].
• days List[int] - Days of the month, such as [5, 6, 7, 8, 9]. Defaults to [1; 31].
• months List[int] - Months of the year, such as [9, 10, 11, 12]. Defaults to [1; 12].
• years List[int] - Years, such as [2000, 2001, 2002]. Defaults to the current year.
• onums List[int] - Order numbers, such as [371, 372, ..., 420]. Defaults to [0; 999].

Returns:

• List[str] - List of SSNs.

Raises:

• ValueError - When any of the given arguments is invalid.

---

isikukood

---

Isikukood Objects

class Isikukood()

---

from_ssn

@classmethod
def from_ssn(cls, ssn: str)

Instantiate the class from an already existing SSN.

Examples:

    >>>isikukood.Isikukood.from_ssn('50001010006')

Raises:

• ValueError - When the given SSN is invalid.

---

construct

@multimethod
def construct() -> List[str]

Generate all possible SSNs with the instance's gender and birthdate.

Examples:

    >>>isikukood.Isikukood('m', '2000-01-01').construct()
    ['50001010006', '50001010017', '50001010028', ...]

Returns:

• List[str] - List of SSNs.

---

construct

@multimethod
def construct(ordernumber: int) -> str

Generate an SSN with the instance's gender and birthdate and the order number that was given as an argument.

Examples:

    >>>isikukood.Isikukood('m', '2000-01-01').construct(111)
    '50001011112'

Raises:

• ValueError - When the given order number is invalid.

---

construct

@multimethod
def construct(ordernumbers: List[int]) -> List[str]

Generate all possible SSNs with the instance's gender and birthdate and with all the order numbers that were given as an argument.

Examples:

    >>>isikukood.Isikukood('m', '2000-01-01').construct([111, 222, 333])
    ['50001011112', '50001012229', '50001013335']

Arguments:

• ordernumbers List[int] - List of order numbers.

Returns:

• List[str] - List of SSNs.

Raises:

• ValueError - When any of the given order numbers is invalid.

---

assertions

---

assert_ordernumber_range

def assert_ordernumber_range(ordernumber: int) -> None

Assert that the given argument is between 0 and 999 (inclusive).

Raises:

• AssertionError - When the assertion fails.

---

assert_numeric

def assert_numeric(arg: str) -> None

Assert that the given argument is numeric.

Raises:

• AssertionError - When the assertion fails.

---

assert_gender

def assert_gender(gender: str) -> None

Assert that the given argument is either 'm' or 'f'.

Raises:

• AssertionError - When the assertion fails.

---

assert_first_digit

def assert_first_digit(ssn: str) -> None

Assert that the first character of the given argument is between 1 and 8 (inclusive).

Raises:

• AssertionError - When the assertion fails.

---

assert_year_range

def assert_year_range(yyyy: int) -> None

Assert that the given argument is between 1800 and 2199 (inclusive).

Raises:

• AssertionError - When the assertion fails.

---

assert_existing_date

def assert_existing_date(date: str) -> None

Assert that the given date exists (no February 29th on non-leap years, no April 31st, etc.).

Arguments:

• date str - Date in ISO 8601 (YYYY-MM-DD).

Raises:

• AssertionError - When the assertion fails.

---

assert_constructor_list

def assert_constructor_list(ssns: List[str]) -> None

Sanity check called by SSN constructors. Asserts that the given argument contains no duplicates and that every one of its elements is a valid Estonian SSN.

Arguments:

• ssns List[str] - List of SSNs coming from Isikukood.construct().

Raises:

• AssertionError - When any of the assertions fail.

---

assert_valid_ssn

def assert_valid_ssn(ssn: str) -> None

Assert that the given argument is a valid Estonian SSN. Currently, this performs the following checks:

• that the SSN is numeric
• that the first digit is between 1 and 8 (inclusive)
• that the SSN is exactly 11 digits
• that the checksum is correct
• that the birthdate exists
• that the year of birth is between 1800 and 2199 (inclusive)

Raises:

• AssertionError - When any of the assertions fail.

---

assert_correct_checksum

def assert_correct_checksum(ssn: str) -> None

Assert that the given SSN's checksum is correct.

Raises:

• AssertionError - When the assertion fails.

---

assert_enum_arguments

def assert_enum_arguments(genders: List[str], days: List[int],
                          months: List[int], years: List[int]) -> None

Assert that the arguments for functions.enum() are valid. This performs the following checks:

• that every element in genders is either 'm' or 'f'
• that every element in days is between 1 and 31 (inclusive)
• that every element in months is between 1 and 12 (inclusive)
• that every element in years is between 1800 and 2199 (inclusive)

Raises:

• AssertionError - When any of the assertions fail.