poland-py (alpha)

A lightweight, zero-dependency Python utility for validating and extracting metadata from Polish PESEL numbers.

Installation

pip install poland-py

Usage

Basic validation and parsing

from poland_py import PESEL

pesel = PESEL("80010112345")

if pesel.is_valid():
    print("Valid PESEL")
    print(f"Birth date: {pesel.birth_date}")
    print(f"Year: {pesel.year}")
    print(f"Month: {pesel.month}")
    print(f"Day: {pesel.day}")
    print(f"Gender: {pesel.gender}")
    print(f"Age: {pesel.age}")
else:
    print("Invalid PESEL")

print(repr(pesel))  # <PESEL raw='80010112345' valid=True>

Invalid PESEL handling

from poland_py import PESEL

pesel = PESEL("12345")
print(pesel.is_valid())      # False
print(pesel.birth_date)      # None
print(pesel.gender)          # None
print(pesel.age)             # None

API

class PESEL

Constructor

• PESEL(raw_value: str) – creates a PESEL object from a string (whitespace is stripped).

Methods

• is_valid() -> bool – returns True if the PESEL number passes validation (length, checksum, date validity).

Properties

• raw -> str – original input string (stripped).
• birth_date -> Optional[date] – parsed birth date (datetime.date) or None if invalid.
• year -> Optional[int], month -> Optional[int], day -> Optional[int] – date components, or None if invalid.
• gender -> Optional[str] – "male" or "female", or None if invalid.
• age -> Optional[int] – calculated age in years based on today's date, or None if invalid.

Representation

• __repr__() -> str – e.g. <PESEL raw='80010112345' valid=True>.

Validation rules

The PESEL number is considered valid if:

• it consists of exactly 11 digits,
• the checksum (with weights 1, 3, 7, 9, 1, 3, 7, 9, 1, 3) matches the 11th digit,
• the encoded birth date is a valid calendar date,
• the month encoding corresponds to a supported century range (1800–2299).

Design goals

• Zero dependencies – no external libraries required.
• Simple API – single class for validation and parsing.
• Educational and utility use – suitable for demos, prototypes, and lightweight tooling.

Disclaimer

This package is provided for informational and utility purposes only, on an “as is” basis, without warranties of any kind. It is not affiliated with or endorsed by any Polish government institution. The authors are not liable for any damages arising from its use, including but not limited to incorrect validation results, data misinterpretation, or business interruptions.

Do not rely on this package as the sole source of truth for legal, financial, or official identification purposes. Always verify critical data against official sources.