pythonlings 0.3.0__tar.gz

pythonlings-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,18 @@
+---
+name: Bug report
+about: Report a reproducible problem
+labels: bug
+---
+
+## What Happened?
+
+## Steps To Reproduce
+
+## Expected Behavior
+
+## Environment
+
+- OS:
+- Python:
+- Terminal:
+- Pythonlings version:

pythonlings-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature request
+about: Suggest an improvement
+labels: enhancement
+---
+
+## Problem
+
+## Proposed Behavior
+
+## Alternatives Considered

pythonlings-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+## Tests
+
+## Screenshots
+
+## Checklist
+
+- [ ] Updated docs when behavior changed
+- [ ] Added or updated tests
+- [ ] Verified `python -m pytest -q`

pythonlings-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+      - run: pythonlings --root tests/fixtures/passing_curriculum verify
+      - run: python -m pip install build
+      - run: python -m build
+      - run: python -m pip install --force-reinstall dist/*.whl
+      - run: pythonlings init --path /tmp/pythonlings-workspace
+      - run: pythonlings --root /tmp/pythonlings-workspace list

pythonlings-0.3.0/.github/workflows/pages.yml

@@ -0,0 +1,42 @@
+name: pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+      - uses: actions/configure-pages@v5
+      - run: python -m pip install -r requirements-docs.txt
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

pythonlings-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Check release tag matches project version
+        run: |
+          version=$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+          print(data["project"]["version"])
+          PY
+          )
+          test "${GITHUB_REF_NAME}" = "v${version}"
+      - run: python -m pip install build
+      - run: python -m build
+      - run: python -m pip install --force-reinstall dist/*.whl
+      - run: pythonlings --version
+      - run: pythonlings init --path /tmp/pythonlings-workspace
+      - run: pythonlings --root /tmp/pythonlings-workspace list
+      - run: pythonlings --root /tmp/pythonlings-workspace solution variables1
+      - run: pythonlings --root /tmp/pythonlings-workspace reset variables1 --yes
+      - run: pythonlings --root tests/fixtures/passing_curriculum verify
+      - uses: pypa/gh-action-pypi-publish@release/v1

pythonlings-0.3.0/.gitignore

@@ -0,0 +1,140 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Pythonlings runtime state (root install and any nested fixture roots)
+.pythonlings/
+.superpowers/
+.worktrees
+
+# Local artifacts from older pythonlings workspaces; not part of this package.
+/pythonlings/.gitignore
+/pythonlings/.git/
+/pythonlings/.pythonlings.toml
+/pythonlings/exercises/

pythonlings-0.3.0/AGENTS.md

@@ -0,0 +1,29 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`pythonlings/` contains the installable application package. Core exercise loading, workspace setup, state, reset, solutions, and runner logic live in `pythonlings/core/`; CLI entry points are in `pythonlings/cli.py` and `pythonlings/__main__.py`; Textual screens/widgets live in `pythonlings/screens/` and `pythonlings/widgets/`; `pythonlings/pythonlings.tcss` holds TUI styles.
+
+Curriculum files are split between `exercises/<topic>/<exercise>.py` for learner code, `checks/<topic>/<exercise>.py` for hidden assertions, and `solutions/<exercise>.py` for reference answers. Keep these trees aligned with `info.toml`, which defines order, hints, and docs URLs. Tests live in `tests/unit/`, `tests/integration/`, and `tests/tui/`, with fixtures in `tests/fixtures/`.
+
+## Build, Test, and Development Commands
+
+- `pip install -e ".[dev]"`: install pythonlings locally with pytest dependencies.
+- `pythonlings init --path ./learn-python`: create a self-contained learner workspace.
+- `pythonlings`, `pythonlings topics`, `pythonlings list`: launch the TUI or inspect progress.
+- `pythonlings run variables1`, `pythonlings dry-run variables1`, `pythonlings solution variables1`: test exercise and solution flows.
+- `pythonlings --root tests/fixtures/passing_curriculum verify`: smoke-test a known passing fixture.
+- `python -m pytest -q`: run the full suite configured in `pyproject.toml`.
+- `python -m build`: build source and wheel distributions.
+
+## Coding Style & Naming Conventions
+
+Use Python 3.11+ idioms and 4-space indentation. Prefer small, typed functions where practical. Keep UI behavior in `screens` or `widgets`; keep filesystem, manifest, reset, and runner behavior in `core`. Name tests `test_<behavior>.py` and test functions `test_<expected_behavior>`. Curriculum names use topic plus ordinal, such as `variables1.py` or `collections10.py`.
+
+## Testing Guidelines
+
+Use pytest for all tests; async tests are supported by `pytest-asyncio` in auto mode. Add unit tests for core behavior, integration tests for CLI/workspace flows, and TUI tests for Textual interactions. When changing curriculum, update `exercises/`, `checks/`, `solutions/`, and `info.toml`, then run relevant pytest files plus `pythonlings --root tests/fixtures/passing_curriculum verify`.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses conventional prefixes such as `feat:`, `fix:`, `docs:`, `chore:`, and merge commits between `feature/*`, `dev`, and `main`. Keep commits focused and imperative, for example `fix: reset exercise originals`. Pull requests should explain the user-facing change, list tests run, link issues when applicable, and include screenshots or terminal output for TUI/CLI changes.

pythonlings-0.3.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project are documented here. Pythonlings follows
+Semantic Versioning.
+
+## [0.3.0] - 2026-06-10
+
+### Added
+
+- The in-app reference (`F5`) now bundles a second complementary section from
+  the official Python documentation for every topic, roughly tripling each
+  topic's offline reference content.
+
+### Changed
+
+- The project is renamed from pylings to **pythonlings**. The PyPI package
+  (previously `python-learnings`), the CLI command (previously `pylings`),
+  and the Python package are all now `pythonlings`. Existing workspaces are
+  migrated automatically: a legacy `.pylings/` state directory is renamed to
+  `.pythonlings/` on the next run, preserving progress and reset snapshots.
+- The README and quick-start now describe the built-in editor accurately:
+  checks rerun as you type in the TUI editor.
+
+### Fixed
+
+- Running `pythonlings` outside a workspace now explains how to create one
+  with `pythonlings init` instead of a bare "info.toml not found".
+
+### Removed
+
+- The unused `watchdog` dependency, for a lighter install.
+
+## [0.2.0] - 2026-05-30
+
+### Added
+
+- Support for Python 3.9 and 3.10 (minimum was 3.11), broadening
+  compatibility with stock macOS and Debian/Ubuntu interpreters.
+
+### Changed
+
+- The `type_hints4`, `type_hints8`, and `itertools8` exercises carry a small
+  forward-compatibility shim (`from __future__ import annotations` and a
+  `tee`-based `pairwise` fallback) so their modern syntax and stdlib usage run
+  on Python 3.9 and 3.10. The learner's task is unchanged.
+
+### Fixed
+
+- Manifest loading now falls back to the `tomli` backport on Python < 3.11,
+  where `tomllib` is not available in the standard library. Previously the
+  package would install but crash on launch under older interpreters.
+
+## [0.1.0] - 2026-05-25
+
+### Added
+
+- Interactive Textual coding workflow with topic picker, resume state, hints,
+  reset, and automatic check reruns.
+- CLI commands for listing topics, running exercises, printing hints, resetting
+  files, and verifying curricula.
+- 292 Python exercises across 31 topics with mirrored hidden checks.
+- Bundled local Python documentation snippets generated from official docs.
+- In-app documentation modal with `F5`, `Esc`, and `O` keyboard flow.
+- PyPI distribution name `pythonlings`, which installs the `pythonlings` command.
+- Contributor guide, screenshots, release flow notes, and MIT license.
+
+### Verified
+
+- Full test suite: `125 passed`.
+- Curriculum/docs audit: every exercise has a configured docs URL and a bundled
+  local snippet.

pythonlings-0.3.0/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Pythonlings is "Rustlings for Python": a terminal TUI (Textual) where learners fix small broken exercises and checks rerun on save. Published on PyPI as `pythonlings` (formerly `python-learnings`; the unrelated `pylings` PyPI name belongs to a different project).
+
+## Commands
+
+```bash
+pip install -e ".[dev]"          # local install with pytest deps
+
+python -m pytest -q                              # full suite
+python -m pytest tests/unit/test_runner.py -q    # one file
+python -m pytest tests/unit/test_state.py::test_name -q  # one test
+
+pylings --root tests/fixtures/passing_curriculum verify   # smoke-test: all solutions pass their checks
+
+python -m build                  # sdist + wheel
+```
+
+Manual testing of flows: `pylings init --path ./learn-python` (create a learner workspace), `pylings` (TUI), `pylings run variables1`, `pylings dry-run variables1`, `pylings solution variables1`, `pylings hint`, `pylings list`, `pylings topics`, `pylings reset`. `--root` points any command at an arbitrary workspace (used heavily by tests against `tests/fixtures/`).
+
+## Architecture
+
+Two distinct trees in this repo:
+
+1. **The application** — `pylings/` (installable package)
+2. **The curriculum** — repo-root `exercises/`, `checks/`, `solutions/`, and `info.toml`
+
+At build time, hatch `force-include` maps the curriculum into the wheel as `pylings/curriculum/` (see `pyproject.toml`). `pylings init` copies that bundled curriculum into a self-contained learner workspace; progress lives in `<workspace>/.pylings/state.json` (written atomically, with `.bak` recovery on corruption).
+
+### Curriculum model
+
+Each exercise is a triple that must stay in sync, plus a manifest entry:
+
+- `exercises/<topic>/<name>.py` — the broken code the learner edits, containing the `# I AM NOT DONE` marker (defined in `core/exercise.py`)
+- `checks/<topic>/<name>.py` — hidden bare `assert` statements (not pytest)
+- `solutions/<name>.py` — reference answer
+- `info.toml` — ordered `[[exercises]]` entries with `name`, `path`, `hint`, `docs` URL; this file is the source of truth for exercise order and topics
+
+When changing curriculum, update all four, then run the relevant tests plus `pylings --root tests/fixtures/passing_curriculum verify`. Exercise names are topic + ordinal (`variables1`, `collections10`).
+
+### How checks run (`core/runner.py`)
+
+An exercise passes when a generated runner script `exec()`s the exercise source and then the check source in a shared namespace, in a fresh subprocess with a 5s timeout. The check sees the exercise's variables directly — that's why checks are bare asserts. Passing checks alone aren't enough: the learner must also remove `# I AM NOT DONE` to advance.
+
+### Layering
+
+- `pythonlings/core/` — all filesystem, manifest, state, reset, solutions, and runner logic. No UI imports. (Checks rerun on a debounce in the TUI editor, not a filesystem watcher.)
+- `pylings/screens/` and `pylings/widgets/` — Textual UI only; `pylings/app.py` wires them up; `pylings.tcss` holds styles.
+- `pylings/cli.py` — argparse subcommands; entry point `pylings = "pylings.cli:main"`.
+
+Keep UI behavior in screens/widgets and behavior logic in core — tests depend on this split (`tests/unit/` for core, `tests/integration/` for CLI/workspace flows, `tests/tui/` for Textual pilot tests, fixtures in `tests/fixtures/`).
+
+## Conventions
+
+- `requires-python = ">=3.9"`: guard newer-stdlib usage (e.g. `tomllib` falls back to `tomli` in `core/manifest.py`); `from __future__ import annotations` at the top of modules.
+- Async tests run under `pytest-asyncio` in auto mode (configured in `pyproject.toml`).
+- Tests are named `test_<behavior>.py` / `test_<expected_behavior>`.
+- Commits use conventional prefixes (`feat:`, `fix:`, `docs:`, `chore:`); work flows through `feature/*` → `dev` → `main`.
+- `AGENTS.md` holds the same contributor guidelines in long form.

pythonlings-0.3.0/CNAME

@@ -0,0 +1 @@
+pythonlings.abhik.ai

pythonlings-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+Pythonlings follows the Contributor Covenant Code of Conduct, version 2.1.
+
+## Our Standards
+
+Use welcoming and inclusive language, respect different experience levels, accept constructive feedback, and focus on what is best for the community.
+
+Unacceptable behavior includes harassment, personal attacks, sexualized language or imagery, publishing private information, or sustained disruption of project work.
+
+## Enforcement
+
+Report unacceptable behavior through GitHub Security Advisories. Maintainers may remove comments, close issues, block users, or take other appropriate action.

pythonlings-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Pythonlings is actively developed and **open to contributors** — beginners welcome.
+The fastest way in is a [`good first issue`](https://github.com/abhiksark/pythonlings/issues?q=is%3Aopen+label%3A%22good+first+issue%22).
+
+## Where the work is
+
+- **[0.3.0 roadmap](docs/roadmap/0.3.0.md)** — the current focus (wider adoption
+  for beginners). Each roadmap issue is written to be picked up cold: it has
+  context, scope, the exact files to touch, and how to verify.
+- Browse open issues by label: [`good first issue`](https://github.com/abhiksark/pythonlings/issues?q=is%3Aopen+label%3A%22good+first+issue%22),
+  [`help wanted`](https://github.com/abhiksark/pythonlings/issues?q=is%3Aopen+label%3A%22help+wanted%22).
+
+## Claiming an issue
+
+1. Comment on the issue to claim it (e.g. "I'd like to take this"). This avoids
+   two people doing the same work.
+2. Ask any questions right on the issue — happy to clarify scope.
+3. Open a PR that references the issue (`Closes #NN`).
+
+No need to wait for a formal assignment; claiming by comment is enough.
+
+## Development Setup
+
+```bash
+git clone git@github.com:abhiksark/pythonlings.git
+cd pythonlings
+pip install -e ".[dev]"   # or: uv pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Supported Python: 3.9+.
+
+## Curriculum Changes
+
+Update `info.toml`, `exercises/`, `checks/`, and `solutions/` together. Exercise
+and check paths must mirror each other, and **every exercise must have a passing
+reference solution** (`tests/integration/test_solution_verify.py` enforces this).
+
+## Pull Requests
+
+- Use focused branches named `feature/<name>` or `fix/<name>`.
+- Reference the issue you're closing (`Closes #NN`).
+- Include a short description, test output (`python -m pytest -q`), and
+  screenshots/GIFs for TUI changes.
+- Keep PRs scoped to one issue where possible.

pythonlings-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhik Sarkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.