attendancex 0.1.0

A lightweight Python library for attendance calculations

attendancex

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

---

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

pip install attendancex

---

Usage

import attendancex

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

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

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

---

Examples

# 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

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.