An automation helper to submit weekly attendance codes. Now in Public Beta.
⚠️ Use responsibly and follow your institution’s policies.

中文文档

Choose one method to get the folder onto your computer:

• Install Git: https://git-scm.com/downloads
• macOS/Linux:

git clone https://github.com/bunizao/always-attend.git
cd always-attend

• Windows (PowerShell or Command Prompt):

git clone https://github.com/bunizao/always-attend.git
cd always-attend

• Open the project page: https://github.com/bunizao/always-attend
• Click the green "Code" button → "Download ZIP"
• Or direct ZIP link: https://github.com/bunizao/always-attend/archive/refs/heads/main.zip
• Extract the ZIP:
  • Windows: right‑click the ZIP → "Extract All..."
  • macOS: double‑click the ZIP to extract
• Open the extracted always-attend folder

• macOS: double‑click Always-Attend.command
• Windows: double‑click Always-Attend.bat or right‑click Always-Attend.ps1 → Run with PowerShell
• The first run will guide setup automatically

Double‑click to run with the enhanced first‑time setup:

• macOS: double‑click Always-Attend.command
• Windows: double‑click Always-Attend.bat (or run Always-Attend.ps1)

Want to drop a single file on another machine and get going? Run the bundled launch.py script:

• Prompts for the install location (defaults to the current folder)
• Clones always-attend, creates/updates .venv, installs dependencies, and copies .env.example
• Lets you choose UI login, headless mode, or --dry-run, then runs main.py or prints the launch command
• Perfect for rapid sharing in chats or classrooms—just send launch.py, then run python launch.py

The application follows a structured 4-step workflow with multiple execution modes:

1. Environment Setup - Bootstrap and install dependencies
2. Python Check - Verify Python environment and packages
3. App Start - Load config, privacy policy, and first-run setup
4. Choose Mode - Select execution mode:

• 🔍 Stats (--stats) - View attendance statistics (read-only)
• 📤 Submit (default) - Main workflow for code submission
• 🔑 Login Only (--login-only) - Refresh session and exit

When using Submit mode, the application follows this sequence:

1. Session Check → Sign-in if needed
2. Submission → Dry-run or submit codes
3. Done → Save results and exit

When using Login Only mode:

1. Session Check → Sign-in if needed
2. Done → Exit after refreshing session

# Basic execution
python main.py

# View statistics
python main.py --stats

# Refresh login session
python main.py --login-only

# Run specific week
python main.py --week 4

# Show browser (headed mode)
python main.py --headed

Why uv?

• 🔒 Deterministic installs via uv.lock so every machine shares the same dependency graph.
• ⚡ Rust-powered resolver/installer that is noticeably faster than pip + venv.
• 🧪 uv sync keeps the virtual env fresh without manual activation juggling (uv run … handles it).
• 🌍 Handles Python download/management when the requested interpreter is missing.

1. Install uv if it is not already available:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. From the project root, sync dependencies and refresh the local virtual environment:

   uv sync

3. Install the Chromium browser bundle for Playwright:

   uv run python -m playwright install chromium

4. Launch the CLI (examples):

   uv run python main.py --dry-run
   uv run python main.py --login-only

python3 -m venv .venv
source .venv/bin/activate    # Windows: .\.venv\Scripts\activate
pip install -U pip
pip install -r requirements.txt
python -m playwright install chromium
python main.py

What the launchers do:

• Check for Python (and Git if available)
• Create/activate a virtualenv and install dependencies on first run
• Run a first‑time setup wizard (portal URL, credentials, week, browser)
• Auto‑detect the latest week from data/*/*.json and set WEEK_NUMBER

Update later:

git pull

Always Attend now reads attendance codes exclusively from the data/ directory (or the folder specified by CODES_DB_PATH). Each course gets its own subfolder and every week is represented by a JSON file:

data/
  FIT1045/
    3.json     # [{"slot": "Workshop 01", "code": "LCPPH"}, ...]
  FIT1047/
    7.json

If you maintain your codes in a separate Git repository, point the tool at it:

export CODES_DB_REPO="git@github.com:you/attendance-db.git"
export CODES_DB_BRANCH="main"

On every run the repository is cloned (if missing) or updated before submission. Without a repository the tool simply reads whatever JSON files already exist under data/.

The tool now automatically tracks your attendance submission statistics:

# View detailed statistics
python main.py --stats

# Or use the stats module directly
python stats.py

Statistics include:

• Total runs and success rate
• Codes submitted per course
• Recent activity timeline
• Error history

Always Attend ships with a polished terminal UI powered by Rich:

• Animated Monash-blue typewriter banner with optional spark highlights (auto-disables on non-TTY output).
• Live, single-line progress bars with square block fills and cached ASCII spinners when CLI_PROGRESS_RICH=1.
• Animated logging for major workflow steps without leaking ANSI fragments when launched via .command/.bat.

# Full experience: animated banner, live block progress
CLI_STYLE=fancy CLI_PROGRESS_RICH=1 python main.py --dry-run

# Quiet fallback suitable for basic terminals
CLI_STYLE=minimal CLI_PROGRESS_RICH=0 python main.py

Set these in your .env to persist the chosen style across runs.

• If login keeps asking for MFA: re-run the headed login to refresh storage_state.json
• If the browser fails to launch: make sure Google Chrome or Microsoft Edge is installed, or set BROWSER_CHANNEL to chrome/msedge.
• On Windows, if activation fails, run PowerShell as Administrator once, then try .venv\Scripts\Activate.ps1 again.
• When running, please do NOT use a VPN, as this may cause Okta to refuse the connection.

• Use py instead of python: If python isn't found or points to another version, use py (e.g., py -m venv .venv, py main.py).
• Switching between Git Bash and PowerShell: In terminals like VS Code, use the dropdown to open a new Git Bash or PowerShell window. Some commands (e.g., source) only work in Git Bash, while PowerShell uses .\ for scripts.
• Path escaping issues: PowerShell uses backslashes (\) and may treat them as escape characters. Wrap paths in quotes or use double backslashes like C:\path\to\file. Git Bash uses forward slashes (/).

main.py

• This project is for educational and personal use only. Use it responsibly and follow your institution’s policies and the website’s terms of use.
• This project is not affiliated with, endorsed by, or sponsored by any university or service provider. All product names, logos, and brands are property of their respective owners.
• You are solely responsible for any use of this tool and any consequences that may arise. The authors provide no guarantee that it will work for your specific setup.

• This project is licensed under the GNU General Public License v3.0 (GPL‑3.0). See the full text in the LICENSE file.
• You may copy, modify, and distribute this software under the terms of the GPL‑3.0. It is provided “as is”, without any warranty.