rhul-attendance-bot 0.1.48__py3-none-any.whl

rhul_attendance_bot-0.1.48.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: rhul-attendance-bot
+Version: 0.1.48
+Summary: RHUL attendance automation bot
+Author: PandaQuQ
+License: 
+        MIT License
+        
+        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, 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.
+        
+        [Additional Clause]
+        For any commercial use, attribution to the original author (PandaQuQ) is required.
+        
+        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.
+        
+Project-URL: Repository, https://github.com/PandaQuQ/RHUL_attendance_bot
+Keywords: automation,attendance,selenium,rhul
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ics
+Requires-Dist: rich
+Requires-Dist: selenium
+Requires-Dist: webdriver-manager
+Requires-Dist: pynput
+Requires-Dist: ntplib
+Requires-Dist: pyotp
+Dynamic: license-file
+
+# RHUL Attendance Bot
+[中文](https://github.com/PandaQuQ/RHUL_attendance_bot/blob/main/README_CN.md)
+---
+![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)
+![Version No.](https://img.shields.io/github/commits-since/PandaQuQ/RHUL_attendance_bot/b80f0cf6c4b060ebf318bff844607af06225e6b0?label=Version%20No.)
+![Last Updated](https://img.shields.io/github/last-commit/PandaQuQ/RHUL_attendance_bot)
+
+The RHUL Attendance Bot automates attendance marking for Royal Holloway students by using web automation. The script checks your calendar events, triggers attendance based on specified conditions, and provides real-time logging using Rich library for better visualization.
+![UI screenshot](assets/ui_screenshot.png)
+![Discord broadcast screenshot](assets/discord_bot_screenshot.png)
+## Features
+
+- **Automated Attendance**: Automatically opens the attendance page and marks your attendance based on your calendar events.
+- **Manual Trigger**: Allows manual attendance marking via keyboard shortcuts.
+- **Real-Time Logging**: Displays logs using Rich library for a better visual experience.
+- **Environment and Dependency Checks**: Ensures the script is run in the proper environment and all dependencies are installed.
+- **System Time Synchronization Check**: Checks if the system time is synchronized with the NTP server.
+- **Auto-Update Feature**: Detects script updates and prompts the user to update.
+- **Auto Login with 2FA**: Handles Microsoft login, switches to verification code, and auto-fills TOTP from your saved secret.
+- **Automatic Timetable Download**: On first run, automatically fetches your ICS timetable into the `ics/` folder—no manual download needed.
+- **Discord Webhook Notifications (optional)**: Sends start/stop, login success, and attendance success messages with your profile name when a webhook URL is configured.
+
+## Prerequisites
+
+1. **Python 3.9 or above**: Ensure that Python is installed. If not, download and install it from [python.org](https://www.python.org/downloads/).
+2. **Google Chrome Browser**: The script uses Chrome for web automation. Make sure it is installed.
+3. **Virtual Environment (Recommended)**: Run the script inside a Python virtual environment to avoid dependency conflicts.
+
+## Installation
+
+Install Google Chrome if you don't have it yet: [download page](https://www.google.com/chrome/) (macOS users can also `brew install --cask google-chrome`).
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/PandaQuQ/RHUL_attendance_bot.git
+```
+
+### Step 2: Navigate to the Project Directory
+
+```bash
+cd RHUL_attendance_bot
+```
+
+### Step 3: Set Up a Virtual Environment (Recommended)
+
+#### On Windows:
+```bash
+python -m venv venv
+venv\Scripts\activate
+```
+
+#### On macOS/Linux:
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### Step 4: Install Dependencies
+
+#### Option A: Install from PyPI (recommended)
+
+```bash
+pip install rhul-attendance-bot
+```
+
+#### Option B: Install from source
+
+```bash
+pip install -r requirements.txt
+```
+
+### Step 5: (Optional) Prepare ICS Manually
+
+The bot now auto-downloads your timetable on first run and stores it in `ics/`. You only need manual prep if the auto download fails:
+
+- Go to [Royal Holloway Timetable](https://intranet.royalholloway.ac.uk/students/study/timetable/your-timetable.aspx) and log in.
+- Choose `Calendar Download`, click `View Timetable`, then `Android™ and others` to get the `.ics` link.
+- Download the `.ics` and place it into the `ics` folder at the project root (create it if missing).
+
+## Usage
+
+1. **Navigate to the Script Directory**:
+
+   ```bash
+   cd RHUL_attendance_bot
+   ```
+
+2. **Activate the Virtual Environment**:
+
+   #### On Windows:
+   ```bash
+   venv\Scripts\activate
+   ```
+
+   #### On macOS/Linux:
+   ```bash
+   source venv/bin/activate
+   ```
+
+3. **Run the Script**:
+
+   #### From PyPI install:
+   ```bash
+   rhul-attendance-bot
+   ```
+
+   #### From source:
+   ```bash
+   python RHUL_attendance_bot.py
+   ```
+
+   > **✅ Auto Login + 2FA**
+   > 
+   > The bot now handles Microsoft login and the verification-code MFA flow automatically using your stored credentials and local TOTP secret. On first run, complete onboarding (credentials/secret); the timetable is downloaded automatically.
+
+4. **Profile Selection**:
+
+    - Use `-user <profile_name>` to pick a specific profile, e.g.:
+       ```bash
+       rhul-attendance-bot -user Alice
+       ```
+    - If `-user` is not provided, the app will list existing profiles and ask you to choose (or create a new one).
+
+5. **Keyboard Shortcuts**:
+
+   - **Manually Trigger the Next Event**: Press `[`, then `]`
+   - **Exit the Script**: Press `[`, then `q`
+
+## Important Notes
+
+- **Dependencies**: Make sure all required dependencies are installed by following the instructions in the `requirements.txt` file.
+- **Virtual Environment**: Using a virtual environment is highly recommended to avoid conflicts with global packages.
+- **System Time**: If the system time is not synchronized with the NTP server, the script will prompt you to synchronize your system clock.
+- **Supported Platforms**: The script supports Windows, macOS, and Linux.
+
+### Multi-Profile Usage
+
+Profiles are stored under `~/.rhul_attendance_bot/profiles/<profile_name>`. Each profile has its own:
+
+- `credentials.json`
+- `2fa_config.json`
+- `ics/`
+- `chrome_user_data/`
+- `automation.log`
+
+Use `-user` to switch profiles at runtime.
+
+> **🔐 Security Note - Login Session Duration**
+> 
+> ~~A session typically lasts about one week; you may need to manually re-login after it expires.~~
+> The bot now auto-renews login with stored credentials + TOTP. Sessions are refreshed automatically; monitor occasionally in case the institution changes its 2FA policy.
+
+## Configuration
+
+To configure the script, modify the relevant parameters inside the code or create a configuration file (not provided in this version). Future versions may include more flexible configuration options.
+
+## Updating
+
+If an update is detected, the script will prompt you to update. You can choose to update by typing `y` or skip it by typing `n`.
+
+## Troubleshooting
+
+1. **Chrome WebDriver Issues**: Make sure that the correct version of the ChromeDriver is being used. The script uses `webdriver-manager` to automatically manage ChromeDriver versions.
+2. **Dependency Issues**: If you encounter errors related to missing modules, reinstall via `pip install rhul-attendance-bot` or use `pip install -r requirements.txt` from source.
+3. **Virtual Environment Issues**: If you face issues while running the script, try setting up a fresh virtual environment and reinstalling the dependencies.
+
+## TODO
+
+Current focus / future ideas:
+
+- ✅ **2FA Integration**: Microsoft verification-code path with TOTP auto-fill is implemented.
+- ✅ **Automatic Login**: Stored credentials + TOTP drive a fully automatic login flow.
+- ✅ **2FA Code Reading**: OTP is generated locally from your saved secret.
+- ✅ **Discord Webhook Bot**: Discord webhook notifications for attendance status, login, and lifecycle (optional; disable by leaving webhook URL empty)
+
+## License
+
+This project is licensed under the MIT License with an additional clause. See the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Thanks to the developers of [Rich](https://github.com/Textualize/rich), [Selenium](https://www.selenium.dev/), and [ics.py](https://github.com/C4ptainCrunch/ics.py) for their amazing libraries.
+
+## Contact
+
+For questions or suggestions, please feel free to reach out via the [GitHub repository](https://github.com/PandaQuQ/RHUL_attendance_bot). Feedback and contributions are welcome!

rhul_attendance_bot-0.1.48.dist-info/RECORD

@@ -0,0 +1,14 @@
+RHUL_attendance_bot.py,sha256=J-5aSVrfGL1gjlGgsBcb_QYW4OEXL81mFVL0kLgqE-I,24193
+app_paths.py,sha256=1VnUSQBaXCbAzDjivhCHyRTZJ3aHKMj6ewkcaMVDuHg,2161
+auto_login.py,sha256=CfSr2kiUz7SyfEAHDaZmisiSXO3RXuSUIm_QU087iEE,34654
+discord_broadcast.py,sha256=0hRJ_vronQK_TvRgC06NNWxaj8892h-Q7Hzmrp3-lB4,2615
+display_manager.py,sha256=iRPWxwFiQWSvWl-QazKsiaLbvX2T7LPPFItfMZ52-Yg,11079
+fetch_ics.py,sha256=5G2SYuYALqRxmT8TqUMTvNBvMHeoXuJueI9agyyApKs,4617
+local_2fa.py,sha256=2PY6XtczgIxjKqWls9DeN27MWLIiNKbQdk9E3GZVJxU,729
+update.py,sha256=kw_KWBJLu20JpMMmJQAAxu2ZZIlcUeRxppaVGr3S1r8,2354
+rhul_attendance_bot-0.1.48.dist-info/licenses/LICENSE,sha256=iBk7hceb7NgwcLnsFlT_v2SE2-m9i8CzsjlvBw8xmPg,1075
+rhul_attendance_bot-0.1.48.dist-info/METADATA,sha256=gx0sOQD_9mo0QzcFONZZHET94OD9-NFQPvIi7fzNze0,9721
+rhul_attendance_bot-0.1.48.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+rhul_attendance_bot-0.1.48.dist-info/entry_points.txt,sha256=TH2lA3ukDDxlnFr2CIy0xd1ZbsaO6FMjuUTDUIbkShs,65
+rhul_attendance_bot-0.1.48.dist-info/top_level.txt,sha256=TABKd3ZTI6hvA899O5XSRt0lk58h9dxrv6QHChtJqmU,102
+rhul_attendance_bot-0.1.48.dist-info/RECORD,,

rhul_attendance_bot-0.1.48.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rhul_attendance_bot-0.1.48.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rhul-attendance-bot = RHUL_attendance_bot:main

rhul_attendance_bot-0.1.48.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+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, 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.
+
+[Additional Clause]
+For any commercial use, attribution to the original author (PandaQuQ) is required.
+
+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.

rhul_attendance_bot-0.1.48.dist-info/top_level.txt

@@ -0,0 +1,8 @@
+RHUL_attendance_bot
+app_paths
+auto_login
+discord_broadcast
+display_manager
+fetch_ics
+local_2fa
+update

update.py

@@ -0,0 +1,67 @@
+import os
+import sys
+import time
+import threading
+import subprocess
+import logging
+
+
+def _prompt_update_with_timeout(timeout=10):
+    user_input = {"val": None}
+
+    def _reader():
+        try:
+            user_input["val"] = input().strip().lower()
+        except Exception:
+            user_input["val"] = None
+
+    t = threading.Thread(target=_reader, daemon=True)
+    t.start()
+    for remaining in range(timeout, 0, -1):
+        if user_input["val"] is not None:
+            break
+        print(
+            f"\rA new update is available. Update now? (y/n) Auto-skip in {remaining}s: ",
+            end="",
+            flush=True,
+        )
+        time.sleep(1)
+    print()
+    return user_input["val"]
+
+
+def check_for_updates(logger=None, timeout=10):
+    try:
+        if not os.path.isdir(os.path.join(os.getcwd(), ".git")):
+            if logger:
+                logger.info("Update check skipped (no git repo detected).", extra={"gray": True})
+            return
+        local_commit = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()
+        remote_commit = subprocess.check_output(["git", "ls-remote", "origin", "HEAD"]).decode().split()[0]
+        if local_commit != remote_commit:
+            if logger:
+                logger.info("New update detected.")
+            user_input = _prompt_update_with_timeout(timeout=timeout)
+            if user_input in ("", "y", "yes"):
+                if logger:
+                    logger.info("Updating the script...")
+                subprocess.check_call(["git", "pull"])
+                if logger:
+                    logger.info("Update successful. Restarting the script...")
+                os.execv(sys.executable, [sys.executable] + sys.argv)
+            else:
+                if logger:
+                    logger.info("Skipping update. Continuing with the current version.")
+        else:
+            if logger:
+                logger.info("No updates found. Continuing execution.", extra={"gray": True})
+    except (FileNotFoundError, subprocess.CalledProcessError) as e:
+        if logger:
+            logger.info("Update check skipped (git not available).", extra={"gray": True})
+        else:
+            raise
+    except Exception as e:
+        if logger:
+            logger.error(f"Failed to check for updates: {e}", exc_info=True)
+        else:
+            raise