Merge pull request #22 from i-walk-away/feature/lesson_topics

feature/lesson_topics

Author: i-walk-away

CONTRIBUTING.md

@@ -12,17 +12,63 @@ If you want to add a new lesson to pydantic quest, do this:
     * `lesson.yaml`
     * `theory.md`
     * `starter.py`
-    * `cases.yaml`
+    * `cases.yaml` -- *for theory-only lessons with no coding assignment, leave this file empty*
 3. Head to [lessons/index.yaml](lessons/index.yaml) and add the following:
 
 ```yaml
   - slug: dash-separated-lesson-name
-    order: <integer>
+    order: "<order-path>"
+    no_code: false   # or `true` if there is no assignment intended for the lesson
 ```
 
-The "order" field changes the order in which lessons appear in pydantic quest.
-If you're not sure, just use whatever highest order already exists in index and
-add +1 to it. I will reorder everything myself if needed :)
+The `slug` must exactly match the lesson directory name in [lessons/](lessons/).
+For example, this:
+
+```yaml
+  - slug: field-validators
+    order: "1.1"
+```
+
+must correspond to this directory:
+
+```text
+lessons/field-validators/
+```
+
+The `order` field controls lesson position in the UI and now supports
+hierarchical numbering.
+
+Valid examples:
+
+```yaml
+  - slug: validators
+    order: "1"
+  - slug: field-validators
+    order: "1.1"
+  - slug: model-validators
+    order: "1.2"
+  - slug: models
+    order: "2"
+  - slug: basemodel
+    order: "2.1"
+```
+
+Rules:
+
+- use positive numeric segments separated by dots
+- like this: `"1"`, `"1.1"`, `"2.3.4"`
+- every order value must be unique
+- set `no_code: true` for theory-only lessons with no coding task
+
+Sorting is numeric by segment, so lessons appear like:
+
+- `1`
+- `1.1`
+- `1.2`
+- `2`
+
+If you're not sure where a lesson should go, just add it near the right section
+and i can reorder things myself later :)
 
 ## Explanation of the 4 neccessary files
 
@@ -58,6 +104,8 @@ Test cases for your lesson. Just refer to [`lessons/lesson-template/cases.yaml`]
 You can find
 a *lot* of information there about how it works and how exactly to design your own test cases.
 Please inform me if it is still not very clear.
+If the lesson is marked `no_code: true`, this file is still required for consistency,
+but it can be empty, `{}`, or `cases: null`. The `run` button will be disabled in the UI.
 
 ## Contributor checklist
 

README.md

@@ -2,16 +2,20 @@
 
 Free interactive course on Pydantic v2.
 
-It is designed to teach you the capabilities of pydantic - a validation library for python. It's (hopefully) beginner friendly, while still being useful to those already familiar with the library.
-
-
-
+It is designed to teach you the capabilities of pydantic - a validation library for python. It's (hopefully) beginner
+friendly, while still being useful to those already familiar with the library.
 
 # What is wrong with the official documentation? (note: last section)
 
-Absolutely nothing, this courae is just another way to learn the library, that might fit better with different people's learning styles.
+Absolutely nothing, this courae is just another way to learn the library, that might fit better with different people's
+learning styles.
 
-Pydantic's docs are great at showing you how to do things and what functionality exists in the API, but they leave the "why does this feature exist and what are its use cases" for you to figure out on your own. It's not a flaw, you don't want to flood your docs with stuff like this. But it does open an another way of learning pydantic - through tutorials and courses, where technical information can be presented in a different, more friendly way.
+Pydantic's docs are great at showing you how to do things and what functionality exists in the API, but they leave the "
+why does this feature exist and what are its use cases" for you to figure out on your own. It's not a flaw, you don't
+want to flood your docs with stuff like this. But it does open an another way of learning pydantic - through tutorials
+and courses, where technical information can be presented in a different, more friendly way.
 
-Pydantic is basically industry standard now, but a lot of people only use the basic basemodel difinitions, some simple validators and nothing more. Even while working on this very project i realised that pydantic has already solved a lot of things that i have been reinventing for years.
+Pydantic is basically industry standard now, but a lot of people only use the basic basemodel difinitions, some simple
+validators and nothing more. Even while working on this very project i realised that pydantic has already solved a lot
+of things that i have been reinventing for years.
 

backend/migrations/versions/0b7e7f6f2a4d_add_cascade_delete_to_lesson_progress.py

@@ -0,0 +1,66 @@
+"""add cascade delete to lesson_progress
+
+Revision ID: 0b7e7f6f2a4d
+Revises: 642e01a7aceb
+Create Date: 2026-03-10 21:35:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "0b7e7f6f2a4d"
+down_revision: Union[str, Sequence[str], None] = "642e01a7aceb"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _find_lesson_progress_lesson_fk_name() -> str:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+
+    for foreign_key in inspector.get_foreign_keys("lesson_progress"):
+        constrained_columns = foreign_key.get("constrained_columns") or []
+        referred_table = foreign_key.get("referred_table")
+
+        if constrained_columns == ["lesson_id"] and referred_table == "lessons":
+            name = foreign_key.get("name")
+            if not name:
+                raise RuntimeError("lesson_progress.lesson_id foreign key exists without a name")
+            return name
+
+    raise RuntimeError("Could not find lesson_progress.lesson_id foreign key")
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    foreign_key_name = _find_lesson_progress_lesson_fk_name()
+
+    op.drop_constraint(foreign_key_name, "lesson_progress", type_="foreignkey")
+    op.create_foreign_key(
+        "fk_lesson_progress_lesson_id_lessons",
+        "lesson_progress",
+        "lessons",
+        ["lesson_id"],
+        ["id"],
+        ondelete="CASCADE",
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_constraint(
+        "fk_lesson_progress_lesson_id_lessons",
+        "lesson_progress",
+        type_="foreignkey",
+    )
+    op.create_foreign_key(
+        "fk_lesson_progress_lesson_id_lessons",
+        "lesson_progress",
+        "lessons",
+        ["lesson_id"],
+        ["id"],
+    )

…lign_lessons_schema_with_cases_column.py …tions/versions/642e01a7aceb_hierarchy.pybackend/migrations/versions/e558abd4298f_align_lessons_schema_with_cases_column.py renamed to backend/migrations/versions/642e01a7aceb_hierarchy.py backend/migrations/versions/e558abd4298f_align_lessons_schema_with_cases_column.py renamed to backend/migrations/versions/642e01a7aceb_hierarchy.py

@@ -1,8 +1,8 @@
-"""align lessons schema with cases column
+"""hierarchy
 
-Revision ID: e558abd4298f
+Revision ID: 642e01a7aceb
 Revises: 
-Create Date: 2026-03-09 20:09:58.137245
+Create Date: 2026-03-10 19:10:23.746018
 
 """
 from typing import Sequence, Union
@@ -11,7 +11,7 @@
 from alembic import op
 
 # revision identifiers, used by Alembic.
-revision: str = 'e558abd4298f'
+revision: str = '642e01a7aceb'
 down_revision: Union[str, Sequence[str], None] = None
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
@@ -22,7 +22,7 @@ def upgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
     op.create_table(
         'lessons',
-        sa.Column('order', sa.Integer(), nullable=False),
+        sa.Column('order', sa.String(length=64), nullable=False),
         sa.Column('slug', sa.String(length=255), nullable=False),
         sa.Column('name', sa.String(length=255), nullable=False),
         sa.Column('body_markdown', sa.Text(), nullable=False),

backend/migrations/versions/8c7e3c1b5e21_add_no_code_flag_to_lessons.py

@@ -0,0 +1,36 @@
+"""add no_code flag to lessons
+
+Revision ID: 8c7e3c1b5e21
+Revises: 0b7e7f6f2a4d
+Create Date: 2026-03-10 22:35:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "8c7e3c1b5e21"
+down_revision: Union[str, Sequence[str], None] = "0b7e7f6f2a4d"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.add_column(
+        "lessons",
+        sa.Column(
+            "no_code",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.false(),
+        ),
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_column("lessons", "no_code")

backend/src/app/content/loader.py

@@ -9,6 +9,7 @@
     LoadedLesson,
 )
 from src.app.content.validator import LessonsContentValidator
+from src.app.domain.lesson_order import lesson_order_key
 
 LESSON_META_FILENAME = "lesson.yaml"
 LESSON_THEORY_FILENAME = "theory.md"
@@ -47,13 +48,14 @@ def load(self) -> list[LoadedLesson]:
         for index_item in index_file.lessons:
             lesson_dir = self.root_dir / index_item.slug
             lesson_meta = self._load_meta(lesson_dir=lesson_dir)
-            lesson_cases = self._load_cases(lesson_dir=lesson_dir)
+            lesson_cases = self._load_cases(lesson_dir=lesson_dir, no_code=index_item.no_code)
             theory = self._read_text(path=lesson_dir / LESSON_THEORY_FILENAME)
             starter_code = self._read_text(path=lesson_dir / LESSON_STARTER_FILENAME)
             lessons.append(
                 LoadedLesson(
                     slug=index_item.slug,
                     order=index_item.order,
+                    no_code=index_item.no_code,
                     name=lesson_meta.title,
                     body_markdown=theory,
                     code_editor_default=starter_code,
@@ -62,7 +64,7 @@ def load(self) -> list[LoadedLesson]:
                 ),
             )
 
-        lessons.sort(key=lambda item: item.order)
+        lessons.sort(key=lambda item: lesson_order_key(item.order))
 
         return lessons
 
@@ -78,15 +80,24 @@ def _load_meta(self, lesson_dir: Path) -> LessonMetaFile:
 
         return LessonMetaFile.model_validate(obj=payload)
 
-    def _load_cases(self, lesson_dir: Path) -> LessonCasesFile:
+    def _load_cases(self, lesson_dir: Path, *, no_code: bool) -> LessonCasesFile:
         """
         Load lesson cases file.
 
         :param lesson_dir: lesson directory path
+        :param no_code: lesson has no coding task
 
         :return: lesson cases
         """
-        payload = self._read_yaml(path=lesson_dir / LESSON_CASES_FILENAME)
+        cases_path = lesson_dir / LESSON_CASES_FILENAME
+
+        payload = self._read_yaml(path=cases_path)
+
+        if no_code:
+            raw_cases = payload.get("cases")
+
+            if raw_cases is None:
+                return LessonCasesFile(cases=[])
 
         return LessonCasesFile.model_validate(obj=payload)
 

backend/src/app/content/models.py

@@ -4,14 +4,16 @@
 
 from pydantic import ConfigDict, field_validator, model_validator
 
+from src.app.domain.lesson_order import normalize_lesson_order
 from src.app.domain.models.dto.extended_basemodel import ExtendedBaseModel
 
 
 class LessonIndexItem(ExtendedBaseModel):
     model_config = ConfigDict(extra="forbid")
 
     slug: str
-    order: int
+    order: str
+    no_code: bool = False
 
     @field_validator("slug")
     @classmethod
@@ -23,14 +25,10 @@ def validate_slug(cls, value: str) -> str:
 
         return normalized
 
-    @field_validator("order")
+    @field_validator("order", mode="before")
     @classmethod
-    def validate_order(cls, value: int) -> int:
-        if value < 1:
-            message = "order must be positive."
-            raise ValueError(message)
-
-        return value
+    def validate_order(cls, value: str | int | float) -> str:
+        return normalize_lesson_order(value=value)
 
 
 class LessonsIndexFile(ExtendedBaseModel):
@@ -104,21 +102,18 @@ class LoadedLesson(ExtendedBaseModel):
     model_config = ConfigDict(extra="forbid")
 
     slug: str
-    order: int
+    order: str
+    no_code: bool = False
     name: str
     body_markdown: str
     code_editor_default: str
     cases: list[LessonCaseFileItem]
     source_dir: Path
 
-    @field_validator("order")
+    @field_validator("order", mode="before")
     @classmethod
-    def validate_order(cls, value: int) -> int:
-        if value < 1:
-            message = "order must be positive."
-            raise ValueError(message)
-
-        return value
+    def validate_order(cls, value: str | int | float) -> str:
+        return normalize_lesson_order(value=value)
 
     @field_validator("slug", "name", "body_markdown")
     @classmethod

backend/src/app/content/validator.py

@@ -1,4 +1,5 @@
 from src.app.content.models import LessonsIndexFile
+from src.app.domain.lesson_order import lesson_order_key
 
 
 class LessonsContentValidator:
@@ -24,12 +25,10 @@ def validate_index(index_file: LessonsIndexFile) -> None:
 
             seen_slugs.add(item.slug)
 
-            if item.order < 1:
-                message = f"lesson order must be positive: {item.slug}"
-                raise ValueError(message)
-
             if item.order in seen_orders:
                 message = f"duplicate lesson order in index: {item.order}"
                 raise ValueError(message)
 
             seen_orders.add(item.order)
+
+        _ = sorted(lesson_order_key(item.order) for item in index_file.lessons)

backend/src/app/core/exceptions/lesson_exc.py

@@ -25,7 +25,7 @@ class LessonOrderInvalid(HTTPException):
     Lesson order is invalid.
     """
     status_code = 422
-    detail = "Lesson order must be sequential with no gaps."
+    detail = "Lesson order must be unique and use a dotted path like 1 or 2.3."
 
     def __init__(self) -> None:
         """