studentpybox 0.1.0__tar.gz

studentpybox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talha_main
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

studentpybox-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: studentpybox
+Version: 0.1.0
+Summary: A simple Python toolkit for university students: GPA tools and study planning helpers.
+Author-email: Talha_main <450talhatahir@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YOUR_GITHUB_USERNAME/studentpybox
+Keywords: gpa,student,university,study,pomodoro,education
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Education
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# studentpybox
+
+A simple Python toolkit for university students, with two modules: **GPA tools** and **study planning helpers**.
+
+## Installation
+
+```bash
+pip install studentpybox
+```
+
+## Modules & Functions
+
+### `studentpybox.gpa`
+
+| Function | Description |
+|---|---|
+| `calculate_gpa(grades, credits)` | Credit-weighted GPA from a list of grade points and credit hours. |
+| `percentage_to_grade(percentage)` | Convert a percentage score into a letter grade. |
+| `cgpa_predictor(current_cgpa, completed_credits, target_cgpa, upcoming_credits)` | GPA needed in upcoming courses to hit a target CGPA. |
+| `attendance_needed(attended, total, target_percentage=75.0)` | Classes still needed (or classes that can be skipped) to meet an attendance target. |
+
+### `studentpybox.study`
+
+| Function | Description |
+|---|---|
+| `pomodoro_timer_text(work_minutes=25, break_minutes=5, sessions=4)` | Printable Pomodoro study schedule. |
+| `random_motivation()` | A random short motivational line. |
+| `study_hours_left(total_hours_needed, hours_completed)` | Remaining study hours and progress percentage. |
+| `exam_countdown(exam_date, date_format="%Y-%m-%d")` | Days left until an exam date. |
+
+## Usage
+
+```python
+from studentpybox import calculate_gpa, percentage_to_grade, random_motivation, exam_countdown
+
+print(calculate_gpa([4.0, 3.3, 3.7], [3, 4, 3]))   # 3.63
+print(percentage_to_grade(82))                      # B+
+print(random_motivation())                          # a random study quote
+print(exam_countdown("2026-07-15"))                  # {'days_left': ..., 'status': 'upcoming'}
+```
+
+## License
+
+MIT

studentpybox-0.1.0/README.md

@@ -0,0 +1,44 @@
+# studentpybox
+
+A simple Python toolkit for university students, with two modules: **GPA tools** and **study planning helpers**.
+
+## Installation
+
+```bash
+pip install studentpybox
+```
+
+## Modules & Functions
+
+### `studentpybox.gpa`
+
+| Function | Description |
+|---|---|
+| `calculate_gpa(grades, credits)` | Credit-weighted GPA from a list of grade points and credit hours. |
+| `percentage_to_grade(percentage)` | Convert a percentage score into a letter grade. |
+| `cgpa_predictor(current_cgpa, completed_credits, target_cgpa, upcoming_credits)` | GPA needed in upcoming courses to hit a target CGPA. |
+| `attendance_needed(attended, total, target_percentage=75.0)` | Classes still needed (or classes that can be skipped) to meet an attendance target. |
+
+### `studentpybox.study`
+
+| Function | Description |
+|---|---|
+| `pomodoro_timer_text(work_minutes=25, break_minutes=5, sessions=4)` | Printable Pomodoro study schedule. |
+| `random_motivation()` | A random short motivational line. |
+| `study_hours_left(total_hours_needed, hours_completed)` | Remaining study hours and progress percentage. |
+| `exam_countdown(exam_date, date_format="%Y-%m-%d")` | Days left until an exam date. |
+
+## Usage
+
+```python
+from studentpybox import calculate_gpa, percentage_to_grade, random_motivation, exam_countdown
+
+print(calculate_gpa([4.0, 3.3, 3.7], [3, 4, 3]))   # 3.63
+print(percentage_to_grade(82))                      # B+
+print(random_motivation())                          # a random study quote
+print(exam_countdown("2026-07-15"))                  # {'days_left': ..., 'status': 'upcoming'}
+```
+
+## License
+
+MIT

studentpybox-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "studentpybox"
+version = "0.1.0"
+description = "A simple Python toolkit for university students: GPA tools and study planning helpers."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Talha_main", email = "450talhatahir@gmail.com" }
+]
+keywords = ["gpa", "student", "university", "study", "pomodoro", "education"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Education",
+    "Topic :: Education",
+]
+
+[project.urls]
+Homepage = "https://github.com/YOUR_GITHUB_USERNAME/studentpybox"
+
+[tool.setuptools.packages.find]
+where = ["src"]

studentpybox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

studentpybox-0.1.0/src/studentpybox/__init__.py

@@ -0,0 +1,36 @@
+"""
+studentpybox - A simple Python toolkit for university students.
+
+Modules:
+    gpa   - GPA calculation, grading, and attendance helpers.
+    study - Study planning and motivation helpers.
+
+All functions are also importable directly from the top-level package, e.g.:
+    from studentpybox import calculate_gpa, random_motivation
+"""
+
+from .gpa import (
+    calculate_gpa,
+    percentage_to_grade,
+    cgpa_predictor,
+    attendance_needed,
+)
+from .study import (
+    pomodoro_timer_text,
+    random_motivation,
+    study_hours_left,
+    exam_countdown,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "calculate_gpa",
+    "percentage_to_grade",
+    "cgpa_predictor",
+    "attendance_needed",
+    "pomodoro_timer_text",
+    "random_motivation",
+    "study_hours_left",
+    "exam_countdown",
+]

studentpybox-0.1.0/src/studentpybox/gpa.py

@@ -0,0 +1,166 @@
+"""
+gpa.py - GPA, grading, and attendance helpers for university students.
+"""
+
+from __future__ import annotations
+
+# Standard 4.0-scale grade boundaries used by percentage_to_grade().
+# Each tuple is (minimum percentage, letter grade, grade point).
+_GRADE_TABLE = [
+    (90, "A", 4.0),
+    (85, "A-", 3.7),
+    (80, "B+", 3.3),
+    (75, "B", 3.0),
+    (70, "B-", 2.7),
+    (65, "C+", 2.3),
+    (60, "C", 2.0),
+    (55, "C-", 1.7),
+    (50, "D", 1.0),
+    (0, "F", 0.0),
+]
+
+
+def calculate_gpa(grades: list[float], credits: list[float]) -> float:
+    """
+    Calculate a credit-weighted GPA.
+
+    Args:
+        grades: Grade points earned per course (e.g. [4.0, 3.3, 3.7]).
+        credits: Credit hours for each course, same order as grades.
+
+    Returns:
+        The weighted GPA rounded to 2 decimal places.
+
+    Example:
+        >>> calculate_gpa([4.0, 3.3, 3.7], [3, 4, 3])
+        3.63
+    """
+    if not grades or not credits:
+        raise ValueError("grades and credits cannot be empty")
+    if len(grades) != len(credits):
+        raise ValueError("grades and credits must have the same length")
+    if any(c <= 0 for c in credits):
+        raise ValueError("credits must be positive numbers")
+
+    total_points = sum(g * c for g, c in zip(grades, credits))
+    total_credits = sum(credits)
+    return round(total_points / total_credits, 2)
+
+
+def percentage_to_grade(percentage: float) -> str:
+    """
+    Convert a percentage score into a letter grade.
+
+    Args:
+        percentage: Score between 0 and 100.
+
+    Returns:
+        A letter grade, e.g. "A", "B+", "C-", "F".
+
+    Example:
+        >>> percentage_to_grade(82)
+        'B+'
+    """
+    if not 0 <= percentage <= 100:
+        raise ValueError("percentage must be between 0 and 100")
+
+    for minimum, letter, _ in _GRADE_TABLE:
+        if percentage >= minimum:
+            return letter
+    return "F"  # unreachable, but keeps type-checkers happy
+
+
+def cgpa_predictor(
+    current_cgpa: float,
+    completed_credits: float,
+    target_cgpa: float,
+    upcoming_credits: float,
+) -> float:
+    """
+    Estimate the GPA needed in upcoming courses to reach a target CGPA.
+
+    Args:
+        current_cgpa: CGPA earned so far.
+        completed_credits: Total credit hours completed so far.
+        target_cgpa: The CGPA the student wants to reach.
+        upcoming_credits: Credit hours still to be taken.
+
+    Returns:
+        The GPA required in the upcoming credits, rounded to 2 decimals.
+        Can exceed 4.0 (or whatever your scale's max is) if the target
+        is no longer mathematically reachable -- the caller should
+        compare the result against their grading scale's maximum.
+
+    Example:
+        >>> cgpa_predictor(3.2, 60, 3.5, 20)
+        4.4
+    """
+    if completed_credits <= 0 or upcoming_credits <= 0:
+        raise ValueError("credits must be positive numbers")
+
+    total_credits = completed_credits + upcoming_credits
+    required_total_points = target_cgpa * total_credits
+    current_points = current_cgpa * completed_credits
+    required_gpa = (required_total_points - current_points) / upcoming_credits
+    return round(required_gpa, 2)
+
+
+def attendance_needed(
+    attended: int, total: int, target_percentage: float = 75.0
+) -> dict:
+    """
+    Work out attendance status against a target percentage.
+
+    Args:
+        attended: Classes attended so far.
+        total: Total classes held so far.
+        target_percentage: Required attendance percentage (default 75%).
+
+    Returns:
+        A dict with keys:
+            "current_percentage": current attendance percentage,
+            "status": "safe" or "short",
+            "classes_to_attend": consecutive classes still needed to
+                reach the target (0 if already met),
+            "classes_can_skip": consecutive classes that can still be
+                missed while staying at/above the target (0 if short).
+
+    Example:
+        >>> attendance_needed(28, 40, 75)
+        {'current_percentage': 70.0, 'status': 'short', 'classes_to_attend': 8, 'classes_can_skip': 0}
+    """
+    if total <= 0:
+        raise ValueError("total must be greater than 0")
+    if attended < 0 or attended > total:
+        raise ValueError("attended must be between 0 and total")
+    if not 0 < target_percentage <= 100:
+        raise ValueError("target_percentage must be between 0 and 100")
+
+    current_percentage = round((attended / total) * 100, 2)
+
+    if current_percentage >= target_percentage:
+        # How many more classes (all missed) could the student skip
+        # before dropping below the target?
+        can_skip = 0
+        while (attended) / (total + can_skip + 1) * 100 >= target_percentage:
+            can_skip += 1
+        return {
+            "current_percentage": current_percentage,
+            "status": "safe",
+            "classes_to_attend": 0,
+            "classes_can_skip": can_skip,
+        }
+    else:
+        # How many more classes (all attended) are needed to reach target?
+        need = 0
+        a, t = attended, total
+        while (a / t) * 100 < target_percentage:
+            a += 1
+            t += 1
+            need += 1
+        return {
+            "current_percentage": current_percentage,
+            "status": "short",
+            "classes_to_attend": need,
+            "classes_can_skip": 0,
+        }

studentpybox-0.1.0/src/studentpybox/study.py

@@ -0,0 +1,143 @@
+"""
+study.py - Study planning and motivation helpers for university students.
+"""
+
+from __future__ import annotations
+
+import random
+from datetime import datetime, date
+
+
+# Original, short motivational lines (no external/copyrighted quotes).
+_MOTIVATION_LINES = [
+    "Small steps every day add up to big results. Open the book.",
+    "You don't need to feel motivated to start -- starting creates the motivation.",
+    "Future you is counting on the work you put in right now.",
+    "Progress, not perfection. One page at a time.",
+    "The hardest part is opening the laptop. You've already done it.",
+    "Tired brains still learn -- just take it slow and keep going.",
+    "Every concept you understand today is one less thing to fear at exam time.",
+    "You've survived 100% of your hard days so far. This one's no different.",
+    "Done is better than perfect. Submit the draft, polish later.",
+    "Your only competition is who you were yesterday.",
+]
+
+
+def pomodoro_timer_text(
+    work_minutes: int = 25, break_minutes: int = 5, sessions: int = 4
+) -> str:
+    """
+    Generate a printable Pomodoro study schedule.
+
+    Args:
+        work_minutes: Length of each focused work block (default 25).
+        break_minutes: Length of each short break (default 5).
+        sessions: Number of work/break cycles (default 4).
+
+    Returns:
+        A formatted multi-line schedule string, e.g.:
+        "Session 1: Study 25 min -> Break 5 min
+         Session 2: Study 25 min -> Break 5 min
+         ...
+         Total focused study time: 100 min"
+
+    Example:
+        >>> print(pomodoro_timer_text(25, 5, 2))
+        Session 1: Study 25 min -> Break 5 min
+        Session 2: Study 25 min -> Break 5 min
+        Total focused study time: 50 min
+    """
+    if work_minutes <= 0 or break_minutes <= 0 or sessions <= 0:
+        raise ValueError("work_minutes, break_minutes, and sessions must be positive")
+
+    lines = [
+        f"Session {i}: Study {work_minutes} min -> Break {break_minutes} min"
+        for i in range(1, sessions + 1)
+    ]
+    lines.append(f"Total focused study time: {work_minutes * sessions} min")
+    return "\n".join(lines)
+
+
+def random_motivation() -> str:
+    """
+    Return a random, short motivational line for studying.
+
+    Returns:
+        A motivational sentence as a string.
+
+    Example:
+        >>> isinstance(random_motivation(), str)
+        True
+    """
+    return random.choice(_MOTIVATION_LINES)
+
+
+def study_hours_left(total_hours_needed: float, hours_completed: float) -> dict:
+    """
+    Track remaining study hours against a goal.
+
+    Args:
+        total_hours_needed: Total hours planned for a subject/exam.
+        hours_completed: Hours already studied.
+
+    Returns:
+        A dict with keys:
+            "hours_remaining": hours still left (never negative),
+            "percent_complete": progress percentage, rounded to 1 decimal,
+            "status": "done" if the goal is met, otherwise "in_progress".
+
+    Example:
+        >>> study_hours_left(20, 8)
+        {'hours_remaining': 12, 'percent_complete': 40.0, 'status': 'in_progress'}
+    """
+    if total_hours_needed <= 0:
+        raise ValueError("total_hours_needed must be greater than 0")
+    if hours_completed < 0:
+        raise ValueError("hours_completed cannot be negative")
+
+    remaining = max(total_hours_needed - hours_completed, 0)
+    percent = round(min(hours_completed / total_hours_needed, 1) * 100, 1)
+    status = "done" if remaining == 0 else "in_progress"
+
+    return {
+        "hours_remaining": remaining,
+        "percent_complete": percent,
+        "status": status,
+    }
+
+
+def exam_countdown(exam_date: str, date_format: str = "%Y-%m-%d") -> dict:
+    """
+    Calculate how much time is left until an exam.
+
+    Args:
+        exam_date: The exam date as a string, e.g. "2026-07-15".
+        date_format: The format exam_date is given in (default "%Y-%m-%d").
+
+    Returns:
+        A dict with keys:
+            "days_left": full days remaining (0 if today, negative if past),
+            "status": "upcoming", "today", or "past".
+
+    Example:
+        >>> exam_countdown("2099-01-01")  # doctest: +SKIP
+        {'days_left': ..., 'status': 'upcoming'}
+    """
+    try:
+        target = datetime.strptime(exam_date, date_format).date()
+    except ValueError as exc:
+        raise ValueError(
+            f"exam_date '{exam_date}' does not match format '{date_format}'"
+        ) from exc
+
+    today = date.today()
+    days_left = (target - today).days
+
+    if days_left > 0:
+        status = "upcoming"
+    elif days_left == 0:
+        status = "today"
+    else:
+        status = "past"
+
+    return {"days_left": days_left, "status": status}

studentpybox-0.1.0/src/studentpybox.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: studentpybox
+Version: 0.1.0
+Summary: A simple Python toolkit for university students: GPA tools and study planning helpers.
+Author-email: Talha_main <450talhatahir@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YOUR_GITHUB_USERNAME/studentpybox
+Keywords: gpa,student,university,study,pomodoro,education
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Education
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# studentpybox
+
+A simple Python toolkit for university students, with two modules: **GPA tools** and **study planning helpers**.
+
+## Installation
+
+```bash
+pip install studentpybox
+```
+
+## Modules & Functions
+
+### `studentpybox.gpa`
+
+| Function | Description |
+|---|---|
+| `calculate_gpa(grades, credits)` | Credit-weighted GPA from a list of grade points and credit hours. |
+| `percentage_to_grade(percentage)` | Convert a percentage score into a letter grade. |
+| `cgpa_predictor(current_cgpa, completed_credits, target_cgpa, upcoming_credits)` | GPA needed in upcoming courses to hit a target CGPA. |
+| `attendance_needed(attended, total, target_percentage=75.0)` | Classes still needed (or classes that can be skipped) to meet an attendance target. |
+
+### `studentpybox.study`
+
+| Function | Description |
+|---|---|
+| `pomodoro_timer_text(work_minutes=25, break_minutes=5, sessions=4)` | Printable Pomodoro study schedule. |
+| `random_motivation()` | A random short motivational line. |
+| `study_hours_left(total_hours_needed, hours_completed)` | Remaining study hours and progress percentage. |
+| `exam_countdown(exam_date, date_format="%Y-%m-%d")` | Days left until an exam date. |
+
+## Usage
+
+```python
+from studentpybox import calculate_gpa, percentage_to_grade, random_motivation, exam_countdown
+
+print(calculate_gpa([4.0, 3.3, 3.7], [3, 4, 3]))   # 3.63
+print(percentage_to_grade(82))                      # B+
+print(random_motivation())                          # a random study quote
+print(exam_countdown("2026-07-15"))                  # {'days_left': ..., 'status': 'upcoming'}
+```
+
+## License
+
+MIT

studentpybox-0.1.0/src/studentpybox.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/studentpybox/__init__.py
+src/studentpybox/gpa.py
+src/studentpybox/study.py
+src/studentpybox.egg-info/PKG-INFO
+src/studentpybox.egg-info/SOURCES.txt
+src/studentpybox.egg-info/dependency_links.txt
+src/studentpybox.egg-info/top_level.txt
+tests/test_studentpybox.py

studentpybox-0.1.0/src/studentpybox.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

studentpybox-0.1.0/src/studentpybox.egg-info/top_level.txt

@@ -0,0 +1 @@
+studentpybox

studentpybox-0.1.0/tests/test_studentpybox.py

@@ -0,0 +1,60 @@
+from studentpybox import (
+    calculate_gpa,
+    percentage_to_grade,
+    cgpa_predictor,
+    attendance_needed,
+    pomodoro_timer_text,
+    random_motivation,
+    study_hours_left,
+    exam_countdown,
+)
+
+
+def test_calculate_gpa():
+    assert calculate_gpa([4.0, 3.3, 3.7], [3, 4, 3]) == 3.63
+
+
+def test_percentage_to_grade():
+    assert percentage_to_grade(95) == "A"
+    assert percentage_to_grade(82) == "B+"
+    assert percentage_to_grade(40) == "F"
+
+
+def test_cgpa_predictor():
+    assert cgpa_predictor(3.2, 60, 3.5, 20) == 4.4
+
+
+def test_attendance_needed_short():
+    result = attendance_needed(28, 40, 75)
+    assert result["status"] == "short"
+    assert result["classes_to_attend"] == 8
+
+
+def test_attendance_needed_safe():
+    result = attendance_needed(38, 40, 75)
+    assert result["status"] == "safe"
+    assert result["classes_to_attend"] == 0
+
+
+def test_pomodoro_timer_text():
+    text = pomodoro_timer_text(25, 5, 2)
+    assert "Session 1" in text
+    assert "Total focused study time: 50 min" in text
+
+
+def test_random_motivation():
+    assert isinstance(random_motivation(), str)
+    assert len(random_motivation()) > 0
+
+
+def test_study_hours_left():
+    result = study_hours_left(20, 8)
+    assert result["hours_remaining"] == 12
+    assert result["percent_complete"] == 40.0
+    assert result["status"] == "in_progress"
+
+
+def test_exam_countdown_upcoming():
+    result = exam_countdown("2099-01-01")
+    assert result["status"] == "upcoming"
+    assert result["days_left"] > 0