islamic-inheritance-calculator 0.0.1

Islamic inheritance calculator

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

pip install islamic-inheritance-calculator

Or directly from GitHub:

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

Quick Start

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)

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

# 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:

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

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

pytest tests/ -v

Contributing

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