python-ecd 0.1.1__tar.gz

python_ecd-0.1.1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: python-ecd
+Version: 0.1.1
+Summary: Add your description here
+Author: Pablo Garcia
+Author-email: Pablo Garcia <pablofueros@gmail.com>
+Requires-Dist: everybody-codes-data==0.2
+Requires-Dist: typer>=0.20.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/pablofueros/python-ecd/main/assets/banner.png" alt="python-ecd logo" width="600"/>
+
+---
+
+### **✨ A Python CLI tool for managing Everybody Codes puzzles ✨**
+
+---
+
+</div>
+
+## 📋 Features
+
+- Initialize workspace for [Everybody Codes](https://everybody.codes) puzzles
+- Download puzzle inputs automatically
+- Manage session tokens securely
+- Run solutions with both test and real input data
+- Automatic project structure creation
+
+## 📦 Installation
+
+The package can be installed using [uv](https://docs.astral.sh/uv/#installation), which is recommended for better dependency management and faster installations:
+
+```bash
+# Install it as a system tool
+uv tool install python-ecd
+
+# Otherwise use:
+uvx python-ecd
+```
+
+The tool will be available as both 'python-ecd' and 'ecd'
+
+
+## 💻 Usage
+
+### Initialize a Workspace
+
+Create a new workspace for your puzzles solutions:
+
+It can be done in the current directory:
+
+```bash
+ecd init
+```
+
+Or in a specified path:
+
+```bash
+ecd init everybody-codes-solutions
+```
+
+Note that if the directory does not exist, it will be created.
+
+### Set Session Token
+
+Configure your session token for accessing puzzle inputs:
+
+```bash
+ecd set-token <TOKEN>
+```
+
+Note that is not necessary if you set it during initialization.
+
+### Download Puzzle Input
+
+Get the input for a specific puzzle:
+
+```bash
+ecd get <QUEST_NUMBER> [OPTIONS]
+```
+
+Options:
+- `--year`, `-y`: Event year (default: actual)
+- `--part`, `-p`: Puzzle part (default: 1)
+- `--force`, `-f`: Overwrite existing files
+
+### Run Solutions
+
+Execute your solution for a specific puzzle:
+
+```bash
+ecd run <QUEST_NUMBER> [OPTIONS]
+```
+
+Options:
+- `--year`: Event year (default: actual)
+- `--part`: Part number to execute (default: 1)
+
+### Test Solutions
+
+Run your solution using test data:
+
+```bash
+ecd test <QUEST_NUMBER> [OPTIONS]
+```
+
+Options:
+- `--year`: Event year (default: actual)
+- `--part`: Part number to test (default: 1)
+
+### Display Version
+
+Show the current version of the tool:
+
+```bash
+ecd --version
+```
+
+## ©️ License
+
+[MIT License](LICENSE)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

python_ecd-0.1.1/README.md

@@ -0,0 +1,117 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/pablofueros/python-ecd/main/assets/banner.png" alt="python-ecd logo" width="600"/>
+
+---
+
+### **✨ A Python CLI tool for managing Everybody Codes puzzles ✨**
+
+---
+
+</div>
+
+## 📋 Features
+
+- Initialize workspace for [Everybody Codes](https://everybody.codes) puzzles
+- Download puzzle inputs automatically
+- Manage session tokens securely
+- Run solutions with both test and real input data
+- Automatic project structure creation
+
+## 📦 Installation
+
+The package can be installed using [uv](https://docs.astral.sh/uv/#installation), which is recommended for better dependency management and faster installations:
+
+```bash
+# Install it as a system tool
+uv tool install python-ecd
+
+# Otherwise use:
+uvx python-ecd
+```
+
+The tool will be available as both 'python-ecd' and 'ecd'
+
+
+## 💻 Usage
+
+### Initialize a Workspace
+
+Create a new workspace for your puzzles solutions:
+
+It can be done in the current directory:
+
+```bash
+ecd init
+```
+
+Or in a specified path:
+
+```bash
+ecd init everybody-codes-solutions
+```
+
+Note that if the directory does not exist, it will be created.
+
+### Set Session Token
+
+Configure your session token for accessing puzzle inputs:
+
+```bash
+ecd set-token <TOKEN>
+```
+
+Note that is not necessary if you set it during initialization.
+
+### Download Puzzle Input
+
+Get the input for a specific puzzle:
+
+```bash
+ecd get <QUEST_NUMBER> [OPTIONS]
+```
+
+Options:
+- `--year`, `-y`: Event year (default: actual)
+- `--part`, `-p`: Puzzle part (default: 1)
+- `--force`, `-f`: Overwrite existing files
+
+### Run Solutions
+
+Execute your solution for a specific puzzle:
+
+```bash
+ecd run <QUEST_NUMBER> [OPTIONS]
+```
+
+Options:
+- `--year`: Event year (default: actual)
+- `--part`: Part number to execute (default: 1)
+
+### Test Solutions
+
+Run your solution using test data:
+
+```bash
+ecd test <QUEST_NUMBER> [OPTIONS]
+```
+
+Options:
+- `--year`: Event year (default: actual)
+- `--part`: Part number to test (default: 1)
+
+### Display Version
+
+Show the current version of the tool:
+
+```bash
+ecd --version
+```
+
+## ©️ License
+
+[MIT License](LICENSE)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

python_ecd-0.1.1/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "python-ecd"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+authors = [{ name = "Pablo Garcia", email = "pablofueros@gmail.com" }]
+requires-python = ">=3.13"
+dependencies = ["everybody-codes-data==0.2", "typer>=0.20.0"]
+
+[project.scripts]
+python-ecd = "python_ecd.cli:app"
+ecd = "python_ecd.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ty>=0.0.1a25",
+]

python_ecd-0.1.1/src/python_ecd/cli.py

@@ -0,0 +1,189 @@
+from datetime import datetime
+
+import typer
+
+from . import utils
+from .version import __version__
+
+app = typer.Typer(name="python-ecd", help="python-ecd: CLI tool for Everybody Codes")
+
+
+def _display_version(value: bool) -> None:
+    """Display the version of the application and exit."""
+    if value:
+        typer.echo(f"python-ecd {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        None,
+        "--version",
+        "-v",
+        callback=_display_version,
+        help="Display the version and exit.",
+        is_eager=True,  # Process version before other logic
+    ),
+):
+    pass
+
+
+@app.command("init")
+def init_cmd(
+    path: str = typer.Argument(None, help="Path to initialize the workspace at"),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files"),
+) -> None:
+    """Initialize the workspace for Everybody Codes puzzles."""
+
+    # 0. Parse inputs
+    base_dir_name = "." if path is None else path
+    token = typer.prompt("Session Token", default="", show_default=False)
+
+    # 1. Create base directory
+    base_dir = utils.create_base(base_dir_name)
+    typer.echo(f"📁 Created workspace at: {base_dir}")
+
+    # 2. Initialize git repository
+    git_dir = base_dir / ".git"
+    if not git_dir.exists():
+        utils.create_git(base_dir)
+
+    # 3. Create .gitignore
+    gitignore_path = base_dir / ".gitignore"
+    if gitignore_path.exists() and not force:
+        typer.echo("⚠️ .gitignore already exists (use --force to overwrite).")
+    else:
+        utils.create_gitignore(base_dir)
+        typer.echo("🛑 .gitignore created")
+
+    # 4. Create README.md if requested
+    readme_path = base_dir / "README.md"
+    if readme_path.exists() and not force:
+        typer.echo("⚠️ README.md already exists (use --force to overwrite).")
+    else:
+        utils.create_readme(base_dir, force)
+        typer.echo("📝 README.md created")
+
+    # 5. Save session token if provided
+    token_path = utils.TOKEN_PATH
+    if not token:
+        typer.echo("⚠️ No session token provided (set it later with 'ecd set-token')")
+    elif token_path.exists() and not force:
+        typer.echo("⚠️ Session token file already exists (use --force to overwrite).")
+    else:
+        utils.set_token(token, force)
+        typer.echo(f"🔑 Session token saved to {token_path}")
+
+
+@app.command("set-token")
+def set_token_cmd(
+    token: str = typer.Argument(..., help="Session token to access puzzle inputs"),
+) -> None:
+    """Set the session token to operate with Everybody Codes webpage."""
+    utils.set_token(token)
+    typer.echo("🔑 Session token saved to /home/.config/ecd/token")
+
+
+@app.command("get")
+def get_cmd(
+    quest: int = typer.Argument(..., help="Quest number (e.g. 3)"),
+    year: int = typer.Option(datetime.now().year, "--year", "-y", help="Event year"),
+    part: int = typer.Option(1, "--part", "-p", help="Puzzle part (1, 2, or 3)"),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files"),
+) -> None:
+    """Download input data for a given quest and create local structure."""
+
+    # 0. Locate base directory
+    base_dir = utils.find_base()
+
+    # 1. Ensure session token exists
+    if not utils.get_token():
+        typer.echo(
+            "❌ Error: Session token not found in .env. Use 'ecd set-token' to set it."
+        )
+        raise typer.Exit(1)
+
+    # 2. Download the input for the given part
+    try:
+        input_text = utils.download_input(year, quest, part)
+    except Exception as e:
+        typer.echo(f"❌ Failed to fetch input: {e}")
+        typer.echo("ℹ️ Maybe ")
+        raise typer.Exit(1)
+
+    # 3. Prepare directory structure
+    quest_dir = utils.create_quest_dir(base_dir, year, quest)
+
+    # 4. Create solution.py if missing
+    solution_file = quest_dir / "solution.py"
+    if solution_file.exists() and not force:
+        typer.echo("⚠️ solution.py already exists (use --force to overwrite).")
+    else:
+        utils.create_solution(quest_dir, force)
+        typer.echo("🧩 Created solution.py")
+
+    # 5. Save input
+    input_file = quest_dir / f"input/input_p{part}.txt"
+    if input_file.exists() and not force:
+        typer.echo("⚠️ Input file already exists (use --force to overwrite).")
+    else:
+        input_file.write_text(input_text, encoding="utf-8")
+        typer.echo(f"📥 Saved input for quest {quest:02d} part {part}.")
+
+    # 6. Ensure empty test file exists
+    test_file = quest_dir / f"test/test_p{part}.txt"
+    if test_file.exists() and not force:
+        typer.echo("⚠️ Test file already exists (use --force to overwrite).")
+    else:
+        test_file.touch(exist_ok=True)
+
+    typer.echo(
+        f"✅ Quest {quest:02d} (Part {part}) ready at {solution_file.relative_to(base_dir)}"
+    )
+
+
+@app.command("run")
+def run_cmd(
+    quest: int = typer.Argument(..., help="Quest number (e.g. 3)"),
+    year: int = typer.Option(datetime.now().year, "--year", "-y", help="Event year"),
+    part: int = typer.Option(1, "--part", "-p", help="Part number to execute"),
+) -> None:
+    """Execute the solution for a given quest and part using input data."""
+
+    # 0. Locate base directory
+    base_dir = utils.find_base()
+
+    # 1. Execute the solution
+    try:
+        result = utils.execute_part(base_dir, quest, year, part, mode="input")
+    except Exception as e:
+        typer.echo(f"❌ Failed to execute Quest {quest} Part {part}: {e}")
+        raise typer.Exit(1)
+
+    typer.echo(f"✅ Result for Quest {quest} Part {part}:\n{result}")
+
+
+@app.command("test")
+def test_cmd(
+    quest: int = typer.Argument(..., help="Quest number (e.g. 3)"),
+    year: int = typer.Option(datetime.now().year, "--year", "-y", help="Event year"),
+    part: int = typer.Option(1, "--part", "-p", help="Part number to test"),
+) -> None:
+    """Run the solution for a given quest and part using test data."""
+
+    # 0. Locate base directory
+    base_dir = utils.find_base()
+
+    # 1. Execute the solution in test mode
+    try:
+        result = utils.execute_part(base_dir, quest, year, part, mode="test")
+    except Exception as e:
+        typer.echo(f"❌ Failed to run test for Quest {quest} Part {part}: {e}")
+        raise typer.Exit(1)
+
+    typer.echo(f"🧪 Test result for Quest {quest} Part {part}:\n{result}")
+
+
+if __name__ == "__main__":
+    app()

python_ecd-0.1.1/src/python_ecd/templates/.gitignore.tpl

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

python_ecd-0.1.1/src/python_ecd/templates/README.md.tpl

@@ -0,0 +1,40 @@
+# 🧩 Everybody Codes Solutions
+
+My solutions to the [Everybody Codes](https://everybody.codes/) puzzles (managed by the [python-ecd](https://github.com/pablofueros/python-ecd) library).
+
+---
+
+## 📂 Project Structure
+
+Each quest is stored under `events/<year>/quest_<id>/` and contains:
+
+| File / Folder | Description |
+|----------------|-------------|
+| `solution.py` | Your Python solution with `part_1`, `part_2`, and `part_3` functions. |
+| `input/` | Puzzle inputs (`input_p1.txt`, `input_p2.txt`, …) fetched automatically. |
+| `test/` | Optional test files (`test_p1.txt`, …) for local validation. |
+
+---
+
+## ✅ Completed Quests
+
+| Year | Quest | Part 1 | Part 2 | Part 3 |
+|------|--------|--------|--------|--------|
+| yyyy | n | ✅ | ⬜ | ⬜ |
+
+---
+
+## 🚀 Usage
+
+```bash
+# Initialize your workspace
+ecd init
+
+# Fetch a puzzle input ()
+ecd get 3  # Quest 3 of the current year
+
+# Run your test cases
+ecd test 3 --part 1
+
+# Execute your actual input
+ecd run 3 --part 1

python_ecd-0.1.1/src/python_ecd/templates/solution.py.tpl

@@ -0,0 +1,18 @@
+def part_1(data: str) -> str:
+    return ""
+
+
+def part_2(data: str) -> str:
+    return ""
+
+
+def part_3(data: str) -> str:
+    return ""
+
+
+def main() -> None:
+    pass  # debugging
+
+
+if __name__ == "__main__":
+    main()

python_ecd-0.1.1/src/python_ecd/utils.py

@@ -0,0 +1,178 @@
+import contextlib
+import importlib.util
+import io
+import subprocess
+from pathlib import Path
+
+from ecd import get_inputs
+
+
+def _read_template(template_name: str) -> str:
+    """
+    Read a template file from the templates directory.
+    """
+    templates_dir = Path(__file__).parent / "templates"
+    template_path = templates_dir / template_name
+    text = template_path.read_text(encoding="utf-8")
+    return text
+
+
+def create_base(base_dir_name: str) -> Path:
+    """
+    Create the base directory for the project, including subfolders.
+    """
+    base_dir = Path(base_dir_name).resolve()
+    (base_dir / "events").mkdir(parents=True, exist_ok=True)
+    return base_dir
+
+
+def find_base() -> Path:
+    """
+    Locate the base directory by searching upwards from the current directory.
+    """
+    current_dir = Path.cwd()
+    for parent in [current_dir] + list(current_dir.parents):
+        if (parent / "events").exists():
+            return parent
+    raise FileNotFoundError("Base directory not found. Please run 'ecd init'.")
+
+
+def create_quest_dir(base_dir: Path, year: int, quest: int) -> Path:
+    """
+    Create directory structure for a given quest/year.
+    """
+    quest_dir = base_dir / "events" / str(year) / f"quest_{quest:02d}"
+    quest_dir.mkdir(parents=True, exist_ok=True)
+    (quest_dir / "input").mkdir(exist_ok=True)
+    (quest_dir / "test").mkdir(exist_ok=True)
+    return quest_dir
+
+
+def create_readme(base_dir: Path, force: bool) -> None:
+    """
+    Create a simple README.md in the base directory.
+    """
+    readme_path = base_dir / "README.md"
+    if not readme_path.exists() or force:
+        content = _read_template("README.md.tpl")
+        readme_path.write_text(content, encoding="utf-8")
+
+
+def create_git(base_dir: Path) -> None:
+    """
+    Initialize a git repository in the base directory.
+    """
+    git_dir = base_dir / ".git"
+    if git_dir.exists():
+        return  # Git already initialized
+    subprocess.run(
+        ["git", "init"],
+        cwd=str(base_dir),
+        check=True,
+        stdout=subprocess.DEVNULL,
+    )
+
+
+def create_gitignore(base_dir: Path) -> None:
+    gitignore_path = base_dir / ".gitignore"
+    if not gitignore_path.exists():
+        content = _read_template(".gitignore.tpl")
+        gitignore_path.write_text(content, encoding="utf-8")
+
+
+def create_solution(quest_dir: Path, force: bool) -> None:
+    """
+    Create a solution.py file in the quest directory.
+    """
+    solution_path = quest_dir / "solution.py"
+    if not solution_path.exists() or force:
+        content = _read_template("solution.py.tpl")
+        solution_path.write_text(content, encoding="utf-8")
+
+
+TOKEN_PATH = Path.home() / ".config" / "ecd" / "token"
+
+
+def set_token(token: str, force: bool = False) -> None:
+    """Create ~/.config/ecd/token with the given token."""
+    config_dir = TOKEN_PATH.parent
+    config_dir.mkdir(parents=True, exist_ok=True)
+    TOKEN_PATH.write_text(token.strip())
+
+
+def get_token() -> str | None:
+    """Read the token if it exists, else return None."""
+    if not TOKEN_PATH.exists():
+        return None
+    return TOKEN_PATH.read_text().strip()
+
+
+def download_input(year: int, quest: int, part: int) -> str:
+    """
+    Fetch the input text for a specific quest and part.
+    Raises if part not available.
+    """
+
+    with contextlib.redirect_stderr(io.StringIO()):
+        data = get_inputs(quest=quest, event=year)
+
+    key = str(part)
+    if key not in data:
+        raise ValueError(f"Part {part} not unlocked or not available.")
+
+    return data[key]
+
+
+def execute_part(
+    base_dir: Path,
+    quest: int,
+    year: int,
+    part: int,
+    mode: str = "input",
+) -> str:
+    """
+    Execute a given part of a quest solution with either input or test data.
+
+    Args:
+        base_dir: Base directory
+        part: Part number (1, 2, or 3)
+        mode: Either "input" or "test"
+
+    Returns:
+        The string result produced by part_{part}(data).
+    """
+
+    quest_dir = base_dir / "events" / str(year) / f"quest_{quest:02d}"
+    solution_path = quest_dir / "solution.py"
+    data_path = quest_dir / mode / f"{mode}_p{part}.txt"
+
+    if not solution_path.exists():
+        raise FileNotFoundError(
+            f"Missing solution file: {solution_path.relative_to(base_dir)}"
+        )
+    if not data_path.exists():
+        raise FileNotFoundError(f"Missing data file: {data_path.relative_to(base_dir)}")
+
+    # Load data
+    data = data_path.read_text(encoding="utf-8")
+
+    # Dynamic import
+    spec = importlib.util.spec_from_file_location("solution", solution_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(
+            f"Could not load module from {solution_path.relative_to(base_dir)}"
+        )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    func_name = f"part_{part}"
+    func = getattr(module, func_name, None)
+    if not callable(func):
+        raise AttributeError(f"No function '{func_name}' defined in solution.py")
+
+    # Run the function
+    result = func(data)
+    if result is None:
+        raise ValueError(f"{func_name} returned None.")
+
+    return str(result)

python_ecd-0.1.1/src/python_ecd/version.py

@@ -0,0 +1,3 @@
+import importlib.metadata as metadata
+
+__version__ = metadata.version("python-ecd")