Metadata-Version: 2.4
Name: attendancex
Version: 0.1.0
Summary: A lightweight Python library for attendance calculations
Author: Khushi Dhamani
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# attendancex

A lightweight, dependency-free Python library for attendance calculations and planning.

[![PyPI version](https://img.shields.io/pypi/v/attendancex.svg)](https://pypi.org/project/attendancex/)
[![Python](https://img.shields.io/pypi/pyversions/attendancex.svg)](https://pypi.org/project/attendancex/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## What is attendancex?

`attendancex` is a pure Python library that handles attendance logic — so developers don't have to write it themselves.

It works as a calculation engine that can be plugged into any project — a college app, a chatbot, a web dashboard, or an academic management system.

---

## Installation

```bash
pip install attendancex
```

---

## Usage

```python
import attendancex
```

By default, all functions use **75%** as the minimum required attendance.
To use a different percentage, pass `required_percent` to any function:

```python
# Default — 75% minimum
attendancex.safe_bunks(attended=49, total=60)

# Custom — 80% minimum
attendancex.safe_bunks(attended=49, total=60, required_percent=80)
```

---

## Examples

```python
# Current attendance percentage
# attended=45 classes out of total=60 classes held
attendancex.calculate_percentage(attended=45, total=60)
# → 75.0

# How many classes can I skip and stay above 75%?
# attended=49 out of total=60
attendancex.safe_bunks(attended=49, total=60)
# → 4

# My attendance is low — how many consecutive classes must I attend to reach 75%?
# attended=30 out of total=60 — currently at 50%
attendancex.classes_needed(attended=30, total=60)
# → 60

# Can I still pass by end of semester?
# attended=45, total=60 held, remaining=20 classes left
attendancex.will_pass(attended=45, total=60, remaining=20)
# → True

# If I attend all upcoming classes, what will my percentage be?
# attended=45, total=60, extra_classes=10 upcoming
attendancex.projected_attendance(attended=45, total=60, extra_classes=10)
# → 78.57

# Minimum classes I must attend from remaining to pass?
# attended=45, total=60 held, remaining=20 classes left
attendancex.minimum_to_pass(attended=45, total=60, remaining=20)
# → 15

# How many classes can I skip in a row right now?
# attended=49 out of total=60
attendancex.bunk_streak(attended=49, total=60)
# → 5

# Full attendance report in one call
attendancex.attendance_summary(attended=45, total=60, remaining=20)
# → {
#     'percentage': 75.0,            # current attendance %
#     'status': 'warning',           # safe / warning / critical
#     'safe_bunks': 0,               # classes that can be skipped
#     'classes_needed': 0,           # classes needed to recover
#     'will_pass': True,             # can still pass this semester?
#     'projected_attendance': 81.25, # % if all remaining classes attended
#     'minimum_to_pass': 15,         # minimum to attend from remaining
#     'bunk_streak': 0               # max consecutive bunks right now
#   }
```

---

## All Functions

| Function | Returns | Description |
|---|---|---|
| `calculate_percentage(attended, total)` | `float` | Current attendance percentage |
| `safe_bunks(attended, total)` | `int` | Classes that can be safely skipped |
| `classes_needed(attended, total)` | `int` | Classes to attend to reach required % |
| `will_pass(attended, total, remaining)` | `bool` | Whether passing is still achievable |
| `projected_attendance(attended, total, extra_classes)` | `float` | % if all future classes are attended |
| `minimum_to_pass(attended, total, remaining)` | `int` | Minimum classes to attend from remaining |
| `bunk_streak(attended, total)` | `int` | Max classes that can be skipped in a row |
| `attendance_summary(attended, total, remaining)` | `dict` | Complete attendance report |

---

## Error Handling

```python
try:
    attendancex.calculate_percentage(attended=45, total=0)
except ValueError as e:
    print(e)
# → 'total' must be greater than zero

try:
    attendancex.calculate_percentage(attended=70, total=60)
except ValueError as e:
    print(e)
# → 'attended' cannot be greater than 'total'
```

---

## License

MIT — free to use, modify, and distribute.

