Metadata-Version: 2.4
Name: attendancex
Version: 0.1.1
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
```

---

## Quick Example

All examples below use:
- `attended` — number of classes you have attended so far
- `total` — total number of classes held so far
- `remaining` — number of classes yet to be held this semester
  (e.g. if semester has 80 total classes and 60 are done, remaining = 20)

```python
import attendancex

# What is my 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 without falling below 75%?
# attended=49 out of total=60 — I have some buffer
attendancex.safe_bunks(attended=49, total=60)
# → 4  (I can skip 4 more classes safely)

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

# 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 attendance be?
# attended=45, total=60, extra_classes=10 upcoming
attendancex.projected_attendance(attended=45, total=60, extra_classes=10)
# → 78.57%

# What is the minimum number of remaining classes I must attend to pass?
# attended=45, total=60 held, remaining=20 classes left
attendancex.minimum_to_pass(attended=45, total=60, remaining=20)
# → 15  (must attend at least 15 out of the 20 remaining classes)

# 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  (can skip 5 consecutive classes before dropping below 75%)

# Get a complete 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 still be skipped
#     'classes_needed': 0,        # classes needed to recover (0 = already passing)
#     'will_pass': True,          # can you still pass this semester?
#     'projected_attendance': 81.25,  # % if all remaining classes are attended
#     'minimum_to_pass': 15,      # minimum classes to attend from remaining
#     'bunk_streak': 0            # max consecutive classes that can be skipped
#   }
```

---

## All Functions

| Function | Parameters | 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 |

---

## Custom Attendance Requirement

By default, all functions use **75%** as the minimum required attendance.

If your college has a different requirement, pass it using `required_percent`:

```python
# Default — 75% minimum requirement
attendancex.safe_bunks(attended=49, total=60)
# → 4  (can skip 4 classes)

# Custom — 80% minimum requirement
attendancex.safe_bunks(attended=49, total=60, required_percent=80)
# → 1  (can skip only 1 class)

# Works with all functions
attendancex.attendance_summary(attended=45, total=60, remaining=20, required_percent=80)
```

---

## Error Handling

`attendancex` raises clear exceptions for invalid inputs — no silent failures.

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

# Attended cannot be more than total
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.

