spawnio 1.0.5__py3-none-any.whl

spawn/templates/data_project/__init__.py

@@ -0,0 +1,125 @@
+from pathlib import Path
+
+from spawn.templates.base import BaseTemplate
+from spawn.templates.data_project.analysis import DataAnalysisTemplate
+from spawn.templates.data_project.dashboard import DashboardTemplate
+from spawn.templates.data_project.etl import ETLPipelineTemplate
+from spawn.templates.data_project.ml import MLProjectTemplate
+
+_SUBTEMPLATE_MAP = {
+    "Data Analysis":    DataAnalysisTemplate,
+    "Dashboard":        DashboardTemplate,
+    "ETL Pipeline":     ETLPipelineTemplate,
+    "Machine Learning": MLProjectTemplate,
+}
+
+_GITIGNORE_RULES: dict[str, str] = {
+    "Data Analysis": (
+        "\n# Data Analysis artifacts\n"
+        "data/*.csv\n"
+        "!data/sample.csv\n"
+        "reports/*.png\n"
+        "notebooks/.ipynb_checkpoints/\n"
+    ),
+    "Dashboard": (
+        "\n# Dashboard artifacts\n"
+        "data/*.csv\n"
+        "!data/sample.csv\n"
+    ),
+    "ETL Pipeline": (
+        "\n# ETL artifacts\n"
+        "data/cleaned.csv\n"
+    ),
+    "Machine Learning": (
+        "\n# ML artifacts\n"
+        "models/*.joblib\n"
+        "experiments/*.json\n"
+        "data/*.csv\n"
+        "!data/dataset.csv\n"
+    ),
+}
+
+
+class _DataProjectPostInstallMixin:
+    """
+    Shared post_install logic for all Data Project subtemplates.
+
+    Subtemplates must set:
+      - self.extras (list[str])
+      - self.data_type (str)
+    and import their own CI constants from their content module.
+    """
+
+    # Subtemplates override these with their own imported constants.
+    _CI_BASE: str = ""
+    _CI_RUFF_STEP: str = ""
+    _CI_PYTEST_STEP: str = ""
+
+    def post_install(self, project_path: Path) -> None:
+        # ── pyproject.toml extras ─────────────────────────────────────────
+        needs_pyproject = any(e in self.extras for e in ("pytest", "ruff"))
+        if needs_pyproject:
+            pyproject = project_path / "pyproject.toml"
+            current = pyproject.read_text(encoding="utf-8")
+            additions = ""
+            if "pytest" in self.extras:
+                additions += '\n[tool.pytest.ini_options]\ntestpaths = ["tests"]\n'
+            if "ruff" in self.extras:
+                additions += "\n[tool.ruff]\nline-length = 88\n"
+            if additions:
+                pyproject.write_text(current + additions, encoding="utf-8")
+
+        # ── GitHub Actions ────────────────────────────────────────────────
+        if "github-actions" in self.extras and self._CI_BASE:
+            workflows_path = project_path / ".github" / "workflows"
+            workflows_path.mkdir(parents=True, exist_ok=True)
+            ci = self._CI_BASE
+            if "ruff" in self.extras:
+                ci += self._CI_RUFF_STEP
+            if "pytest" in self.extras:
+                ci += self._CI_PYTEST_STEP
+            (workflows_path / "ci.yml").write_text(ci, encoding="utf-8")
+
+        # ── Data-artifact gitignore rules ─────────────────────────────────
+        gitignore_path = project_path / ".gitignore"
+        current_gitignore = gitignore_path.read_text(encoding="utf-8")
+        rule = _GITIGNORE_RULES.get(self.data_type, "")
+        if rule and rule.strip() not in current_gitignore:
+            gitignore_path.write_text(current_gitignore + rule, encoding="utf-8")
+
+
+class DataProjectTemplate(BaseTemplate):
+    """
+    Dispatcher that returns the appropriate per-data_type subtemplate.
+    Uses __new__ so the returned object IS the subtemplate.
+    """
+
+    def __new__(
+        cls,
+        data_type: str = "Data Analysis",
+        extras: list[str] | None = None,
+    ) -> BaseTemplate:  # type: ignore[misc]
+        klass = _SUBTEMPLATE_MAP.get(data_type)
+        if klass is not None:
+            return klass(extras=extras)
+        instance = super().__new__(cls)
+        return instance
+
+    def __init__(
+        self,
+        data_type: str = "Data Analysis",
+        extras: list[str] | None = None,
+    ) -> None:
+        if isinstance(self, tuple(_SUBTEMPLATE_MAP.values())):
+            return
+        self.data_type = data_type
+        self.extras = extras or []
+        super().__init__(
+            name="Data Project",
+            folders=[],
+            starter_files=[],
+            next_steps=["cd {project_name}"],
+        )
+
+    def get_dependencies(self) -> list[str]:
+        return []

spawn/templates/data_project/analysis/__init__.py

@@ -0,0 +1,74 @@
+from pathlib import Path
+
+from spawn.templates.base import BaseTemplate
+from spawn.templates.data_project.analysis.content import (
+    SAMPLE_CSV,
+    NOTEBOOK_CONTENT,
+    TEST_CONTENT,
+    make_readme,
+    GITHUB_ACTIONS_CI_BASE,
+    GITHUB_ACTIONS_CI_RUFF_STEP,
+    GITHUB_ACTIONS_CI_PYTEST_STEP,
+)
+
+FOLDERS = ["data", "notebooks", "reports", "src", "tests"]
+
+FILES = [
+    ("data/sample.csv",           SAMPLE_CSV),
+    ("notebooks/analysis.ipynb",  NOTEBOOK_CONTENT),
+    ("tests/test_analysis.py",    TEST_CONTENT),
+    ("tests/__init__.py",         ""),
+    ("reports/.gitkeep",          ""),
+    ("src/__init__.py",           ""),
+]
+
+DEPENDENCIES = ["pandas", "numpy", "jupyter", "matplotlib"]
+
+NEXT_STEPS = [
+    "cd {project_name}",
+    "uv run jupyter notebook",
+]
+
+
+class DataAnalysisTemplate(BaseTemplate):
+    data_type = "Data Analysis"
+    _CI_BASE = GITHUB_ACTIONS_CI_BASE
+    _CI_RUFF_STEP = GITHUB_ACTIONS_CI_RUFF_STEP
+    _CI_PYTEST_STEP = GITHUB_ACTIONS_CI_PYTEST_STEP
+
+    def __init__(self, extras: list[str] | None = None) -> None:
+        self.extras = extras or []
+        super().__init__(
+            name="Data Project",
+            folders=list(FOLDERS),
+            starter_files=list(FILES),
+            next_steps=list(NEXT_STEPS),
+        )
+
+    def get_readme_content(self, context: dict) -> str | None:
+        return make_readme().format_map(context)
+
+    def get_dependencies(self) -> list[str]:
+        base = list(DEPENDENCIES)
+        if "pytest" in self.extras:
+            base.append("pytest")
+        if "ruff" in self.extras:
+            base.append("ruff")
+        return base
+
+    def generate(self, project_path: Path, context: dict) -> None:
+        """Write files, skipping format_map for .ipynb (raw JSON)."""
+        for folder in self.folders:
+            (project_path / folder).mkdir(parents=True, exist_ok=True)
+
+        for relative_path, content in self.starter_files:
+            file_path = project_path / relative_path
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            if relative_path.endswith(".ipynb"):
+                file_path.write_text(content, encoding="utf-8")
+            else:
+                file_path.write_text(content.format_map(context), encoding="utf-8")
+
+    def post_install(self, project_path: Path) -> None:
+        from spawn.templates.data_project import _DataProjectPostInstallMixin
+        _DataProjectPostInstallMixin.post_install(self, project_path)  # type: ignore[arg-type]

spawn/templates/data_project/analysis/content.py

@@ -0,0 +1,190 @@
+import json
+
+SAMPLE_CSV = """\
+date,category,value
+2024-01-05,Electronics,1200
+2024-01-12,Clothing,430
+2024-01-18,Electronics,980
+2024-01-25,Food,210
+2024-02-03,Clothing,560
+2024-02-10,Electronics,1450
+2024-02-14,Food,330
+2024-02-22,Clothing,390
+2024-03-01,Electronics,1100
+2024-03-08,Food,270
+2024-03-15,Clothing,620
+2024-03-21,Electronics,870
+2024-03-28,Food,190
+2024-04-04,Clothing,710
+2024-04-11,Electronics,1340
+2024-04-18,Food,250
+2024-04-25,Clothing,480
+"""
+
+NOTEBOOK_CONTENT = json.dumps(
+    {
+        "nbformat": 4,
+        "nbformat_minor": 5,
+        "metadata": {
+            "kernelspec": {
+                "display_name": "Python 3",
+                "language": "python",
+                "name": "python3",
+            },
+            "language_info": {"name": "python", "version": "3.12.0"},
+        },
+        "cells": [
+            {
+                "cell_type": "code",
+                "execution_count": None,
+                "metadata": {},
+                "outputs": [],
+                "source": [
+                    "import pandas as pd\n",
+                    "import matplotlib.pyplot as plt\n",
+                    "\n",
+                    'df = pd.read_csv("data/sample.csv", parse_dates=["date"])\n',
+                    "df.head()",
+                ],
+            },
+            {
+                "cell_type": "code",
+                "execution_count": None,
+                "metadata": {},
+                "outputs": [],
+                "source": [
+                    "print(df.describe())\n",
+                    "print()\n",
+                    'summary = df.groupby("category")["value"].sum().reset_index()\n',
+                    "print(summary)",
+                ],
+            },
+            {
+                "cell_type": "code",
+                "execution_count": None,
+                "metadata": {},
+                "outputs": [],
+                "source": [
+                    "import os\n",
+                    'os.makedirs("reports", exist_ok=True)\n',
+                    "\n",
+                    "fig, ax = plt.subplots(figsize=(8, 5))\n",
+                    'ax.bar(summary["category"], summary["value"], color="steelblue")\n',
+                    'ax.set_title("Total Value by Category")\n',
+                    'ax.set_xlabel("Category")\n',
+                    'ax.set_ylabel("Total Value")\n',
+                    "plt.tight_layout()\n",
+                    'plt.savefig("reports/summary.png", dpi=150)\n',
+                    "plt.show()\n",
+                    'print("Chart saved to reports/summary.png")',
+                ],
+            },
+            {
+                "cell_type": "markdown",
+                "metadata": {},
+                "source": [
+                    "## Insights\n",
+                    "\n",
+                    "_Fill in your observations here after reviewing the chart above._",
+                ],
+            },
+        ],
+    },
+    indent=2,
+)
+
+TEST_CONTENT = """\
+import os
+from pathlib import Path
+
+
+def test_sample_csv_exists_and_nonempty():
+    import pandas as pd
+
+    df = pd.read_csv("data/sample.csv")
+    assert len(df) > 0, "data/sample.csv is empty"
+    assert "category" in df.columns
+    assert "value" in df.columns
+
+
+def test_reports_directory_exists():
+    reports_path = Path("reports")
+    assert reports_path.exists(), (
+        "reports/ directory missing — run the notebook first to generate it"
+    )
+"""
+
+
+def make_readme() -> str:
+    return (
+        "# {project_name}\n\n"
+        "A Data Analysis project generated with Spawn using pandas, matplotlib, and Jupyter.\n\n"
+        "## Getting Started\n\n"
+        "1. Install dependencies:\n\n"
+        "```bash\n"
+        "uv sync\n"
+        "```\n\n"
+        "2. Launch the notebook:\n\n"
+        "```bash\n"
+        "uv run jupyter notebook\n"
+        "```\n\n"
+        "3. Open `notebooks/analysis.ipynb` and run all cells.\n"
+        "   A bar chart is saved to `reports/summary.png` automatically.\n\n"
+        "## Example\n\n"
+        "```\n"
+        "$ uv run jupyter notebook\n"
+        "# Open notebooks/analysis.ipynb\n"
+        "# Run all cells → reports/summary.png is generated\n"
+        "```\n\n"
+        "## Project Structure\n\n"
+        "```\n"
+        "{project_name}/\n"
+        "├── data/\n"
+        "│   └── sample.csv          # Sample sales data\n"
+        "├── notebooks/\n"
+        "│   └── analysis.ipynb      # Main analysis notebook\n"
+        "├── reports/                # Generated charts and outputs\n"
+        "├── src/\n"
+        "├── tests/\n"
+        "│   └── test_analysis.py\n"
+        "└── README.md\n"
+        "```\n\n"
+        "## Running Tests\n\n"
+        "```bash\n"
+        "uv run pytest\n"
+        "```\n"
+    )
+
+# ─── GitHub Actions ───────────────────────────────────────────────────────
+
+GITHUB_ACTIONS_CI_BASE = """\
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync
+"""
+
+GITHUB_ACTIONS_CI_RUFF_STEP = """\
+      - name: Lint
+        run: uv run ruff check .
+"""
+
+GITHUB_ACTIONS_CI_PYTEST_STEP = """\
+      - name: Test
+        run: uv run pytest
+"""

spawn/templates/data_project/dashboard/__init__.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+
+from spawn.templates.base import BaseTemplate
+from spawn.templates.data_project.dashboard.content import (
+    DASHBOARD_SAMPLE_CSV,
+    DASHBOARD_APP_CONTENT,
+    DASHBOARD_TEST_CONTENT,
+    make_readme,
+    GITHUB_ACTIONS_CI_BASE,
+    GITHUB_ACTIONS_CI_RUFF_STEP,
+    GITHUB_ACTIONS_CI_PYTEST_STEP,
+)
+
+FOLDERS = ["data", "dashboard", "src", "tests"]
+
+FILES = [
+    ("data/sample.csv",           DASHBOARD_SAMPLE_CSV),
+    ("dashboard/__init__.py",     ""),
+    ("dashboard/app.py",          DASHBOARD_APP_CONTENT),
+    ("tests/test_dashboard.py",   DASHBOARD_TEST_CONTENT),
+    ("tests/__init__.py",         ""),
+    ("src/__init__.py",           ""),
+]
+
+DEPENDENCIES = ["streamlit", "pandas", "plotly"]
+
+NEXT_STEPS = [
+    "cd {project_name}",
+    "uv run streamlit run dashboard/app.py",
+]
+
+
+class DashboardTemplate(BaseTemplate):
+    data_type = "Dashboard"
+    _CI_BASE = GITHUB_ACTIONS_CI_BASE
+    _CI_RUFF_STEP = GITHUB_ACTIONS_CI_RUFF_STEP
+    _CI_PYTEST_STEP = GITHUB_ACTIONS_CI_PYTEST_STEP
+
+    def __init__(self, extras: list[str] | None = None) -> None:
+        self.extras = extras or []
+        super().__init__(
+            name="Data Project",
+            folders=list(FOLDERS),
+            starter_files=list(FILES),
+            next_steps=list(NEXT_STEPS),
+        )
+
+    def get_readme_content(self, context: dict) -> str | None:
+        return make_readme().format_map(context)
+
+    def get_dependencies(self) -> list[str]:
+        base = list(DEPENDENCIES)
+        if "pytest" in self.extras:
+            base.append("pytest")
+        if "ruff" in self.extras:
+            base.append("ruff")
+        return base
+
+    def post_install(self, project_path: Path) -> None:
+        from spawn.templates.data_project import _DataProjectPostInstallMixin
+        _DataProjectPostInstallMixin.post_install(self, project_path)  # type: ignore[arg-type]

spawn/templates/data_project/dashboard/content.py

@@ -0,0 +1,135 @@
+from spawn.templates.data_project.analysis.content import SAMPLE_CSV
+
+# Reuse the same sample dataset — date/category/value fits both use cases
+DASHBOARD_SAMPLE_CSV = SAMPLE_CSV
+
+DASHBOARD_APP_CONTENT = """\
+import pandas as pd
+import plotly.express as px
+import streamlit as st
+
+df = pd.read_csv("data/sample.csv", parse_dates=["date"])
+
+st.title("{project_name} Dashboard")
+
+# ── Sidebar filters ───────────────────────────────────────────────────────
+st.sidebar.header("Filters")
+all_categories = sorted(df["category"].unique().tolist())
+selected_categories = st.sidebar.multiselect(
+    "Category",
+    options=all_categories,
+    default=all_categories,
+)
+
+filtered = df[df["category"].isin(selected_categories)]
+
+# ── Raw data ──────────────────────────────────────────────────────────────
+st.subheader("Raw Data")
+st.dataframe(filtered, width="stretch")
+
+# ── Chart ─────────────────────────────────────────────────────────────────
+st.subheader("Total Value by Category")
+summary = filtered.groupby("category")["value"].sum().reset_index()
+fig = px.bar(
+    summary,
+    x="category",
+    y="value",
+    color="category",
+    title="Total Value by Category",
+    labels={{"category": "Category", "value": "Total Value"}},
+)
+st.plotly_chart(fig, width="stretch")
+"""
+
+DASHBOARD_TEST_CONTENT = """\
+def test_sample_csv_loads_with_expected_columns():
+    import pandas as pd
+
+    df = pd.read_csv("data/sample.csv")
+    assert len(df) > 0, "data/sample.csv is empty"
+    assert "date" in df.columns
+    assert "category" in df.columns
+    assert "value" in df.columns
+
+
+def test_dashboard_app_exists():
+    from pathlib import Path
+
+    assert Path("dashboard/app.py").exists(), "dashboard/app.py is missing"
+"""
+
+
+def make_readme() -> str:
+    return (
+        "# {project_name}\n\n"
+        "An interactive Dashboard generated with Spawn using Streamlit and Plotly.\n\n"
+        "## Getting Started\n\n"
+        "1. Install dependencies:\n\n"
+        "```bash\n"
+        "uv sync\n"
+        "```\n\n"
+        "2. Launch the dashboard:\n\n"
+        "```bash\n"
+        "uv run streamlit run dashboard/app.py\n"
+        "```\n\n"
+        "3. Open the URL shown in the terminal (usually http://localhost:8501).\n\n"
+        "## Example\n\n"
+        "```\n"
+        "$ uv run streamlit run dashboard/app.py\n"
+        "  Local URL: http://localhost:8501\n"
+        "# Use the sidebar to filter by category\n"
+        "```\n\n"
+        "## Adding Data\n\n"
+        "Replace `data/sample.csv` with your own CSV that has `date`, `category`,\n"
+        "and `value` columns (or update `dashboard/app.py` to match your schema).\n\n"
+        "## Project Structure\n\n"
+        "```\n"
+        "{project_name}/\n"
+        "├── data/\n"
+        "│   └── sample.csv          # Sample sales data\n"
+        "├── dashboard/\n"
+        "│   └── app.py              # Streamlit application\n"
+        "├── src/\n"
+        "├── tests/\n"
+        "│   └── test_dashboard.py\n"
+        "└── README.md\n"
+        "```\n\n"
+        "## Running Tests\n\n"
+        "```bash\n"
+        "uv run pytest\n"
+        "```\n"
+    )
+
+# ─── GitHub Actions ───────────────────────────────────────────────────────
+
+GITHUB_ACTIONS_CI_BASE = """\
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync
+"""
+
+GITHUB_ACTIONS_CI_RUFF_STEP = """\
+      - name: Lint
+        run: uv run ruff check .
+"""
+
+GITHUB_ACTIONS_CI_PYTEST_STEP = """\
+      - name: Test
+        run: uv run pytest
+"""

spawn/templates/data_project/etl/__init__.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+
+from spawn.templates.base import BaseTemplate
+from spawn.templates.data_project.etl.content import (
+    ETL_RAW_CSV,
+    ETL_CLEAN_CONTENT,
+    ETL_RUN_CONTENT,
+    ETL_ENV_CONTENT,
+    ETL_TEST_CONTENT,
+    make_readme,
+    GITHUB_ACTIONS_CI_BASE,
+    GITHUB_ACTIONS_CI_RUFF_STEP,
+    GITHUB_ACTIONS_CI_PYTEST_STEP,
+)
+
+FOLDERS = ["data", "pipelines", "src", "tests"]
+
+FILES = [
+    ("data/raw.csv",               ETL_RAW_CSV),
+    ("pipelines/__init__.py",      ""),
+    ("pipelines/clean_data.py",    ETL_CLEAN_CONTENT),
+    ("pipelines/run.py",           ETL_RUN_CONTENT),
+    ("tests/test_etl.py",          ETL_TEST_CONTENT),
+    ("tests/__init__.py",          ""),
+    ("src/__init__.py",            ""),
+    (".env.example",               ETL_ENV_CONTENT),
+]
+
+DEPENDENCIES = ["pandas", "python-dotenv"]
+
+NEXT_STEPS = [
+    "cd {project_name}",
+    "Rename .env.example to .env if you want custom paths",
+    "uv run python -m pipelines.run",
+]
+
+
+class ETLPipelineTemplate(BaseTemplate):
+    data_type = "ETL Pipeline"
+    _CI_BASE = GITHUB_ACTIONS_CI_BASE
+    _CI_RUFF_STEP = GITHUB_ACTIONS_CI_RUFF_STEP
+    _CI_PYTEST_STEP = GITHUB_ACTIONS_CI_PYTEST_STEP
+
+    def __init__(self, extras: list[str] | None = None) -> None:
+        self.extras = extras or []
+        super().__init__(
+            name="Data Project",
+            folders=list(FOLDERS),
+            starter_files=list(FILES),
+            next_steps=list(NEXT_STEPS),
+        )
+
+    def get_readme_content(self, context: dict) -> str | None:
+        return make_readme().format_map(context)
+
+    def get_dependencies(self) -> list[str]:
+        base = list(DEPENDENCIES)
+        if "pytest" in self.extras:
+            base.append("pytest")
+        if "ruff" in self.extras:
+            base.append("ruff")
+        return base
+
+    def post_install(self, project_path: Path) -> None:
+        from spawn.templates.data_project import _DataProjectPostInstallMixin
+        _DataProjectPostInstallMixin.post_install(self, project_path)  # type: ignore[arg-type]