Metadata-Version: 2.4
Name: islamic-inheritance-calculator
Version: 0.0.1
Summary: Islamic inheritance calculator
Project-URL: Homepage, https://github.com/qcri/islamic-inheritance-calculator
Project-URL: Issues, https://github.com/qcri/islamic-inheritance-calculator/issues
Author-email: QCRI <qcri@hbku.edu.qa>
License: BSD 3-Clause License
        
        Copyright (c) 2025-2026, Qatar Computing Research Institute - HBKU.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: calculator,fiqh,inheritance,islamic,shariah
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Islamic Inheritance Calculator

[![CI](https://github.com/qcri/islamic-inheritance-calculator/actions/workflows/ci.yml/badge.svg)](https://github.com/qcri/islamic-inheritance-calculator/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/islamic-inheritance-calculator)](https://pypi.org/project/islamic-inheritance-calculator/)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/islamic-inheritance-calculator/)

A Python calculator for Islamic inheritance distribution (Faraid/Mirath) based on Shariah law. Zero external dependencies.

## Supported Heirs

- **Spouse**: husband, wife (up to 4 wives)
- **Children**: sons, daughters
- **Parents**: father, mother
- **Grandparents**: paternal grandfather, paternal grandmother, maternal grandmother
- **Grandchildren**: sons of son, daughters of son
- **Siblings**: full, paternal, and maternal (brothers and sisters)
- **Nephews**: sons of full brothers, sons of paternal brothers
- **Paternal uncles**: full and paternal, and their sons (cousins)

## Supported Rules

- Fixed shares (Fard) and residuary (Asaba) distribution
- Blocking (Hijab) — closer heirs exclude distant ones
- 'Awl — proportional reduction when shares exceed the estate
- Radd — proportional return of remainder to entitled heirs
- Umariyyatan — special case for spouse + mother + father
- Akdariyya — special case for husband + mother + grandfather + one sister
- Mushtaraka (Himariyya) — maternal siblings sharing with full siblings
- Legal impediments (Mawani') — excluding heirs e.g. killer, religion mismatch
- Wasiyyah (bequest) deduction with 1/3 cap
- Dual-school output when Hanafi and Jumhur schools differ

## Installation

```bash
pip install islamic-inheritance-calculator
```

Or directly from GitHub:

```bash
pip install git+https://github.com/qcri/islamic-inheritance-calculator.git
```

## Quick Start

```python
from decimal import Decimal
from islamic_inheritance_calculator import InheritanceCalculator

calc = InheritanceCalculator(Decimal("120000"), currency="USD")

result = calc.calculate(
    deceased_is_male=True,
    has_wife=True,
    num_wives=1,
    num_sons=2,
    num_daughters=1,
)

for share in result["shares"]:
    print(f"{share.heir_type}: {share.share_amount:.2f} ({share.share_fraction})")
```

## With Bequest (Wasiyyah)

```python
result = calc.calculate(
    deceased_is_male=True,
    has_wife=True,
    num_wives=1,
    num_sons=1,
    bequest_amount=Decimal("30000"),  # deducted before distribution (capped at 1/3)
)

print(f"Gross estate: {result['gross_estate']:.2f}")
print(f"Net estate after bequest: {result['estate_value']:.2f}")
```

## With Legal Impediments

```python
# One of two sons is excluded (e.g. killed the deceased)
result = calc.calculate(
    deceased_is_male=True,
    num_sons=2,
    impeded_heirs={"sons": 1},
)
```

## When Schools Differ

For certain cases (grandfather with siblings, Mushtaraka), Hanafi and Jumhur schools produce different distributions. The result includes both:

```python
result = calc.calculate(
    deceased_is_male=True,
    has_grandfather=True,
    num_brothers_full=1,
    num_sisters_full=1,
)

if result["schools_differ"]:
    print(f"Issue: {result['school_difference_issue']}")

    for share in result["jumhur"].shares:
        print(f"[Jumhur] {share.heir_type}: {share.share_amount:.2f}")

    for share in result["hanafi"].shares:
        print(f"[Hanafi] {share.heir_type}: {share.share_amount:.2f}")
```

## API Reference

### `InheritanceCalculator`

```python
InheritanceCalculator(
    estate_value: Decimal,          # net estate after debts and funeral expenses
    currency: str = "USD",          # currency code for display
    default_school: str = "jumhur", # "jumhur" or "hanafi" (used for Radd eligibility)
)
```

### `calculate(**kwargs) -> dict`

All parameters are optional and default to `False` or `0`.

**Heirs:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `deceased_is_male` | `bool` | Gender of the deceased (default `True`) |
| `has_husband` | `bool` | Deceased has a husband |
| `has_wife` | `bool` | Deceased has wife/wives |
| `num_wives` | `int` | Number of wives (max 4) |
| `num_sons` | `int` | Number of sons |
| `num_daughters` | `int` | Number of daughters |
| `has_father` | `bool` | Father is alive |
| `has_mother` | `bool` | Mother is alive |
| `has_grandfather` | `bool` | Paternal grandfather is alive |
| `has_grandmother_paternal` | `bool` | Paternal grandmother is alive |
| `has_grandmother_maternal` | `bool` | Maternal grandmother is alive |
| `num_sons_of_son` | `int` | Sons of son (paternal grandsons) |
| `num_daughters_of_son` | `int` | Daughters of son (paternal granddaughters) |
| `num_brothers_full` | `int` | Full brothers |
| `num_sisters_full` | `int` | Full sisters |
| `num_brothers_paternal` | `int` | Paternal half-brothers |
| `num_sisters_paternal` | `int` | Paternal half-sisters |
| `num_brothers_maternal` | `int` | Maternal half-brothers |
| `num_sisters_maternal` | `int` | Maternal half-sisters |
| `num_sons_of_brother_full` | `int` | Sons of full brothers (nephews) |
| `num_sons_of_brother_paternal` | `int` | Sons of paternal brothers (nephews) |
| `num_paternal_uncles_full` | `int` | Father's full brothers |
| `num_paternal_uncles_paternal` | `int` | Father's paternal half-brothers |
| `num_sons_of_paternal_uncle_full` | `int` | Sons of father's full brothers (cousins) |
| `num_sons_of_paternal_uncle_paternal` | `int` | Sons of father's paternal half-brothers (cousins) |

**Other parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `impeded_heirs` | `dict[str, int]` | Heirs excluded due to legal impediment. Format: `{"sons": 1, "father": 1}`. Valid keys match the heir parameter names (e.g. `"sons"`, `"daughters"`, `"father"`, `"sisters_full"`, etc.) |
| `bequest_amount` | `Decimal` | Amount to deduct as Wasiyyah before distribution. Capped at 1/3 of the estate per Islamic law. |

**Returned dict (when schools agree):**

| Key | Type | Description |
|-----|------|-------------|
| `estate_value` | `Decimal` | Net estate used for distribution |
| `currency` | `str` | Currency code |
| `schools_differ` | `bool` | `False` when Hanafi and Jumhur agree |
| `shares` | `list[InheritanceShare]` | Each heir's share |
| `total_distributed` | `Decimal` | Total amount distributed |
| `warnings` | `list[str]` | Informational notes (blocking, adjustments, etc.) |
| `gross_estate` | `Decimal` | Original estate before bequest (only when `bequest_amount` provided) |
| `bequest_amount` | `Decimal` | Deducted bequest amount (only when provided) |

**Returned dict (when schools differ):**

| Key | Type | Description |
|-----|------|-------------|
| `schools_differ` | `bool` | `True` |
| `school_difference_issue` | `str` | `"grandfather_with_siblings"` or `"mushtaraka"` |
| `jumhur` | `SchoolResult` | Jumhur (Shafi'i/Maliki/Hanbali) distribution |
| `hanafi` | `SchoolResult` | Hanafi distribution |

`SchoolResult` has `.shares` (list of `InheritanceShare`) and `.total_distributed` (Decimal).

**`InheritanceShare` fields:**

| Field | Type | Description |
|-------|------|-------------|
| `heir_type` | `str` | Name of the heir (e.g. `"Wife"`, `"Son"`, `"Daughter"`) |
| `count` | `int` | Number of heirs of this type |
| `share_fraction` | `str` | Fraction string (e.g. `"1/4"`, `"Residuary"`) |
| `share_amount` | `Decimal` | Amount per heir |
| `percentage` | `Decimal` | Percentage of estate per heir |
| `category` | `str` | `"Fixed Share (Fard)"` or `"Residuary (Asaba)"` |

## Testing

```bash
pytest tests/ -v
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up your environment, run the pre-commit hooks, and submit a pull request.
