feat!: deprecate "Know Your Class and Section" and mark v4.0.0 release

[ndigvijay]

📌 Description

This PR removes the deprecated knowYourClassAndSection feature because the corresponding PESU Academy endpoint, /Academy/a/getStudentClassInfo, no longer works.

The removal includes:

• Removing knowYourClassAndSection from the authentication request schema.
• Removing knowYourClassAndSection from the authentication response schema.
• Removing the upstream API request and response parsing logic.
• Removing the KYCAS response model and dedicated exception.
• Removing KYCAS-only profile fields.
• Removing related README and OpenAPI documentation.
• Removing benchmark CLI and payload support.
• Removing obsolete unit, functional, and integration tests.

Requests containing knowYourClassAndSection are now treated like any other unknown request field and return a 400 validation response.

ℹ️ Fixes / Related Issues
Fixes: 153
Related: N/A

🧱 Type of Change

• 🐛 Bug fix – Non-breaking fix for a functional/logic error
• ✨ New feature – Adds functionality without breaking existing APIs
• ⚠️ Breaking change – Introduces backward-incompatible changes (API, schema, etc.)
• 📝 Documentation update – README, docstrings, OpenAPI tags, etc.
• 🧪 Test suite change – Adds/updates unit, functional, or integration tests
• ⚙️ CI/CD pipeline update – Modifies GitHub Actions, pre-commit, or Docker build
• 🧹 Code quality / Refactor – Improves structure, readability, or style (no functional changes)
• 🐢 Performance improvement – Speeds up auth, scraping, or reduces I/O
• 🕵️ Debug/logging enhancement – Adds or improves logging/debug support
• 🔧 Developer tooling – Scripts, benchmarks, local testing improvements
• 🔒 Security fix – Addresses auth/session/data validation vulnerabilities
• 🧰 Dependency update – Updates libraries in requirements.txt, pyproject.toml

🧪 How Has This Been Tested?

• Unit Tests (tests/unit/)
• Functional Tests (tests/functional/)
• Integration Tests (tests/integration/)
• Manual Testing

⚙️ Test Configuration:

• OS: macOS
• Python: 3.14.6 via uv
• Docker build tested (during maintainer review, on Linux / python3.14-alpine)

Testing performed:

• uv run pytest -m 'not secret_required'
  • 68 tests passed (61 before the regression tests were restored, see the update below).
  • 11 secret-dependent tests were deselected because the required TEST_* credentials were unavailable.
• Full suite with TEST_* credentials populated (maintainer review):
  • 79 tests passed, 99.38% coverage, clearing the 95% gate.
• uv run ruff check . and ruff format --check
  • All checks passed.
• Generated OpenAPI schemas were inspected to confirm knowYourClassAndSection is absent from both request and response models.
• Repository searches confirmed there are no remaining references to the removed feature.

✅ Checklist

• My code follows the CONTRIBUTING.md guidelines
• I've performed a self-review of my changes
• I've added/updated necessary comments and docstrings
• I've updated relevant docs (README or endpoint docs)
• No new warnings introduced
• I've updated tests for the removed behavior
• All tests pass locally (scripts/run_tests.py)
• I've run linting and formatting (pre-commit run --all-files)
• Docker image builds and runs correctly
• Changes are backwards compatible (if applicable) – intentionally not, see Migration below
• Feature flags or .env vars updated (if applicable)
• I've tested across multiple environments (if applicable)
• Benchmarks still meet expected performance (scripts/benchmark/benchmark_requests.py)

🛠️ Affected API Behaviour

• app/app.py – Modified /authenticate route logic
• app/pesu.py – Updated scraping or authentication handling

🧩 Models

• app/models/request.py – Input validation or request schema changes
• app/models/response.py – Authentication response formatting
• app/models/profile.py – Profile extraction logic

🐳 DevOps & Config

• Dockerfile – Changes to base image or build process
• .github/workflows/*.yaml – CI/CD pipeline or deployment updates
• pyproject.toml / requirements.txt – Project version bumped to 4.0.0 and uv.lock re-locked (no dependency changes)
• .pre-commit-config.yaml – Linting or formatting hook changes
• .env.example – Dropped the dead TEST_BRANCH_SHORT_CODE variable

📊 Benchmarks & Analysis

• scripts/benchmark/benchmark_requests.py – Removed support for the deprecated request flag
• scripts/benchmark/analyze_benchmark.py – Benchmark result analysis changes
• scripts/run_tests.py – Custom test runner logic or behavior updates

📸 Screenshots / API Demos

Example response when a client continues to send the removed field:

{
  "status": false,
  "message": "Could not validate request data - body.knowYourClassAndSection: Extra inputs are not permitted"
}

The generated OpenAPI request and response schemas no longer include knowYourClassAndSection.

🔄 Update — maintainer commits

Pushed to this branch during review (see the review comment for the reasoning and test evidence):

Commit	What
0246480	Restores the three deprecation tests this PR had deleted — they still pass verbatim and were the only coverage pinning that the KYCAS keys are rejected. Adds the previously untested contracts: the camelCase knowYourClassAndSection key, and cycle / department / instituteName as fields values.
b31d835	Bumps the version to 4.0.0 (+ uv.lock). 3.0.0 is already released and serving in production, so a breaking change cannot ride inside it.
350e66b	Drops the dead TEST_BRANCH_SHORT_CODE from .env.example, unread since 22e3d4b.

The upstream 403 was independently reproduced on a second account (different campus and cohort from the issue report): POST /Academy/a/getStudentClassInfo returns 403 Access denied for student role even with a valid authenticated session and CSRF token, so this is a permanent loss of the endpoint for the student role rather than anything fixable client-side.

🧠 Additional Notes — Migration to v4.0.0

This is a breaking API change, shipping as v4.0.0.

• Remove knowYourClassAndSection from authentication requests entirely. Sending the key at all is now a 400 — including "knowYourClassAndSection": false. Clients that explicitly opted out must delete the key rather than set it to false.
• Stop expecting knowYourClassAndSection in authentication responses. The key is gone from the response schema.
• cycle, department and instituteName are no longer valid fields values and now return 400.
• Direct Python callers must stop passing the know_your_class_and_section argument to PESUAcademy.authenticate().

The normal profile response continues to provide supported fields such as semester and section.

[Copilot]

Pull request overview

This PR removes the deprecated Know Your Class and Section (KYCAS) feature end-to-end from the PESUAuth API because the upstream PESU Academy endpoint no longer works, and updates tests/docs/tooling accordingly.

Changes:

• Removes the knowYourClassAndSection request flag and the corresponding response payload/model/exception.
• Deletes all KYCAS scraping/parsing logic from PESUAcademy.authenticate() and associated tests.
• Updates docs and benchmark tooling to drop KYCAS references and CLI support.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/test_request_model.py	Removes request-model tests that covered the now-removed KYCAS request flag; retains extra-field rejection coverage.
tests/unit/test_pesu.py	Drops unit tests and imports related to KYCAS fetch/parsing behavior; minor formatting tweaks.
tests/integration/test_app_integration.py	Removes integration coverage for KYCAS request/response behavior and validation.
tests/functional/test_authenticate_functional.py	Removes functional tests that exercised KYCAS behavior.
scripts/benchmark/util.py	Removes KYCAS payload flag from benchmark request construction.
scripts/benchmark/benchmark_requests.py	Removes KYCAS CLI flag and propagation into benchmark requests.
README.md	Removes KYCAS from API request/response documentation and examples.
app/pesu.py	Removes KYCAS constants and the KYCAS fetch path from authenticate().
app/models/response.py	Removes the KYCAS field from the response schema.
app/models/request.py	Removes the KYCAS field from the request schema so it becomes a forbidden extra input.
app/models/kycas.py	Deletes the KYCAS response model.
app/models/init.py	Removes KYCAS model export from the models package.
app/exceptions/authentication.py	Removes the dedicated KYCAS fetch exception type.
app/docs/authenticate.py	Removes OpenAPI examples and error examples related to KYCAS.
app/app.py	Stops passing the removed KYCAS flag through the /authenticate route into PESUAcademy.authenticate().

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[achyu-dev]

LGTM

[aditeyabaral]

Review: tested end-to-end — I've pushed the two fixes, good to merge once CI is green

Reviewed at feba9a1 and re-verified at b31d835, tested against the live PESU Academy backend with a valid student account, both locally (Python 3.13) and via the Docker image built from this branch (Python 3.14.7).

Rather than leave these as review comments, I pushed both changes straight to the branch — hope that's alright:

• 0246480 — restores the three deprecation tests this PR deleted, and adds the contracts that were untested
• b31d835 — bumps the version to 4.0.0 (+ uv.lock)

Detail on each below.

The premise in #153 checks out

With a valid authenticated session + authenticated CSRF token, POST /Academy/a/getStudentClassInfo returns:

403 Forbidden
<html><head><title>Error</title></head><body>Access denied for student role</body></html>

I reproduced this on a different account from the one in the issue (RR campus, different cohort), so it's neither account-specific nor transient — PESU has revoked the student role's access to that controller. Nothing we can do client-side, so removing the feature is the right call rather than trying to repair the request.

Expected behaviour from #153 — matches exactly

Against the container built from this branch:

Request	Result
{…, "profile": true, "knowYourClassAndSection": true}	400 · body.knowYourClassAndSection: Extra inputs are not permitted — message-identical to the issue's "Expected Behavior" ✅
{…, "knowYourClassAndSection": false}	400, same message
{…, "know_your_class_and_section": true}	400
{…, "fields": ["cycle", "department", "instituteName"]}	400, enum now offers only the 11 profile fields
{…, "profile": true}	200, full profile, no knowYourClassAndSection key
{…} (auth only)	200
{…, "fields": ["name", "campus", "semester"]}	200, correctly filtered
wrong password	401
/health · /readme · /	200 · 308 → repo · 200

GET /openapi.json exposes exactly ProfileModel, RequestModel, ResponseModel, with zero occurrences of kycas / knowYourClass / instituteName / cycle. A repo-wide grep for every KYCAS identifier is clean too — the removal across models, app/pesu.py, the exception class, OpenAPI examples, README tables + samples, and the benchmark CLI/payload is complete and surgical.

Docker build also verified end-to-end (the description has that box unchecked): image builds on python3.14-alpine, container comes up in ~4s, all of the above runs against it.

Test suite

With TEST_* secrets populated: 79 passed, 99.38% coverage (app/pesu.py at 100%), comfortably clearing the 95% gate. ruff check and ruff format --check both clean. Without secrets: 68 passed, 11 deselected.

(Minor note on the description's numbers — before my commits, pytest -m 'not secret_required' on this branch gave 61 passed / 11 deselected, not 63.)

---

1. 0246480 — restored three deleted tests, they were the regression tests for this exact contract

d418959 deleted these three, but each one still passes verbatim against this branch — I checked before restoring them:

• tests/integration/test_app_integration.py::test_integration_authenticate_deprecated_know_your_class_and_section_key_rejected
• tests/integration/test_app_integration.py::test_integration_authenticate_deprecated_institute_name_in_fields_rejected
• tests/unit/test_request_model.py::test_validate_deprecated_know_your_class_and_section_key_rejected

They were added in #151 specifically to pin deprecated keys as rejected — precisely the guarantee #153 asks this PR to deliver. With them gone, the only remaining coverage was the generic someUnknownField / someRandomField extra-key tests, and those would keep passing if knowYourClassAndSection were ever reintroduced into RequestModel. The behaviour this PR exists to produce would have been pinned by no test at all.

While there I also added the contracts this PR newly introduces, which nothing covered:

• knowYourClassAndSection (camelCase) rejected with 400 — the literal payload from the issue, and the one case we most want to stay pinned
• the removed KYCAS-only field names (cycle, department, instituteName) rejected as fields values

Seven tests in total, all passing.

2. b31d835 — version bumped to 4.0.0

This is a breaking API change, and 3.0.0 is already out: main and dev are identical, and the live deployment's /openapi.json reports 3.0.0. So this can't ride along inside 3.0.0 — following the precedent of 4e14e18, which shipped the camelCase break as 3.0.0, this goes out as 4.0.0.

Worth doing here specifically because OpenAPI's info.version comes from the package metadata, so without the bump / and /openapi.json would advertise the KYCAS removal as part of 3.0.0. uv.lock is updated in the same commit (uv lock touches only that one version line). Verified: a container built from b31d835 now reports 4.0.0.

Worth spelling out in the release notes

"knowYourClassAndSection": false is now a hard 400 too. That follows directly from the expected behaviour in the issue, but it means a client that explicitly opts out of KYCAS — which both the pre-PR README example and scripts/benchmark/util.py did — breaks on upgrade despite never wanting the data. Entirely acceptable in a major version; just the most likely surprise for downstream users, so let's be explicit about it in the 4.0.0 notes.

Nit — also handled

.env.example carried TEST_BRANCH_SHORT_CODE, which nothing has read since the branch_short_code deprecation in 22e3d4b. I'd originally left this out to keep the PR focused, but it's a one-line deletion of dead config, so it went in as 350e66b after all.

---

Otherwise this is a clean, thorough removal — nice work. Once CI goes green on the two new commits this is good to merge.

[aditeyabaral]

Update — everything from the review above is now addressed

All three points I raised are closed, and I've refreshed the title and description. Head is now 350e66b.

Review item	Status
Restore the three deleted deprecation tests	✅ 0246480 — all three back, verbatim
Add the missing camelCase knowYourClassAndSection test	✅ 0246480 — added at both unit and integration level, plus cycle / department / instituteName as fields values
Bump the version for a breaking change	✅ b31d835 — 4.0.0 in pyproject.toml and uv.lock; a container built from it reports 4.0.0
Spell out the "knowYourClassAndSection": false break	✅ now a Migration to v4.0.0 section in the description
Nit: dead TEST_BRANCH_SHORT_CODE in .env.example	✅ 350e66b — swept up after all (I'd said I'd leave it; it's a one-line deletion of a variable nothing has read since 22e3d4b, so it may as well go with the rest of the dead config)

Verification on the final head

• Full suite with TEST_* populated: 79 passed, 99.38% coverage (app/pesu.py at 100%), 95% gate cleared. Without secrets: 68 passed, 11 deselected.
• ruff check + ruff format --check clean.
• Docker image rebuilt from this branch: reports 4.0.0, the Deprecate KYCAS #153 repro still returns 400 body.knowYourClassAndSection: Extra inputs are not permitted, happy path still 200.
• All 8 CI checks green on 350e66b — Docker build, lint on 3.12/3.13/3.14, pre-commit on 3.12/3.13/3.14, PR origin.

Title and description

• Title is now feat!: deprecate "Know Your Class and Section" and mark v4.0.0 release — adds the conventional-commit prefix and the ! breaking marker, and mirrors 4e14e18 (feat!: … and mark v3.0.0 release), since these titles become the squash-merge commit message.
• Description: fixed an unclosed ```json fence that was swallowing the Additional Notes section, refreshed the test counts and checkboxes to match the branch, recorded the three review commits, and added the v4.0.0 migration notes.

Nothing outstanding from my side — good to merge.

[aditeyabaral]

Approving at 350e66b. Full detail in the review and update comments; summarising what I checked:

The removal is justified and complete. POST /Academy/a/getStudentClassInfo returns 403 Access denied for student role with a valid authenticated session and CSRF token, reproduced on a second account from a different campus and cohort than the issue report — a permanent loss of the endpoint for the student role, not something fixable client-side. Every KYCAS identifier is gone from the models, app/pesu.py, the exception class, OpenAPI examples, README and the benchmark scripts, and /openapi.json exposes only ProfileModel, RequestModel, ResponseModel.

Behaviour matches #153 exactly. The reported payload returns 400 body.knowYourClassAndSection: Extra inputs are not permitted, message-identical to the issue's expected output, with the snake_case key, the removed fields values, the happy paths, field filtering, wrong-password 401 and the other three routes all verified against a container built from this branch.

Test deletions reviewed individually. The remaining removals are all genuinely dead: the functional test_authenticate_without_kycas asserted the behaviour of a parameter that no longer exists, and the DEFAULT_FIELDS invariant dropped by test_default_fields_includes_kycas_relevant_fields is still covered at tests/unit/test_pesu.py:479. The three that were not dead are restored in 0246480, along with the previously untested camelCase and fields contracts.

Final state: 79 tests passing at 99.38% coverage with app/pesu.py at 100%, ruff clean, Docker image builds and reports 4.0.0, and all 8 CI checks green.

Thanks for the thorough removal work here — the sweep across docs, benchmarks and OpenAPI examples was genuinely complete, which made this an easy one to verify.