Metadata-Version: 2.4
Name: poland-py
Version: 0.1.1
Summary: Lightweight Python utility for Polish data formats, PESEL parsing, and validation.
Author-email: Rylse Solutions <hello@rylse.com>
License-Expression: MIT
Keywords: poland,pesel,validator,parser,utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# poland-py (alpha)

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


## Installation

```bash
pip install poland-py
```


## Usage

### Basic validation and parsing

```python
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

```python
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.
