attendancex 0.1.1

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

---

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)

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:

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

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