Metadata-Version: 2.4
Name: python-learnings
Version: 0.2.0
Summary: Python learnings, Rustlings-style, in a terminal TUI.
Project-URL: Homepage, https://github.com/abhiksark/pylings
Project-URL: Repository, https://github.com/abhiksark/pylings
Project-URL: Issues, https://github.com/abhiksark/pylings/issues
Project-URL: Changelog, https://github.com/abhiksark/pylings/blob/main/CHANGELOG.md
Project-URL: Documentation, https://pylings.abhik.ai/
License: MIT
License-File: LICENSE
Keywords: beginner-python,cli,coding-practice,education,learn-python,python,python-exercises,python-learnings,rustlings,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Education :: Computer Aided Instruction (CAI)
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Requires-Dist: textual[syntax]>=8.0.0
Requires-Dist: tomli>=1.1.0; python_version < '3.11'
Requires-Dist: watchdog>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# Pylings

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://semver.org/)
[![SemVer](https://img.shields.io/badge/semver-2.0.0-brightgreen)](https://semver.org/)
[![Tests](https://img.shields.io/badge/tests-125%20passing-brightgreen)](#development)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)

Documentation: [pylings.abhik.ai](https://pylings.abhik.ai/)

Python learnings, Rustlings-style, in a live terminal TUI.

Pylings helps you learn Python by fixing small broken programs and watching
checks rerun as you type. It is built for beginner Python practice, coding
practice, and self-paced Python tutorial workflows: 292 exercises, hidden
pytest-style checks, a live Textual editor, progressive hints, and bundled
Python documentation snippets so learners can work without leaving the terminal.

Status: `v0.1.0` alpha. GitHub installs are available now; the PyPI package
name is `python-learnings` and will become the primary install path after
publishing is enabled.

![Coding screen](docs/assets/screenshots/coding-screen.png)

## Highlights

- 292 Python exercises across 31 topics, from variables through async.
- Rustlings-inspired learn-by-doing flow for Python coding practice.
- Live in-terminal editor with automatic checks after edits.
- Topic picker with progress, resume state, reset, hints, and one-shot CLI runs.
- `F5` opens a local Python reference window; `O` opens the official docs page.
- Bundled docs are generated from the official Python documentation for offline use.

## Who It Is For

- Python beginners who want short, focused practice instead of passive reading.
- Rustlings users who want the same fix-and-verify loop for Python.
- Learners who prefer working in a terminal with local docs close to the code.
- Contributors interested in building curriculum, checks, and terminal UX.

## What Happens When You Run It

1. `pylings init` creates a self-contained learner workspace with exercises,
   hidden checks, local docs, and original snapshots for reset.
2. `pylings` opens the first pending exercise in the terminal UI.
3. You edit the broken code, remove `# I AM NOT DONE`, and checks rerun as you
   work.
4. Passing checks mark the exercise complete and move progress forward. `F4`
   opens the topic picker, `F5` opens local docs, and `Esc` quits main screens.

## Install

Install the current release directly from GitHub:

```bash
pipx install "git+https://github.com/abhiksark/pylings.git@v0.1.0"
```

After PyPI publishing is enabled, the package install will be:

```bash
pipx install python-learnings
```

The `pylings` command is installed by the `python-learnings` package. The PyPI
project name `pylings` is already used by another package, so do not use
`pip install pylings` for this project.

For the latest development build from `main`:

```bash
pipx install --force git+https://github.com/abhiksark/pylings.git
```

Create a learner workspace before starting:

```bash
pylings init --path ~/pylings-workspace
cd ~/pylings-workspace
pylings
```

For local development:

```bash
git clone git@github.com:abhiksark/pylings.git
cd pylings
pip install -e ".[dev]"
```

## Quick Start

```bash
pylings init --path ./learn-python     # create a self-contained workspace
cd learn-python
pylings                              # open the TUI on the first pending exercise
pylings topics                       # open the topic picker
pylings list                         # show topic progress
pylings hint variables1              # print a hint and docs link
pylings run variables1               # run one exercise check
pylings dry-run variables1           # run one exercise non-interactively
pylings reset variables1 --yes       # restore an exercise from its original
pylings update                       # refresh checks/docs after upgrading pylings
```

Each exercise contains a `# I AM NOT DONE` marker. Fix the code, remove the
marker, and let the live check advance you to the next exercise.

## Demo

![Pylings terminal demo](docs/assets/demos/pylings-demo.gif)

The demo is generated from [docs/demo.tape](docs/demo.tape). See
[docs/DEMO_GIF.md](docs/DEMO_GIF.md) to regenerate it with
[VHS](https://github.com/charmbracelet/vhs). It covers the first-run flow,
progress listing, hints, the coding screen, local docs, topic picker, and quit
path.

## Interface

![Topic picker](docs/assets/screenshots/topic-picker.png)

| Key | Action |
|---|---|
| `F1` | Toggle hint |
| `F2` | Reset the current exercise |
| `F3` | Toggle the exercise list |
| `F4` | Return to the topic picker |
| `F5` | Show the local Python reference |
| `O` | Open official docs from the reference window |
| `Esc` | Close docs, or quit from main screens |
| `Ctrl+Q` | Quit |

![Local docs reference](docs/assets/screenshots/docs-reference.png)

## Project Layout

```text
pylings/                 # application package
  core/                  # manifest, state, runner, reset, docs loading
  screens/               # Textual screens
  widgets/               # reusable TUI widgets
  docs/                  # bundled Python documentation snippets
pylings/curriculum/      # packaged copy in built wheels
exercises/<topic>/       # learner-editable exercise files
checks/<topic>/          # hidden assertions for each exercise
tests/                   # unit, integration, and TUI tests
scripts/fetch_python_docs.py
info.toml                # curriculum order, hints, and docs URLs
```

Regenerate the local reference snippets with:

```bash
python scripts/fetch_python_docs.py
```

## Development

```bash
pip install -e ".[dev]"
python -m pytest -q
pylings --root tests/fixtures/passing_curriculum verify
```

When adding curriculum, update `exercises/`, `checks/`, and `info.toml`
together. Keep exercise and check filenames mirrored, for example
`exercises/lists/lists3.py` and `checks/lists/lists3.py`.

## Release Flow

Pylings uses Semantic Versioning:

- `MAJOR`: incompatible curriculum or CLI changes.
- `MINOR`: new topics, exercises, TUI features, or docs workflows.
- `PATCH`: fixes, copy edits, and compatible test or packaging updates.

Branch flow is feature-first:

```text
feature/<name> -> dev -> main -> vMAJOR.MINOR.PATCH
```

Feature branches are merged into `dev`. A verified `dev` branch is then merged
into `main` and tagged with an annotated release tag such as `v0.1.0`.
See [RELEASE.md](RELEASE.md) for the release checklist.

## Attribution

Pylings is inspired by [rustlings](https://github.com/rust-lang/rustlings).
Bundled reference snippets are generated from the official Python documentation.
See [pylings/docs/NOTICE.md](pylings/docs/NOTICE.md) for Python documentation
licensing details.

## License

MIT. See [LICENSE](LICENSE).
