project-youler 0.0.1__tar.gz

project_youler-0.0.1/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

project_youler-0.0.1/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: project-youler
+Version: 0.0.1
+Summary: A CLI tool for managing solutions to Project Euler problems.
+Keywords: project-euler,euler
+Author: Henry Swanson
+Author-email: Henry Swanson <henryswanson94@gmail.com>
+License-Expression: Unlicense
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: beautifulsoup4>=0.0.2
+Requires-Dist: click>=8.3.1
+Requires-Dist: requests>=2.32.5
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/HenrySwanson/project-euler-framework
+Description-Content-Type: text/markdown
+
+# project-youler
+
+A command line tool for managing your [Project Euler](https://projecteuler.net/) solutions (if they're written in Python).
+
+Features include:
+- Stores all your confirmed answers in a local JSON file. If you refactor your solution, you can run the `check` command to make sure none of your solvers have broken.
+- Fetches the problem description from the Project Euler website and creates a template file for you to fill in with your solution.
+- Shows an overview of how many problems you've solved and/or attempted.
+- Really basic timing info for profiling your solutions.
+
+This package doesn't contain any solutions itself (that would be uncool).
+
+## Setup
+
+In the project where you've written your solutions, add this package as a dependency, and create an entry point for the `click` CLI returned by `make_cli`.
+
+Example:
+```python
+# src/my_euler/__main__.py
+from pathlib import Path
+
+from youler import EulerConfig, make_cli
+
+from . import bonus, problems
+
+cli = make_cli(
+    EulerConfig(
+        root=Path(__file__).parents[2],
+        problems=problems,
+        bonus=bonus,
+        answer_file="answers.json",
+    )
+)
+
+if __name__ == "__main__":
+    cli()
+```
+
+If you wire it up as a script, you can run `euler` from anywhere in the
+project:
+
+```toml
+[project.scripts]
+euler = "my_euler.__main__:cli"
+```
+
+Aside: `make_cli` returns an ordinary `click.Group`, so you can register extra commands of your own on it.
+
+### Configuration
+
+| field | meaning |
+| --- | --- |
+| `root` | Root of your repository; `answer_file` is resolved against it. |
+| `problems` | The imported package holding your numbered solvers. |
+| `bonus` | The imported package holding your bonus solvers. Optional. |
+| `answer_file` | Where confirmed answers are saved. Defaults to `answers.json`. |
+
+## Writing a solver
+
+A solver is a module named `pNNNN.py` inside your problems package, exporting
+`solve_problem()`:
+
+```python
+# src/my_euler/problems/p0001.py
+"""
+If we list all the natural numbers below 10 that are multiples of 3 or 5, we
+get 3, 5, 6 and 9. The sum of these multiples is 23.
+
+Find the sum of all the multiples of 3 or 5 below 1000.
+"""
+
+
+def solve_problem() -> int:
+    return sum(n for n in range(1000) if n % 3 == 0 or n % 5 == 0)
+```
+
+(*okay, there's **one** solution in this package*)
+
+`euler create 1` creates that file for you, with the problem statement fetched
+from the Project Euler website and formatted into the docstring.
+
+An answer may be an `int` or a `str`, as far as I know.
+
+### Bonus problems
+
+<details>
+  <summary>Spoiler warning</summary>
+  
+  Project Euler has some mysterious bonus problems that unlock after unknown conditions. Personally, I've only seen two of them. I've managed to wedge them into this framework in a reasonably clean way, just specify an arbitrary string key and it'll create a bonus problem.
+
+  For example, if you create a file `bonus/p18i.py`, you can run it with `euler run 18i` and it'll work like other problems.
+
+  Details subject to change since I have no idea what other bonus problems lurk in the darkness.
+</details>
+
+## Commands
+
+> [!NOTE]
+> Most of these commands take arguments of the form `a-b`, meaning problems _a_
+> to _b_ inclusive, the id of a bonus problem, and the special value `all`,
+> which means slightly different things to different commands.
+>
+> You can always pass `--help` for more detail on a particular command.
+
+- `create <n>`: Create `problems/pNNNN.py` for problem #n, prefilled with the problem statement from the Project Euler website.
+- `run <n>`: Run the solver for problem #n. If there is already a saved answer, it'll be compared with it, if not, you'll be prompted whether you want to save it. (Submit it to PE first so you know it's right!)
+- `check <n>`: Run the solver for problem #n and compare it against the saved answer, without prompting. `check all` covers everything you've written or saved, which is nice for validating a refactor.
+- `time <n>`: Run one problem several times and report the average time taken.
+- `status`: Show which problems have been downloaded, solved, or neither.
+- `answers`: Subcommands for manipulating the answer save file.
+  - `show <n>`: Show saved answers.
+  - `delete <n>`: Delete saved answers.
+
+## Development
+
+I use `uv`, `mypy` and `pytest`, in a very typical setup.
+

project_youler-0.0.1/README.md

@@ -0,0 +1,117 @@
+# project-youler
+
+A command line tool for managing your [Project Euler](https://projecteuler.net/) solutions (if they're written in Python).
+
+Features include:
+- Stores all your confirmed answers in a local JSON file. If you refactor your solution, you can run the `check` command to make sure none of your solvers have broken.
+- Fetches the problem description from the Project Euler website and creates a template file for you to fill in with your solution.
+- Shows an overview of how many problems you've solved and/or attempted.
+- Really basic timing info for profiling your solutions.
+
+This package doesn't contain any solutions itself (that would be uncool).
+
+## Setup
+
+In the project where you've written your solutions, add this package as a dependency, and create an entry point for the `click` CLI returned by `make_cli`.
+
+Example:
+```python
+# src/my_euler/__main__.py
+from pathlib import Path
+
+from youler import EulerConfig, make_cli
+
+from . import bonus, problems
+
+cli = make_cli(
+    EulerConfig(
+        root=Path(__file__).parents[2],
+        problems=problems,
+        bonus=bonus,
+        answer_file="answers.json",
+    )
+)
+
+if __name__ == "__main__":
+    cli()
+```
+
+If you wire it up as a script, you can run `euler` from anywhere in the
+project:
+
+```toml
+[project.scripts]
+euler = "my_euler.__main__:cli"
+```
+
+Aside: `make_cli` returns an ordinary `click.Group`, so you can register extra commands of your own on it.
+
+### Configuration
+
+| field | meaning |
+| --- | --- |
+| `root` | Root of your repository; `answer_file` is resolved against it. |
+| `problems` | The imported package holding your numbered solvers. |
+| `bonus` | The imported package holding your bonus solvers. Optional. |
+| `answer_file` | Where confirmed answers are saved. Defaults to `answers.json`. |
+
+## Writing a solver
+
+A solver is a module named `pNNNN.py` inside your problems package, exporting
+`solve_problem()`:
+
+```python
+# src/my_euler/problems/p0001.py
+"""
+If we list all the natural numbers below 10 that are multiples of 3 or 5, we
+get 3, 5, 6 and 9. The sum of these multiples is 23.
+
+Find the sum of all the multiples of 3 or 5 below 1000.
+"""
+
+
+def solve_problem() -> int:
+    return sum(n for n in range(1000) if n % 3 == 0 or n % 5 == 0)
+```
+
+(*okay, there's **one** solution in this package*)
+
+`euler create 1` creates that file for you, with the problem statement fetched
+from the Project Euler website and formatted into the docstring.
+
+An answer may be an `int` or a `str`, as far as I know.
+
+### Bonus problems
+
+<details>
+  <summary>Spoiler warning</summary>
+  
+  Project Euler has some mysterious bonus problems that unlock after unknown conditions. Personally, I've only seen two of them. I've managed to wedge them into this framework in a reasonably clean way, just specify an arbitrary string key and it'll create a bonus problem.
+
+  For example, if you create a file `bonus/p18i.py`, you can run it with `euler run 18i` and it'll work like other problems.
+
+  Details subject to change since I have no idea what other bonus problems lurk in the darkness.
+</details>
+
+## Commands
+
+> [!NOTE]
+> Most of these commands take arguments of the form `a-b`, meaning problems _a_
+> to _b_ inclusive, the id of a bonus problem, and the special value `all`,
+> which means slightly different things to different commands.
+>
+> You can always pass `--help` for more detail on a particular command.
+
+- `create <n>`: Create `problems/pNNNN.py` for problem #n, prefilled with the problem statement from the Project Euler website.
+- `run <n>`: Run the solver for problem #n. If there is already a saved answer, it'll be compared with it, if not, you'll be prompted whether you want to save it. (Submit it to PE first so you know it's right!)
+- `check <n>`: Run the solver for problem #n and compare it against the saved answer, without prompting. `check all` covers everything you've written or saved, which is nice for validating a refactor.
+- `time <n>`: Run one problem several times and report the average time taken.
+- `status`: Show which problems have been downloaded, solved, or neither.
+- `answers`: Subcommands for manipulating the answer save file.
+  - `show <n>`: Show saved answers.
+  - `delete <n>`: Delete saved answers.
+
+## Development
+
+I use `uv`, `mypy` and `pytest`, in a very typical setup.
+

project_youler-0.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "project-youler"
+version = "0.0.1"
+description = "A CLI tool for managing solutions to Project Euler problems."
+readme = "README.md"
+license = "Unlicense"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+keywords = [
+    "project-euler",
+    "euler",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "beautifulsoup4>=0.0.2",
+    "click>=8.3.1",
+    "requests>=2.32.5",
+]
+
+[[project.authors]]
+name = "Henry Swanson"
+email = "henryswanson94@gmail.com"
+
+[project.urls]
+Repository = "https://github.com/HenrySwanson/project-euler-framework"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "types-beautifulsoup4>=4.12.0.20250516",
+    "types-requests>=2.33.0.20260712",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "youler"
+
+[tool.mypy]
+allow_redefinition = true
+strict = true

project_youler-0.0.1/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[project]
+name = "project-youler"
+version = "0.0.1"
+
+# Various metadata for PyPI
+description = "A CLI tool for managing solutions to Project Euler problems."
+readme = "README.md"
+license = "Unlicense"
+license-files = ["LICENSE"]
+authors = [{ name = "Henry Swanson", email = "henryswanson94@gmail.com" }]
+requires-python = ">=3.13"
+keywords = ["project-euler", "euler"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+urls = { Repository = "https://github.com/HenrySwanson/project-euler-framework" }
+
+# Build and dependency stuff
+dependencies = ["beautifulsoup4>=0.0.2", "click>=8.3.1", "requests>=2.32.5"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "types-beautifulsoup4>=4.12.0.20250516",
+    "types-requests>=2.33.0.20260712",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "youler"
+
+# Other tools
+[tool.mypy]
+allow_redefinition = true
+strict = true

project_youler-0.0.1/src/youler/__init__.py

@@ -0,0 +1,4 @@
+from .cli import make_cli
+from .config import EulerConfig
+
+__all__ = ["EulerConfig", "make_cli"]

project_youler-0.0.1/src/youler/answer.py

@@ -0,0 +1,71 @@
+"""
+Previously, I saved these files in a weakly obscured binary format, in order to
+discourage accidentally stumbling across the answers. I no longer think this is
+necessary -- the answers are all over the web, and I'm not even publishing this
+version of the repo with all my answers in it. So now it's just JSON.
+"""
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TypeAlias
+
+# Numbered problems are identified by their number, and the bonus problems that
+# Project Euler doesn't number by a string like "18i". Both appear as keys in
+# the answer file, which is why the type lives here.
+ProblemId: TypeAlias = int | str
+Answer: TypeAlias = int | str
+
+
+def parse_problem_id(key: str) -> ProblemId:
+    """Reads an answer file key, as a number if it looks like one."""
+    try:
+        return int(key)
+    except ValueError:
+        return key
+
+
+def problem_sort_key(id: ProblemId) -> tuple[int, int, str]:
+    """
+    Sorts numbered problems numerically and ahead of the bonus ones, which go
+    alphabetically. Needed because ints and strs don't compare against
+    each other.
+    """
+    if isinstance(id, int):
+        return (0, id, "")
+    return (1, 0, id)
+
+
+def parse_answer_file(path: Path) -> dict[ProblemId, Answer]:
+    """
+    Reads the answer file and returns a dictionary mapping problem ids to
+    their answers. A repository that hasn't saved any yet has no file at all,
+    which reads as empty.
+    """
+    if not path.exists():
+        return {}
+
+    with open(path, "r") as f:
+        contents = json.load(f)
+
+    # confirm the structure
+    answers = {}
+    assert isinstance(contents, dict)
+    for k, v in contents.items():
+        assert isinstance(v, Answer)
+        answers[parse_problem_id(k)] = v
+
+    return answers
+
+
+def save_answer_file(path: Path, answers: Mapping[ProblemId, Answer]) -> None:
+    """
+    Overwrites the contents of the answer file with the given answer mapping.
+    """
+
+    # JSON keys are strings, so sort before writing rather than with
+    # `sort_keys`, which has no way to order a bonus id against a number.
+    ordered = {str(id): answers[id] for id in sorted(answers, key=problem_sort_key)}
+
+    with open(path, "w") as f:
+        json.dump(ordered, f, indent=True)

project_youler-0.0.1/src/youler/cli.py

@@ -0,0 +1,411 @@
+import enum
+from collections import defaultdict
+from pathlib import Path
+from time import perf_counter
+from typing import Final, Iterable
+
+import click
+
+from .answer import (
+    Answer,
+    ProblemId,
+    parse_answer_file,
+    parse_problem_id,
+    problem_sort_key,
+    save_answer_file,
+)
+from .config import EulerConfig
+from .intervals import format_as_intervals, parse_interval_string
+from .problems import (
+    format_problem_id,
+    get_problem_description,
+    list_all_problems,
+    list_bonus_problems,
+    list_problems,
+    problem_path,
+    run_problem,
+    run_problem_if_exists,
+)
+
+TEMPLATE_FILE = Path(__file__).parent / "problem.py.template"
+
+# ==== TODO LIST ====
+# - can i do some python deepmagic to detect the '...' in the problem file?
+#   might help with distinguishing "downloaded" from "started"
+
+
+class CheckStatus(enum.Enum):
+    SUCCESS = enum.auto()
+    FAILURE = enum.auto()
+    UNSOLVED = enum.auto()
+    NEEDS_ATTENTION = enum.auto()
+
+
+class ProblemAlias(enum.Enum):
+    """
+    Synonyms for certain subsets of problems. Now that we're using strings
+    for the bonus problem IDs, it's nice to have a type-system-level difference
+    between "all" and other strings.
+    """
+
+    # TODO: implement others?
+    ALL = enum.auto()
+
+
+def parse_interval_input(args: Iterable[str]) -> set[ProblemId] | ProblemAlias:
+    """
+    Returns either a set of problem ids that was explicitly specified by the
+    user, or the ALL sentinel, if "all" was passed in. (The caller may want to
+    handle that themselves.)
+    """
+
+    problems: set[ProblemId] = set()
+
+    for arg in args:
+        if arg == "all":
+            return ProblemAlias.ALL  # doesn't matter what else was passed
+
+        try:
+            (start, end) = parse_interval_string(arg)
+        except ValueError:
+            # neither a number nor a range, so it's probably a bonus problem
+            problems.add(arg)
+            continue
+
+        problems.update(range(start, end + 1))
+
+    return problems
+
+
+# ==== CLI Commands ====
+
+
+@click.command
+@click.argument("problems", type=str, nargs=-1, required=True)
+@click.pass_obj
+def create(config: EulerConfig, problems: tuple[str, ...]) -> None:
+    """Use the template file to create a starting point for the given problems."""
+
+    numbers = parse_interval_input(problems)
+    if numbers is ProblemAlias.ALL:
+        raise click.UsageError('"all" is not a valid argument for `create`')
+
+    for n in sorted(numbers, key=problem_sort_key):
+        # Project Euler has no page to fetch for the problems it doesn't number
+        if not isinstance(n, int):
+            click.secho(f"Can't create a file for bonus problem {n}", fg="red")
+            continue
+
+        try:
+            create_single_file(config, n)
+        except Exception as e:
+            click.secho(f"Unable to create file for problem {n}: {e}", fg="red")
+
+
+def create_single_file(config: EulerConfig, n: int) -> None:
+    """Creates a solver file for the given problem."""
+
+    dst_path = problem_path(config, n)
+
+    if dst_path.exists() and not click.confirm(
+        f"File {dst_path} already exists; do you want to overwrite?"
+    ):
+        return
+
+    with open(TEMPLATE_FILE, "r") as f:
+        template_contents = f.read()
+
+    output = template_contents.format(description=get_problem_description(n))
+
+    with open(dst_path, "w", encoding="utf-8") as f:
+        f.write(output)
+
+    click.echo(f"Created file for problem {n} at {dst_path}")
+
+
+@click.command
+@click.argument("problems", type=str, nargs=-1, required=True)
+@click.pass_obj
+def run(config: EulerConfig, problems: tuple[str, ...]) -> None:
+    """Run the solver for the given problems and print the answer."""
+
+    numbers = parse_interval_input(problems)
+    if numbers is ProblemAlias.ALL:
+        numbers = set(list_all_problems(config))
+
+    for n in sorted(numbers, key=problem_sort_key):
+        run_single_problem(config, n)
+        click.echo()
+
+
+def run_single_problem(config: EulerConfig, n: ProblemId) -> None:
+    """
+    Runs a single problem, showing its output to the user, and prompting the
+    user to save if the answer is not already saved.
+    """
+
+    click.echo(f"Running problem {format_problem_id(n)}...")
+    answer = run_problem(config, n)
+    click.secho(f"Answer: {answer}", bold=True)
+
+    saved = parse_answer_file(config.answer_path)
+    old_answer = saved.get(n)
+
+    if old_answer is None:
+        click.echo("No previously saved answer")
+    elif old_answer == answer:
+        click.secho("Answer matches previously saved answer", fg="green")
+    else:
+        click.secho(
+            f"WARNING: answer does not match previously saved answer {old_answer}!",
+            fg="red",
+        )
+
+    if old_answer != answer and click.confirm("Would you like to save this answer?"):
+        # Actually write the answer and save it
+        saved[n] = answer
+        save_answer_file(config.answer_path, saved)
+        click.echo("Saved!")
+
+
+@click.command
+@click.argument("problems", type=str, nargs=-1, required=True)
+@click.pass_obj
+def check(config: EulerConfig, problems: tuple[str, ...]) -> None:
+    """
+    Solve all problems and check if the answers match those in the cache.
+    This is nice for checking the validity of any refactoring I'm doing.
+    """
+
+    # Figure out which problems the user specified
+    numbers = parse_interval_input(problems)
+
+    saved_answers: dict[ProblemId, Answer] = parse_answer_file(config.answer_path)
+
+    if numbers is ProblemAlias.ALL:
+        numbers = set(list_all_problems(config)) | saved_answers.keys()
+
+    statuses: dict[CheckStatus, int] = defaultdict(int)
+    for n in sorted(numbers, key=problem_sort_key):
+        status = check_single_problem(config, n, saved_answers.get(n))
+        statuses[status] += 1
+
+    # Decide what color the summary message should show up as
+    if statuses[CheckStatus.FAILURE] > 0:
+        color = "red"
+    elif statuses[CheckStatus.NEEDS_ATTENTION] > 0:
+        color = "yellow"
+    else:
+        color = "green"
+
+    click.secho(
+        f"Ran {len(numbers)} problems: {statuses[CheckStatus.SUCCESS]} succeeded, {statuses[CheckStatus.FAILURE]} failed, {statuses[CheckStatus.UNSOLVED]} unsolved, {statuses[CheckStatus.NEEDS_ATTENTION]} need attention",
+        fg=color,
+    )
+
+
+def check_single_problem(
+    config: EulerConfig, n: ProblemId, saved_answer: Answer | None
+) -> CheckStatus:
+    """
+    Checks the status of a single problem against the saved answer, and returns
+    a `CheckStatus` enum.
+    """
+
+    try:
+        current_answer = run_problem_if_exists(config, n)
+    except Exception as e:
+        # a solver that blows up shouldn't take the rest of the run with it
+        click.secho(
+            f"Problem {format_problem_id(n)} raised {type(e).__name__}: {e}",
+            fg="red",
+            bold=True,
+        )
+        return CheckStatus.FAILURE
+
+    # Big ol' match statement
+    if saved_answer is None:
+        if current_answer is None:
+            click.echo(f"Problem {format_problem_id(n)} is unsolved")
+            return CheckStatus.UNSOLVED
+        else:
+            click.secho(
+                f"Problem {format_problem_id(n)} produces answer {current_answer}, but it is not saved",
+                fg="yellow",
+            )
+            return CheckStatus.NEEDS_ATTENTION
+    else:
+        if current_answer is None:
+            click.secho(
+                f"Problem {format_problem_id(n)} has a saved answer {saved_answer}, but no solver",
+                fg="yellow",
+            )
+            return CheckStatus.NEEDS_ATTENTION
+        elif current_answer == saved_answer:
+            click.secho(f"Problem {format_problem_id(n)} is good!", fg="green")
+            return CheckStatus.SUCCESS
+        else:
+            click.secho(
+                f"Problem {format_problem_id(n)} failed: solver has {current_answer}, save file has {saved_answer}",
+                fg="red",
+                bold=True,
+            )
+            return CheckStatus.FAILURE
+
+
+@click.command
+@click.pass_obj
+def status(config: EulerConfig) -> None:
+    """
+    Check which problems have been done and which are not.
+
+    Helpful for checking if I forgot to save an answer.
+    """
+
+    # Do the regular problems first
+    problems_saved = {
+        id for id in parse_answer_file(config.answer_path) if isinstance(id, int)
+    }
+    problems_with_files = set(list_problems(config))
+
+    click.echo("Problems solved:")
+    click.echo(format_as_intervals(problems_with_files & problems_saved))
+
+    click.echo("Problems downloaded and unsolved:")
+    click.echo(format_as_intervals(problems_with_files - problems_saved))
+
+    if not problems_saved <= problems_with_files:
+        click.echo("Problems solved but not downloaded (???):")
+        click.echo(format_as_intervals(problems_saved - problems_with_files))
+
+    problems_known = problems_with_files | problems_saved
+    first_unknown = max(problems_known) + 1 if problems_known else 1
+    click.echo("Problems remaining:")
+    click.echo(
+        format_as_intervals(
+            set(range(1, first_unknown)) - problems_known, infinite_tail=first_unknown
+        )
+    )
+
+    # The bonus problems don't form intervals, so just list them.
+    bonus_saved = {
+        id for id in parse_answer_file(config.answer_path) if isinstance(id, str)
+    }
+    bonus_with_files = set(list_bonus_problems(config))
+
+    if bonus_with_files or bonus_saved:
+        click.echo("Bonus problems solved:")
+        click.echo(", ".join(sorted(bonus_with_files & bonus_saved)))
+
+        click.echo("Bonus problems downloaded and unsolved:")
+        click.echo(", ".join(sorted(bonus_with_files - bonus_saved)))
+
+
+@click.command
+@click.argument("problem", type=str)
+@click.pass_obj
+def time(config: EulerConfig, problem: str) -> None:
+    """
+    Run the indicated problem several times and give some stats on the timing.
+    """
+
+    id = parse_problem_id(problem)
+
+    run_times = []
+    for i in range(10):
+        # Run the problem
+        start = perf_counter()
+        run_problem(config, id)
+        elapsed = perf_counter() - start
+        run_times.append(elapsed)
+        # Print to reassure the user something's happening
+        click.echo(f"Trial #{i + 1}: {elapsed:.3f}s")
+
+    click.echo("Test complete!")
+    click.echo(f"Mean: {sum(run_times) / len(run_times):.3f}")
+
+
+@click.group()
+def answers() -> None:
+    """
+    Commands for manipulating the answer save file.
+    """
+
+
+@answers.command()
+@click.argument("problems", type=str, nargs=-1, required=True)
+@click.pass_obj
+def show(config: EulerConfig, problems: tuple[str, ...]) -> None:
+    """
+    Show specific answers from the answer list.
+    """
+
+    numbers = parse_interval_input(problems)
+    answers = parse_answer_file(config.answer_path)
+
+    if numbers is ProblemAlias.ALL:
+        numbers = set(answers.keys())
+
+    for n in sorted(numbers, key=problem_sort_key):
+        if n in answers:
+            click.echo(f"Problem {format_problem_id(n)}: {answers[n]}")
+        else:
+            click.secho(
+                f"No saved answer for problem {format_problem_id(n)}", fg="yellow"
+            )
+
+
+@answers.command()
+@click.argument("problems", type=str, nargs=-1, required=True)
+@click.pass_obj
+def delete(config: EulerConfig, problems: tuple[str, ...]) -> None:
+    """Delete a specific answer from the save file."""
+
+    numbers = parse_interval_input(problems)
+    answers = parse_answer_file(config.answer_path)
+
+    if numbers is ProblemAlias.ALL:
+        numbers = set(answers.keys())
+
+    click.confirm(
+        f"Are you sure you want to delete the saved answer for "
+        f"problem(s) {' '.join(problems)}?",
+        abort=True,
+    )
+
+    for problem in sorted(numbers, key=problem_sort_key):
+        if problem in answers:
+            del answers[problem]
+        else:
+            click.secho(
+                f"No saved answer for problem {format_problem_id(problem)}", fg="yellow"
+            )
+
+    save_answer_file(config.answer_path, answers)
+
+
+def make_cli(config: EulerConfig) -> click.Group:
+    """
+    Creates the CLI interface for users of this framework.
+
+    The result is just a regular `click.Group` object, so a) users just need to
+    call the result of this function in order to invoke the CLI, and b) users can
+    register additional commands if they so choose.
+    """
+
+    @click.group()
+    @click.pass_context
+    def cli(ctx: click.Context) -> None:
+        ctx.obj = config
+
+    # Register our commands. We have to do this when we are invoked, not with
+    # the usual decorator, because those functions are defined before the
+    # user has created this `click.Group` object we want to return.
+    cli.add_command(create)
+    cli.add_command(run)
+    cli.add_command(check)
+    cli.add_command(status)
+    cli.add_command(time)
+    cli.add_command(answers)
+
+    return cli

project_youler-0.0.1/src/youler/config.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Union
+
+PathLike = Union[str, Path]
+
+
+@dataclass
+class EulerConfig:
+    """
+    Describes the layout of a repository of Project Euler solutions.
+
+    This is what the user will pass to `make_cli` so that this framework can find
+    the solutions, answer file, etc.
+    """
+
+    # Root of the solution repository. Every relative path below is resolved
+    # against it. Usually `Path(__file__).parents[2]` from the entry point.
+    root: PathLike
+
+    # Package holding the numbered solvers, as an imported module. Solvers are
+    # the files inside it named `pNNNN.py`.
+    problems: ModuleType
+
+    # Package holding the bonus solvers, named `p<id>.py` for a non-numeric id.
+    bonus: ModuleType | None = None
+
+    # Where saved answers live.
+    answer_file: PathLike = "answers.json"
+
+    @property
+    def problems_dir(self) -> Path:
+        """Where the solution modules live."""
+        return _module_dir(self.problems)
+
+    @property
+    def bonus_dir(self) -> Path | None:
+        """Where the bonus solution modules live, if there are any."""
+        if self.bonus is None:
+            return None
+        return _module_dir(self.bonus)
+
+    @property
+    def answer_path(self) -> Path:
+        """Path to the answer file."""
+        return Path(self.root) / self.answer_file
+
+
+class ConfigException(Exception):
+    pass
+
+
+def _module_dir(module: ModuleType) -> Path:
+    """The single directory a package's modules live in."""
+    if len(module.__path__) != 1:
+        raise ConfigException(
+            # not sure what this means or what to do about it
+            f"Multiple paths found for module {module.__name__}"
+        )
+    return Path(module.__path__[0])

project_youler-0.0.1/src/youler/format.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from enum import Enum
+
+from bs4 import BeautifulSoup, NavigableString, PageElement, Tag
+
+IGNORED_EMPHASIS_TAGS = ["var", "i", "b", "a"]
+PREFIX_SYMBOL_TAGS = {"sup": "^", "sub": "_"}
+
+# https://html.spec.whatwg.org/multipage/dom.html#content-models
+
+
+class Mode(Enum):
+    BLOCK = 1
+    INLINE = 2
+    CELL = 3
+
+
+def htmlToDocstring(text: str) -> str:
+    soup = BeautifulSoup(text, "html.parser")
+    return "\n\n".join(
+        block
+        for child in soup.children
+        if (block := format_element(child, Mode.BLOCK)) is not None
+    )
+
+
+def format_elements(elements: Iterable[PageElement], mode: Mode) -> list[str]:
+    return [s for elt in elements if (s := format_element(elt, mode)) is not None]
+
+
+def format_element(element: PageElement, mode: Mode) -> str | None:
+    if isinstance(element, Tag):
+        return format_tag(element, mode)
+    elif isinstance(element, NavigableString):
+        return format_string(element, mode)
+    else:
+        raise Exception(f"Unexpected element: {element}")
+
+
+def format_tag(tag: Tag, mode: Mode) -> str:
+    if tag.name in IGNORED_EMPHASIS_TAGS:
+        return "".join(format_elements(tag.children, mode))
+    if tag.name in PREFIX_SYMBOL_TAGS:
+        return PREFIX_SYMBOL_TAGS[tag.name] + "".join(
+            format_elements(tag.children, mode)
+        )
+    if tag.name == "p":
+        return "".join(format_elements(tag.children, Mode.INLINE))
+    elif tag.name == "div":
+        sep = "\n" if mode == Mode.BLOCK else ""
+        return sep.join(format_elements(tag.children, mode))
+    elif tag.name == "blockquote":
+        text = "".join(format_elements(tag.children, Mode.INLINE))
+        return indent_block(text, 4, False)
+    elif tag.name == "ol":
+        items = format_elements(tag.children, mode)
+        return "\n".join(
+            f"{i + 1}. {indent_block(item, 3, True)}" for (i, item) in enumerate(items)
+        )
+    elif tag.name == "ul":
+        items = format_elements(tag.children, mode)
+        return "\n".join(f"- {indent_block(item, 2, True)}" for item in items)
+    elif tag.name == "li":
+        return "".join(format_elements(tag.children, Mode.INLINE))
+    elif tag.name == "br":
+        return "<br>" if mode == Mode.CELL else "\n"
+    elif tag.name == "table":
+        return "\n".join(format_elements(tag.children, mode))
+    elif tag.name == "tr":
+        return "    ".join(format_elements(tag.children, mode))
+    elif tag.name == "td":
+        return "".join(format_elements(tag.children, Mode.CELL))
+    else:
+        attrs = ",".join(
+            f"{key}={''.join(values)}" for (key, values) in tag.attrs.items()
+        )
+        contents = "".join(format_elements(tag.children, mode))
+        return f"<{tag.name} {attrs}>{contents}</{tag.name}>"
+
+
+def format_string(ns: NavigableString, mode: Mode) -> str | None:
+    text = handle_whitespace(ns, mode)
+    if text is None:
+        return None
+
+    # there's a fair amount of LaTeX notation in these problems; do some
+    # common replacements with Unicode
+    for latex, unicode in LATEX_TO_UNICODE_REPLACEMENTS.items():
+        text = text.replace(latex, unicode)
+
+    # if we have some text between $s, and it's simple enough (the previous
+    # step helps), then we can eliminate the dollar signs.
+    # But also, we gotta watch out for $$, so we do the same thing beforehand,
+    # with $$ as the delimiter.
+    def simplify_math_blocks(src: str, delimiter: str) -> str:
+        out = ""
+        in_math_mode = False
+        for piece in src.split(delimiter):
+            if in_math_mode:
+                # if we're only dealing with safe characters, we can remove the $
+                if all(ch not in "\\{}&" for ch in piece):
+                    out_piece = piece
+                else:
+                    # keep it and manually fix later
+                    out_piece = delimiter + piece + delimiter
+            else:
+                # not in math mode; keep it
+                out_piece = piece
+            out += out_piece
+            in_math_mode = not in_math_mode
+        # we should be out of math mode at the end, but we flipped that flag
+        # one more time at the end, so the next one *would* be math mode
+        assert in_math_mode, "failure to parse math modes"
+        return out
+
+    text = simplify_math_blocks(text, "$$")
+    text = simplify_math_blocks(text, "$")
+    return text
+
+
+def handle_whitespace(ns: NavigableString, mode: Mode) -> str | None:
+    # If we're in a block context, discard leading and trailing space,
+    # and call it a day
+    if mode == Mode.BLOCK:
+        return str(ns).strip() or None
+    elif mode == Mode.INLINE:
+        # https://www.w3.org/TR/css-text-3/#white-space-rules
+        text = str(ns).replace("\t", " ")
+        text = re.sub(" *\n *", " ", text)
+        text = re.sub(" +", " ", text)
+        # Okay, here's a kludge. We want to preserve spaces most of the time,
+        # (e.g., `1<sup>st</sup> thing` should keep the space).
+        # But `1<br />\n2` should drop the newline
+        prev = ns.previous_sibling
+        if isinstance(prev, Tag) and prev.name == "br":
+            text = text.lstrip()
+        next = ns.next_sibling
+        if isinstance(next, Tag) and next.name == "br":
+            text = text.rstrip()
+
+        return text or None
+    elif mode == Mode.CELL:
+        return str(ns).strip().replace("\n", "<br>")
+
+    raise AssertionError()
+
+
+def indent_block(s: str, indent: int, skip_first: bool) -> str:
+    return "\n".join(
+        line if skip_first and i == 0 else " " * indent + line
+        for (i, line) in enumerate(s.splitlines())
+    )
+
+
+LATEX_TO_UNICODE_REPLACEMENTS = {
+    "\\times": "×",
+    "\\le": "≤",
+    "\\ge": "≥",
+    "\\lt": "<",
+    "\\gt": ">",
+    "\\dots": "...",
+    "\\cdots": "...",
+    "\\gcd": "gcd",
+    "\\pm": "±",
+}

project_youler-0.0.1/src/youler/intervals.py

@@ -0,0 +1,81 @@
+import itertools
+from collections.abc import Iterable
+
+
+def intervalize(numbers: Iterable[int]) -> list[tuple[int, int]]:
+    """
+    Given an collection of integers, groups them into contiguous intervals.
+    Intervals are reported with both endpoints inclusive, and single integers are
+    reported as (a, a).
+    """
+    numbers = sorted(numbers)
+
+    if not numbers:
+        return []
+
+    intervals = []
+
+    start = numbers[0]  # start point of current interval
+    for prev, n in itertools.pairwise(numbers):
+        if start is None:
+            start = prev
+
+        if n == prev + 1:
+            continue
+
+        intervals.append((start, prev))
+        start = n
+
+    # Make sure to close the last interval.
+    intervals.append((start, numbers[-1]))
+
+    return intervals
+
+
+def format_as_intervals(
+    numbers: Iterable[int], infinite_tail: int | None = None
+) -> str:
+    """
+    Pretty-prints the collection of numbers by grouping them into intervals and printing
+    the intervals.
+
+    Able to handle certain infinite collections by specifying `infinite_tail=n` (all
+    integers at least n are included in the set.)
+    """
+    intervals = intervalize(numbers)
+
+    # If there's an infinite tail, and it overlaps or is adjacent to any of the intervals,
+    # merge those intervals into the tail.
+    if infinite_tail is not None:
+        while len(intervals) > 0:
+            (start, end) = intervals[-1]
+            # `end+1` so that (5, 10) will merge with infinite_tail=11
+            if infinite_tail <= end + 1:
+                infinite_tail = min(start, infinite_tail)
+                intervals.pop()
+            else:
+                # intervals are in increasing order, so if infinite_tail is
+                # larger than the last interval it's larger than all of them
+                break
+
+    # Stringify things
+    output = [
+        f"{start}-{end}" if start != end else f"{start}" for (start, end) in intervals
+    ]
+
+    if infinite_tail is not None:
+        output.append(f"{infinite_tail}-inf")
+
+    return ", ".join(output)
+
+
+def parse_interval_string(s: str) -> tuple[int, int]:
+    try:
+        x = int(s)
+        return (x, x)
+    except ValueError:
+        pass
+
+    # This ValueError through, we want to throw
+    start, end = s.split("-")
+    return (int(start), int(end))

project_youler-0.0.1/src/youler/problem.py.template

@@ -0,0 +1,7 @@
+"""
+{description}
+"""
+
+
+def solve_problem() -> int:
+    ...

project_youler-0.0.1/src/youler/problems.py

@@ -0,0 +1,98 @@
+from importlib import import_module
+from pathlib import Path
+
+import requests
+
+from .answer import Answer, ProblemId
+from .config import EulerConfig
+from .format import htmlToDocstring
+
+
+def filename(n: int) -> str:
+    return f"p{n:04}"
+
+
+def format_problem_id(id: ProblemId) -> str:
+    """How a problem is named back to the user."""
+    return f"#{id:04}" if isinstance(id, int) else f"bonus-{id}"
+
+
+def problem_path(config: EulerConfig, n: int) -> Path:
+    return config.problems_dir / f"{filename(n)}.py"
+
+
+def module_name(config: EulerConfig, id: ProblemId) -> str:
+    """The importable name of the module solving the given problem."""
+    if isinstance(id, int):
+        return f"{config.problems.__name__}.{filename(id)}"
+
+    if config.bonus is None:
+        raise ValueError("Config did not specify a module for the bonus problems!")
+    return f"{config.bonus.__name__}.p{id}"
+
+
+def run_problem(config: EulerConfig, id: ProblemId) -> Answer:
+    module = import_module(module_name(config, id))
+    answer = module.solve_problem()
+    if not isinstance(answer, Answer):
+        raise TypeError(
+            f"{module.__name__}.solve_problem() returned {answer!r}, "
+            "which is not an int or a str"
+        )
+    return answer
+
+
+def run_problem_if_exists(config: EulerConfig, id: ProblemId) -> Answer | None:
+    # A bonus problem can't exist if the repo never named a package for them.
+    if isinstance(id, str) and config.bonus is None:
+        return None
+
+    try:
+        return run_problem(config, id)
+    except ImportError:
+        return None
+
+
+def get_problem_description(n: int) -> str:
+    """
+    Fetch the project description from the Project Euler website, and apply some light formatting.
+    """
+
+    # TODO error handling (just capture from outside this fn)
+    resp = requests.get(f"https://projecteuler.net/minimal={n}")
+    return htmlToDocstring(resp.text)
+
+
+def list_problems(config: EulerConfig) -> list[int]:
+    """
+    Returns a list of integers for which a solver file exists.
+    """
+
+    problems = []
+    for file in config.problems_dir.glob("p*.py"):
+        try:
+            problems.append(int(file.stem.removeprefix("p")))
+        except ValueError:
+            pass
+
+    return problems
+
+
+def list_bonus_problems(config: EulerConfig) -> list[str]:
+    """
+    Returns the ids of the bonus problems for which a solver file exists.
+    """
+
+    if config.bonus_dir is None:
+        return []
+
+    return [
+        file.stem.removeprefix("p")
+        for file in config.bonus_dir.glob("p*.py")
+        if file.stem != "p"
+    ]
+
+
+def list_all_problems(config: EulerConfig) -> list[ProblemId]:
+    """Every problem, numbered or bonus, that has a solver file."""
+    return [*list_problems(config), *list_bonus_problems(config)]