Metadata-Version: 2.1
Name: expensesplit
Version: 1.0.0
Summary: A Python library for splitting shared expenses between groups of people
Author-email: Arya Agrawal <agrawalarya@egmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/expensesplit
Project-URL: Repository, https://github.com/yourusername/expensesplit
Keywords: expense,split,splitwise,finance,group
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# expensesplit

A Python library for splitting shared expenses between a group of people.
Inspired by Splitwise. Uses the **Minimize Cash Flow** algorithm to produce
the fewest possible settlement transactions.

## Install

```bash
pip install expensesplit
```

## Quick Start

```python
from expensesplit import calculate_balances, calculate_settlements

members = ['Arya', 'John', 'Sara']

expenses = [
    {'payer': 'Arya', 'amount': 90.0},   # Arya paid $90 for dinner
    {'payer': 'John', 'amount': 30.0},   # John paid $30 for taxi
]

# Step 1 — calculate each person's net balance
balances = calculate_balances(members, expenses)
# {'Arya': 50.0, 'John': -10.0, 'Sara': -40.0}
# Arya is owed $50, John owes $10, Sara owes $40

# Step 2 — calculate minimum payments to settle everything
settlements = calculate_settlements(balances)
# [{'from': 'Sara', 'to': 'Arya', 'amount': 40.0},
#  {'from': 'John', 'to': 'Arya', 'amount': 10.0}]

for s in settlements:
    print(f"{s['from']} pays {s['to']}  ${s['amount']:.2f}")
```

## Split Modes

### Equal Split (default)
```python
from expensesplit import split_amount

shares = split_amount(90.0, ['Arya', 'John', 'Sara'])
# {'Arya': 30.0, 'John': 30.0, 'Sara': 30.0}
```

### Custom Amounts
```python
shares = split_amount(
    100.0,
    ['Arya', 'John', 'Sara'],
    split_type='custom',
    values={'Arya': 50.0, 'John': 30.0, 'Sara': 20.0}
)
# {'Arya': 50.0, 'John': 30.0, 'Sara': 20.0}
```

### Percentage Split
```python
shares = split_amount(
    200.0,
    ['Arya', 'John', 'Sara'],
    split_type='percentage',
    values={'Arya': 50, 'John': 30, 'Sara': 20}
)
# {'Arya': 100.0, 'John': 60.0, 'Sara': 40.0}
```

### Custom Shares on Expenses
```python
expenses = [
    {
        'payer': 'Arya',
        'amount': 100.0,
        'shares': {'Arya': 50.0, 'John': 30.0, 'Sara': 20.0}  # custom split
    },
    {
        'payer': 'John',
        'amount': 60.0
        # no 'shares' key = equal split
    },
]

balances = calculate_balances(['Arya', 'John', 'Sara'], expenses)
```

## Settlement Status

```python
from expensesplit import get_settlement_status

get_settlement_status(total_owed=100.0, amount_paid=100.0)  # 'settled'
get_settlement_status(total_owed=100.0, amount_paid=40.0)   # 'partial'
get_settlement_status(total_owed=100.0, amount_paid=0.0)    # 'pending'
```

## How the Algorithm Works

The library uses the **Minimize Cash Flow** algorithm:

1. Calculate each member's net balance (paid minus owed)
2. Separate into creditors (positive balance) and debtors (negative balance)
3. Greedily match the largest debtor with the largest creditor
4. Repeat until all balances are zero

This guarantees the **fewest possible transactions** to settle all debts.

## License

MIT
