Metadata-Version: 2.4
Name: myfap
Version: 0.1.8
Summary: CLI Tool dựa trên MyFAP API dành cho Sinh Viên FPTU
Author-email: WindowScary321 <126940686+WindowScary321@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/WindowScary321/myfap-api-cli
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pkce>=1.0.3
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: ics>=0.7.2
Requires-Dist: pytz>=2023.3
Dynamic: license-file

# MyFAP API CLI

## Giới thiệu

Đây là cli tương tác giống hoàn toàn với APP MYFAP trên điện thoại. Bạn có thể xem lịch học, lịch thi, điểm số (sự thất vọng của gia đình), thông tin cá nhân, v.v. 1 cách thuận tiện, không bị gò bó trong giao diện app. <br>
- Lưu ý: repo này được thực hiện cùng với sự hỗ trợ của AI.

## Tính năng chính
- Hỗ trợ đa nền tảng.
- Login thông qua FEID hoặc Google OAuth.
- Xem lịch học (từng tuần hoặc cả Kỳ).
- Xem điểm (từng môn hoặc cả Kỳ).
- Check điểm danh (từng môn hoặc cả Kỳ).
- Check tình trạng đơn từ.
- Xem thông báo của trường.
- Check Info của sinh viên hoặc phòng dvsv.
- Convert lịch học Kỳ sang **ICS**, dễ dàng import lịch học vào Google Calendar hoặc các dịch vụ tương tự.
- Và nhiều hơn nữa ...

## Cách sử dụng

Bạn có thể cài ứng dụng bằng pip theo hướng dẫn bên dưới. Để phát triển từ mã nguồn, xem mục dùng uv.

- Cài đặt ứng dụng.

  ```
  pip install myfap
  ```

- Lấy danh sách cơ sở.

  ```
  myfap campuses
  ```

- Login vào feid (chỉ cần làm 1 lần, mặc định chọn cơ sở Hola).
  ```
  myfap login
  ```
  Sau khi hoàn thành login, phiên đăng nhập sẽ dc lưu ở ``~/.myfap-api-cli/session.json`` <br>
- Login cho cơ sở Xavalo.
  ```
  myfap login -c HCM
  ```

- Lấy Lịch học *(tự động lấy kỳ mới nhất)*.

  ```
  myfap schedule
  ```

## Phát triển với uv

Bạn cần cài [uv](https://docs.astral.sh/uv/getting-started/installation/) trước khi bắt đầu. Repo dùng Python 3.11 cho môi trường dev, được chọn trong `.python-version`; package vẫn hỗ trợ Python từ 3.9. Cả `.python-version` và `uv.lock` được commit để các máy dùng cùng cấu hình và phiên bản dependency.

Clone repo và cài môi trường theo lockfile:

```sh
git clone https://github.com/WindowScary321/myfap-api-cli.git
cd myfap-api-cli
uv sync --locked
```

`uv sync` tạo `.venv` và cài package ở chế độ editable, nên thay đổi mã nguồn có hiệu lực khi chạy CLI. Bạn dùng `uv run` để chạy trong môi trường này, không cần activate thủ công hay chạy `uv init` trong repo đã có cấu hình.

```sh
uv run myfap --help
uv run myfap version
uv run python -m unittest discover -s tests -v
uv build
```

### Trình duyệt cho đăng nhập

Đăng nhập mở cửa sổ trình duyệt và ưu tiên Chrome đã cài trên máy, sau đó thử Edge. Nếu có Chrome hoặc Edge chạy được, bạn không cần cài thêm trình duyệt. Để dùng Firefox làm phương án dự phòng, cài trình duyệt của Playwright bằng lệnh sau:

```sh
uv run playwright install firefox
```

Bước cài Firefox là tùy chọn; việc build package không cần trình duyệt.

### Cập nhật dependency

Bạn dùng `uv add <tên-package>` hoặc `uv remove <tên-package>` để cập nhật dependency trong `pyproject.toml` và `uv.lock`. Nếu sửa dependency trực tiếp trong `pyproject.toml`, chạy `uv lock` rồi `uv sync --locked`. Sau khi kiểm tra, commit cả thay đổi cấu hình và lockfile cùng nhau. Không commit thư mục `.venv`.

## Các Options
|Option|Chú thích|
|:-|:-|
|--help|Hiển thị bảng Commands và Options|
|--config <đường dẫn>|Đường dẫn tới file cấu hình session tùy chỉnh (mặc định: ~/.myfap-api-cli/session.json)|
|-c, --campus <cơ sở>|Mã cơ sở (VD: APHL, HCM, DN)  [default: APHL]|
|-s, --semester <kỳ học>|Tên kỳ học (VD: Summer2026)|
|-cid, --courseid <mã môn>|Chọn mã môn, chỉ có ở command ``marks``. (VD: 82934, lấy từ bảng điểm của kỳ, ko phải mã môn như PRO192, SWE201c, ...)|
|-w, --week <số tuần>|Chọn tuần, chỉ có ở command ``week-timetable``|
|-y, --year <số năm>|Chọn năm học, chỉ có ở command ``week-timetable``|
|-d, --date \<YYYY-MM-DD\>|Chỉ định ngày chính xác, chỉ có ở command ``week-timetable``|
|-sc, --subjectcode <mã môn>|Chọn môn học,  chỉ có ở command ``attendance``|
|-cn, --classname <mã lớp>|Chọn lớp học, chỉ có ở command ``attendance``|
|--ics|Convert Sang **ICS**, dễ dàng import lịch học vào Google Calendar hoặc các dịch vụ tương tự, chỉ có ở command ``schedule``)|
|-p, --pretty|Format lại bảng điểm gốc của trường sang dạng json, chỉ có ở command ``marks``)|
|--output, -o <thư mục>|Thư mục xuất file thay vì thư mục hiện tại|
|--stdout|In kết quả trực tiếp ra màn hình thay vì lưu file|
|-f, --force|Buộc đăng nhập lại, bỏ qua file ``session.json``, chỉ có ở command ``login``|

## [Các ví dụ sử dụng](./docs/Example.md)
