Support Hints (#71)

piglei · web-flow · commit 4eadc5ca4af2 · 2023-12-11T22:10:52.000-08:00
diff --git a/challenges/basic-any/hints.md b/challenges/basic-any/hints.md
@@ -0,0 +1 @@
+Check out [Any](https://docs.python.org/3/library/typing.html#the-any-type).
diff --git a/challenges/intermediate-generic2/hints.md b/challenges/intermediate-generic2/hints.md
@@ -0,0 +1 @@
+Check out [TypeVar](https://docs.python.org/3/library/typing.html#typing.TypeVar), the `constraints` argument might be a good fit for this challenge.
diff --git a/docs/Contribute.md b/docs/Contribute.md
@@ -9,6 +9,7 @@
    For example, say you want to add a new challenge about [Protocols](https://mypy.readthedocs.io/en/stable/protocols.html). Since this is an advanced topic, you may name the directory `advanced-protocol`.
 
 4. Put a `question.py` and a `solution.py` in the new directory. Here's an example `question.py`:
+
    ```python
    """
    TODO:
@@ -34,4 +35,9 @@
 
 5. Test with [`pyright`](https://microsoft.github.io/pyright/#/installation?id=command-line) to make sure your new challenge works as expected.
 
-6. Create a Pull Request.
+6. *(Optional)* Add a hint message for the challenge,
+   A well-written *HINT* sometimes makes the challenge even better. Steps:
+   - Create a file named `hints.md` in the same directory.
+   - Write hint message in markdown format, e.g: `Check out TypeVar, the constraints argument might be a good fit for this challenge.`.
+
+7. Create a Pull Request.
diff --git a/docs/Development.md b/docs/Development.md
@@ -30,6 +30,7 @@
   ```
   pdm format
   ```
+
   Note: The project uses [djhtml](https://github.com/rtts/djhtml) to format HTML, which may conflicts with your editor's default formatter.
 
 - Start a development server
@@ -40,4 +41,16 @@
 
   Then visit http://127.0.0.1:5000/ to access the app in your local browser.
 
+- Update dependencies
+
+  ```
+  # Use pdm to manage dependencies
+  pdm add markdown
+
+  # Sync changes with requirements.txt after update
+  pdm export --prod --without-hashes > requirements.txt
+  ```
+
+  You may also want to use [pdm-autoexport](https://github.com/pdm-project/pdm-autoexport) extension, it sync the dependencies to other formats automatically.
+
 If you encounter any issues in the above steps, please file a bug and I'll fix it as soon as I can.
diff --git a/pdm.lock b/pdm.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -10,6 +10,7 @@ dependencies = [
     "typing-extensions>=4.8.0",
     "pyright>=1.1.338",
     "flask-sitemapper>=1.7.0",
+    "markdown>=3.5.1",
 ]
 requires-python = ">=3.12"
 readme = "README.md"
diff --git a/requirements.txt b/requirements.txt
@@ -7,9 +7,11 @@ flask==3.0.0
 flask-sitemapper==1.7.0
 itsdangerous==2.1.2
 jinja2==3.1.2
+markdown==3.5.1
 MarkupSafe==2.1.3
 nodeenv==1.8.0
 pyright==1.1.338
 setuptools==68.2.2
 typing-extensions==4.8.0
 Werkzeug==3.0.0
+
diff --git a/templates/challenge.html b/templates/challenge.html
@@ -66,10 +66,39 @@
     }
 
     .challenge-header__exerpt {
-      margin-bottom: 1.5rem;
+      margin-bottom: 0.2rem;
       line-height: 1.5;
     }
 
+    /* Hints styles */
+    .hints-container {
+      margin-bottom: 1.5rem;
+      font-size: 13px;
+    }
+    .hints-container #read-hints {
+      padding: 0.2em 0.8em;
+      font-size: 13px;
+    }
+    .hints-container #hints-missing {
+      margin-top: 0.8em;
+      /* The "secondary" style comes from https://picocss.com/docs/buttons.html */
+      color: var(--secondary);
+    }
+    .hints-container .hints-message {
+      display: none;
+      margin-top: 0.5em;
+      margin-bottom: 0;
+      padding: 0.75em 1em;
+      font-size: 13px;
+    }
+    html[data-theme='light'] .hints-container .hints-message {
+      box-shadow: none;
+      background-color: #f4f4f4;
+    }
+    .hints-container .hints-message * {
+      font-size: 13px;
+    }
+
     .challenge-main {
       display: flex;
       justify-content: space-between;
@@ -243,6 +272,14 @@
           fail type check, while others can pass.<br>
           Hit the "▶️ Run" button to see result.
         </p>
+        <div class="hints-container">
+          {% if hints_for_display %}
+            <a id="read-hints" role="button" class="secondary outline" href="javascript:void(0);">💡 Read Hints</a>
+          {% else %}
+            <div id="hints-missing" href="javascript:void(0);">💡 No Hints Available</div>
+          {% endif %}
+          <article class="hints-message">{{hints_for_display | safe}}</article>
+        </div>
       </div>
 
       <div class="challenge-main">
@@ -355,6 +392,22 @@
       myCodeMirror.setValue(code_under_test);
     };
 
+    // Set up hints events and functions
+    let hintBtn = document.getElementById('read-hints')
+    hintBtn.onclick = function () {
+      // Toggle the display of the hints message.
+      let msgElem = document.getElementsByClassName('hints-message')[0];
+      if (msgElem.style.display === 'block') {
+        msgElem.style.display = 'none';
+      } else {
+        msgElem.style.display = 'block';
+      }
+    };
+    // Make sure to open links in hints in new tab.
+    document.querySelectorAll('.hints-message a').forEach(function(elem) {
+      elem.setAttribute('target', '_blank');
+    })
+
     // Make sure the current challenge is visible to user.
     activeChallengeInList = document.getElementById("{{level}}-{{name}}");
     activeChallengeInList.scrollIntoView({block: 'center'});
diff --git a/tests/assets/challenges/basic-foo-hints/hints.md b/tests/assets/challenges/basic-foo-hints/hints.md
@@ -0,0 +1 @@
+Should contain some hint messages, but there is really nothing to add.
diff --git a/tests/assets/challenges/basic-foo-hints/question.py b/tests/assets/challenges/basic-foo-hints/question.py
@@ -0,0 +1,11 @@
+"""A simple question with hints, only for running tests.
+"""
+
+
+def foo():
+    pass
+
+
+## End of your code ##
+foo(1)
+foo(1, 2)  # expect-type-error
diff --git a/tests/assets/challenges/basic-foo/question.py b/tests/assets/challenges/basic-foo/question.py
@@ -0,0 +1,11 @@
+"""A simple question, only for running tests.
+"""
+
+
+def foo():
+    pass
+
+
+## End of your code ##
+foo(1)
+foo(1, 2)  # expect-type-error
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -16,7 +16,13 @@
 ALL_SOLUTIONS = list(CHALLENGES_DIR.glob("**/solution*.py"))
 
 
-@pytest.fixture
+@pytest.fixture()
+def assets_dir() -> Path:
+    """The directory contains test assets."""
+    return Path(__file__).parent / "assets"
+
+
+@pytest.fixture()
 def test_client() -> FlaskClient:
     return app.test_client()
 
diff --git a/tests/test_challenge.py b/tests/test_challenge.py
@@ -0,0 +1,33 @@
+from pathlib import Path
+
+import pytest
+from views.challenge import ChallengeKey, ChallengeManager
+
+
+class TestLoadChallenges:
+    def test_load_empty_dir(self, tmpdir):
+        assert ChallengeManager(Path(tmpdir)).challenge_count == 0
+
+    def test_defaults(self):
+        assert ChallengeManager().challenge_count > 0
+
+    def test_load_tests_assets(self, assets_dir):
+        mgr = ChallengeManager(assets_dir / "challenges")
+        assert mgr.challenge_count > 0
+
+
+class TestChallengeWithHints:
+    @pytest.fixture()
+    def challenge_mgr(self, assets_dir):
+        return ChallengeManager(assets_dir / "challenges")
+
+    def test_misc(self, challenge_mgr):
+        c_foo = challenge_mgr.get_challenge(ChallengeKey.from_str("basic-foo"))
+        assert c_foo.hints is None
+
+        # Get the challenge with hints
+        c_foo_hints = challenge_mgr.get_challenge(
+            ChallengeKey.from_str("basic-foo-hints")
+        )
+        assert c_foo_hints.hints
+        assert isinstance(c_foo_hints.hints, str)
diff --git a/tests/test_utils.py b/tests/test_utils.py
@@ -1,4 +1,5 @@
 from views.challenge import ChallengeManager
+from views.utils.text import render_hints
 
 
 def test_run_type_check_with_pyright():
@@ -18,3 +19,8 @@ def test_run_type_check_with_pyright():
         "2: error: Expected type error but instead passed\n\n"
         "Found 2 errors"
     )
+
+
+def test_render_hints():
+    content = render_hints("[foo](http://example.com)")
+    assert "<a href=" in content
diff --git a/views/challenge.py b/views/challenge.py
@@ -1,16 +1,14 @@
-import glob
 import io
-import os
-import re
 import random
+import re
 import subprocess
 import tempfile
 import tokenize
+from collections import defaultdict
 from dataclasses import dataclass, field
 from enum import StrEnum
 from pathlib import Path
-from typing import ClassVar, TypeAlias
-import datetime
+from typing import ClassVar, Optional, TypeAlias
 
 ROOT_DIR = Path(__file__).parent.parent
 
@@ -34,16 +32,28 @@ class ChallengeKey:
     level: Level
     name: ChallengeName
 
+    @classmethod
+    def from_str(cls, key: str):
+        """Create a key object from a string like "basic-foo"."""
+        level, name = key.split("-", maxsplit=1)
+        return cls(Level(level), name)
+
 
 @dataclass
 class Challenge:
+    """A challenge object.
+
+    :param hints: An optional string of hints, use markdown syntax.
+    """
+
     CODE_SPLITTER: ClassVar[str] = "\n## End of your code ##\n"
 
     name: ChallengeName
     level: Level
     code: str
     user_code: str = field(default="", init=False)
     test_code: str = field(default="", init=False)
+    hints: Optional[str] = None
 
     def __post_init__(self):
         self.parse_code()
@@ -60,8 +70,15 @@ class TypeCheckResult:
 
 
 class ChallengeManager:
-    def __init__(self):
-        self.challenges: dict[ChallengeKey, Challenge] = self._load_challenges()
+    """The manager for challenges.
+
+    :param root_dir: The root directory that contains the files of challenges.
+    """
+
+    def __init__(self, root_dir: Optional[Path] = None):
+        if not root_dir:
+            root_dir = ROOT_DIR / "challenges"
+        self.challenges: dict[ChallengeKey, Challenge] = self._load_challenges(root_dir)
         self.challenges_groupby_level: dict[Level, list[ChallengeName]]
         self.challenges_groupby_level = self._get_challenges_groupby_level()
 
@@ -71,6 +88,11 @@ def has_challenge(self, key: ChallengeKey) -> bool:
     def get_challenge(self, key: ChallengeKey) -> Challenge:
         return self.challenges[key]
 
+    @property
+    def challenge_count(self) -> int:
+        """The count of challenges."""
+        return len(self.challenges)
+
     def run_challenge(self, key: ChallengeKey, user_code: str) -> TypeCheckResult:
         challenge = self.get_challenge(key)
         # Make sure user code ends with a new line to avoid issue #63.
@@ -82,26 +104,34 @@ def get_random_challenge(self) -> dict[str, str]:
         return {"level": level, "name": name}
 
     @staticmethod
-    def _load_challenges() -> dict[ChallengeKey, Challenge]:
+    def _load_challenges(root_dir: Path) -> dict[ChallengeKey, Challenge]:
         challenges = {}
-        for filename in glob.glob(f"{ROOT_DIR}/challenges/*/question.py"):
-            challenge_folder_name = os.path.basename(os.path.dirname(filename))
-            level, challenge_name = challenge_folder_name.split("-", maxsplit=1)
-            with open(filename, "r") as file:
-                code = file.read()
-            challenges[ChallengeKey(Level(level), challenge_name)] = Challenge(
-                name=challenge_name,
-                level=Level(level),
-                code=code,
-            )
+        for challenge_folder in root_dir.iterdir():
+            question_source = challenge_folder / "question.py"
+            if not question_source.exists():
+                continue
 
+            # Try to read the optional hints file
+            hints_file = challenge_folder / "hints.md"
+            if hints_file.exists():
+                hints = hints_file.read_text().strip()
+            else:
+                hints = None
+
+            key = ChallengeKey.from_str(challenge_folder.name)
+            challenges[key] = Challenge(
+                name=key.name,
+                level=key.level,
+                code=question_source.read_text(),
+                hints=hints,
+            )
         return challenges
 
     def _get_challenges_groupby_level(self) -> dict[Level, list[ChallengeName]]:
-        groups: dict[str, list[ChallengeName]] = {}
+        groups: defaultdict[str, list[ChallengeName]] = defaultdict(list)
 
         for challenge in self.challenges.values():
-            groups.setdefault(challenge.level, []).append(challenge.name)
+            groups[challenge.level].append(challenge.name)
 
         # Sort challenge by name alphabetically.
         for challenge_names in groups.values():
diff --git a/views/utils/__init__.py b/views/utils/__init__.py
diff --git a/views/utils/text.py b/views/utils/text.py
@@ -0,0 +1,6 @@
+import markdown
+
+
+def render_hints(hints: str) -> str:
+    """Render the hints messages to HTML format."""
+    return markdown.markdown(hints)
diff --git a/views/views.py b/views/views.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Check out [Any](https://docs.python.org/3/library/typing.html#the-any-type).`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Check out [TypeVar](https://docs.python.org/3/library/typing.html#typing.TypeVar), the `constraints` argument might be a good fit for this challenge.
Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,7 @@ dependencies = [`
`10`	`10`	`"typing-extensions>=4.8.0",`
`11`	`11`	`"pyright>=1.1.338",`
`12`	`12`	`"flask-sitemapper>=1.7.0",`
	`13`	`+ "markdown>=3.5.1",`
`13`	`14`	`]`
`14`	`15`	`requires-python = ">=3.12"`
`15`	`16`	`readme = "README.md"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Should contain some hint messages, but there is really nothing to add.`