Metadata-Version: 2.4
Name: cursa-cli
Version: 1.4.0
Summary: ⚡ A modern, beautiful terminal framework to track university study plans, prerequisites, grades, and academic progress.
Author-email: Agustin <agbon@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/agbon/cursa
Project-URL: Repository, https://github.com/agbon/cursa
Project-URL: Issues, https://github.com/agbon/cursa/issues
Keywords: cli,university,curriculum,grades,prerequisites,education,rich,typer,academic-progress
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1.0,>=0.9.0
Requires-Dist: sqlalchemy<3.0,>=2.0.0
Requires-Dist: rich<15.0,>=13.0.0
Requires-Dist: pyyaml<7.0,>=6.0
Dynamic: license-file

<h1 align="center">📚 Cursa CLI</h1>

<p align="center">
  <strong>A modern, beautiful, and developer-friendly terminal framework to track university degree plans, prerequisites, grades, and academic progress.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/cursa-cli/"><img src="https://img.shields.io/pypi/v/cursa-cli.svg" alt="PyPI Version"></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
  <a href="https://github.com/tiangolo/typer"><img src="https://img.shields.io/badge/CLI-Typer-brightgreen.svg" alt="Typer"></a>
  <a href="https://github.com/Textualize/rich"><img src="https://img.shields.io/badge/UI-Rich-magenta.svg" alt="Rich"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License MIT"></a>
</p>

---

## ✨ Features

- 🎓 **Degree Plan Management (`cursa init`)**: Load pre-built degree templates or supply your own custom YAML/JSON study plan or backup.
- 🔮 **Smart Course Eligibility (`cursa next`)**: Evaluates complex prerequisite trees to instantly show which courses you are eligible to enroll in or take final exams for.
- 📊 **Academic Dashboard (`cursa stats`)**: Progress bars breaking down Passed, Enrolled, In Progress, and Pending subjects, along with weighted GPAs (with & without failed attempts).
- 🌐 **Multilingual Support (`en` / `es`)**: Switch interface language seamlessly between English and Spanish.
- 🔍 **Accent-Insensitive Search (`cursa search`)**: Query courses by code or partial name, disregarding case and diacritics (`calculo`, `algebra`, etc.).
- 📝 **Full Exam History (`cursa exam`)**: Record multiple exam attempts per subject. Grades $\ge 4$ (configurable) automatically update the subject status to `aprobada`.
- 📁 **Declarative Backup & Export (`cursa export`)**: Export your degree state and full exam history to unified `.yaml` or `.json` files.
- ☁️ **Cloud Synchronization**: Set `CURSA_DB_PATH` to seamlessly sync your SQLite database across devices via Google Drive, OneDrive, or Dropbox.
- ⚙️ **Diagnostics & Configuration (`cursa config`)**: View system diagnostics, update alerts, and adjust passing thresholds, language, or active plans.

---

## 🚀 Installation

### Option 1: Install via `pipx` (Recommended)

[`pipx`](https://pipx.pypa.io/) installs CLI tools in isolated environments and **automatically configures your PATH**:

```bash
# Install pipx if you don't have it yet
pip install pipx
pipx ensurepath      # Only needed the first time (restart your terminal after this)

# Install Cursa
pipx install cursa-cli
```

### Option 2: Install via `pip`
```bash
pip install cursa-cli
```

> **Note (Windows):** If `cursa` is not recognized after installing with `pip`, your Python `Scripts` folder may not be on PATH. Use `pipx` (Option 1) or run `python -m cursa.cli` as a workaround.

### Option 3: Install from source (for development)
```bash
git clone https://github.com/agbon/cursa.git
cd cursa
pip install -e .
```

Verify installation:
```bash
cursa config
```

---

## 🔄 Updating Cursa

To upgrade Cursa to the latest version:

```bash
# If installed via pipx (Recommended)
pipx upgrade cursa-cli

# If installed via pip
pip install --upgrade --no-cache-dir cursa-cli
```

---

## 💡 Quick Start

```bash
# 1. Initialize your degree from a template or file
cursa init --plan ucse_ingenieria_informatica

# 2. Bulk update passed subjects (e.g. 1st year subjects from code 1 to 9)
cursa update 1..9 --estado aprobada

# 3. Register exam results
cursa exam "Algoritmos" 7
cursa exam "Álgebra Lineal" 2 --fecha 2025-03-15
cursa exam "Álgebra Lineal" 5 --fecha 2025-07-20

# 4. Check eligible subjects for the upcoming semester
cursa next

# 5. View detailed subject info & full recursive prerequisite tree
cursa state 41 --tree

# 6. View overall progress & GPAs
cursa stats

# 7. Check system configuration & status
cursa config
```

---

## 🌐 Language & Internationalization (`en` / `es`)

Cursa CLI natively supports both **English** and **Spanish**!

Switch language dynamically:

```bash
# Switch to English
cursa config set language en

# Switch to Spanish
cursa config set language es
```

---

## 📖 Command Reference

| Command | Description | Example |
|---|---|---|
| `cursa init` | Initialize or restore database from a template or local file | `cursa init --plan ucse_ingenieria_informatica` |
| `cursa list` | Display all degree subjects (highlights ⭐ key subjects unlocking 3+ courses) | `cursa list --anio 2` |
| `cursa next` | Show subjects eligible to enroll or take final exams for (prioritizes ⭐ key subjects) | `cursa next` |
| `cursa search <text>` | Search subjects by name (accent-insensitive) | `cursa search "algebra"` |
| `cursa state <code\|name>` | Detailed subject view (`--tree` / `-t` for recursive tree, shows unlock count) | `cursa state 41 --tree` |
| `cursa stats` | Academic dashboard with GPAs and progress breakdown | `cursa stats` |
| `cursa exam <code\|name> [grade]` | Record an exam attempt (`--delete` / `-d` to remove attempt) | `cursa exam 20 8` |
| `cursa update <code\|name\|range>` | Update subject status (`--estado`, supports `1..9`) | `cursa update 1..9 --estado aprobada` |
| `cursa export` | Export progress & exams to YAML or JSON | `cursa export --out my_progress.yaml` |
| `cursa config [get\|set]` | View system status & settings, or modify preferences | `cursa config` or `cursa config set language en` |
| `cursa uninstall` | Remove all Cursa data from the system | `cursa uninstall` |

---

## 🛠️ Defining a Custom Study Plan (`my_degree.yaml`)

Developers and students can create or share study plans using simple, readable YAML in **English** or **Spanish**:

```yaml
# Spanish format (with strong & weak prerequisites):
- codigo: 22
  nombre: Información y Comunicación
  anio: 3
  estado: aprobada

- codigo: 38
  nombre: Seguridad Informática
  anio: 4
  tipo: obligatoria
  duracion: cuatrimestral
  estado: pendiente
  correlativas_fuertes: [22]   # Requires final exam passed to enroll & take exam
  correlativas_debiles: [25]   # Requires coursework regularized to enroll, final exam to pass

---
# English format (bilingual support):
- code: 101
  name: Introduction to Computer Science
  year: 1
  status: passed

- code: 102
  name: Operating Systems
  year: 2
  type: mandatory
  duration: semester
  status: pending
  prerequisites_strong: [101]
```

Initialize your custom plan:
```bash
cursa init --plan path/to/my_degree.yaml
```

---

## ☁️ Cloud & Multi-Device Synchronization

To automatically synchronize your database across your desktop and laptop:

1. Move your database file (`~/.cursa/cursa.db`) to your synced cloud directory (e.g. OneDrive or Google Drive).
2. Set the `CURSA_DB_PATH` environment variable:

**PowerShell (Windows):**
```powershell
[Environment]::SetEnvironmentVariable("CURSA_DB_PATH", "G:\My Drive\Facultad\cursa\cursa.db", "User")
```

**Bash / Zsh (Linux / macOS):**
```bash
export CURSA_DB_PATH="$HOME/Google Drive/cursa/cursa.db"
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
