stooge 0.1.0__tar.gz

stooge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Derrick Chambers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

stooge-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: stooge
+Version: 0.1.0
+Summary: A simple project framework to keep you from getting burned
+Author-email: Derrick Chambers <chambers.ja.derrick@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2023 Derrick Chambers
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        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 OR COPYRIGHT HOLDERS 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.
+        
+Project-URL: Bug Tracker, https://github.com/d-chambers/port/issues
+Project-URL: Documentation, https://github.com/d-chambers/port
+Project-URL: Homepage, https://github.com/d-chambers/port
+Keywords: workflow,projects
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: jinja2
+Requires-Dist: toml
+Requires-Dist: pdbpp>=0.12.0.post1
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pre-commit; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Requires-Dist: scikit-learn; extra == "test"
+Provides-Extra: dev
+Requires-Dist: stooge[test]; extra == "dev"
+Dynamic: license-file
+
+# port
+
+A simple project framework.
+
+`port` facilitates rapid, reproducible development for local research projects.
+
+## Project structure
+
+port requires a specific project structure.
+
+An example project directory looks like this:
+
+my_project
+-> inputs/
+---> some_file.csv
+-> outputs/
+-> local.py
+-> environment.yml
+-> a010_clean_data.py
+-> a020_calculate.py
+-> a030_visualize.py
+
+Each script has an ID (the part of the name before the first `_`).
+
+The file called `local.py` defines the inputs and outputs of the scripts. In this file, outputs are also given the same prefix.
+
+For example:
+
+```python
+from pathlib import Path
+
+input_path = Path("inputs")
+output_path = Path("outputs")
+
+raw_data_path = input_path / "raw data.csv"
+
+a010_clean_data_path = output_path / "a010_cleaned_outputs.csv"
+a020_calculated_data_path = output_path / "a020_calculated_results.csv"
+a030_result_plot = output_path / "a030_result_plot.png"
+```
+
+This provides port with all the required information to figure out the relationships between scripts and their outputs.
+
+## Init
+Creates a port project skeleton.
+
+This provides a small Rich interface to get information about the project name and backend, or they can be provided via command-line flags.
+
+Supported backends are:
+- [uv](https://docs.astral.sh/uv/)
+- [miniforge](https://github.com/conda-forge/miniforge)
+- [marimo](https://marimo.io/)
+- python (use system python or provided interpreter path)
+
+```bash
+port init test_project --backend uv
+```
+
+## Run
+
+`port run` runs the entire project up to and including a target ID. It automatically calculates stale or missing results that `a030` depends on.
+
+For example:
+
+```bash
+port run a030
+```
+
+This first gets the directed acyclic graph (DAG) that defines `a030`'s dependencies. It then uses file output mtime values to determine if any results need to be re-run. This includes:
+
+- Requiring that, for a given output, all dependency outputs have an mtime less than or equal to the current output.
+- Requiring all outputs to have an mtime greater than or equal to the script that creates them.
+
+Flags include:
+- `--force`: rerun the specified task.
+- `--force-all`: rerun all affected tasks.
+- `--debug`: If true, drop into a pdb debugger on failure.
+
+## Remove
+
+Remove results from specified tasks.
+
+```bash
+port remove a020  # removes the results for a020
+```
+
+## Parse
+
+Although typically called automatically by other commands, it can be used manually to parse script structure/dependencies and update timestamps.
+
+```bash
+port parse  # parse current directory, or pass a path
+```
+
+The flag `--dryrun` can be used to simply validate the project structure.
+
+
+# Guiding principles
+- `port` is always optional. A project can be fully executed by running the scripts in order. It is there when you want it, and it gets out of your way when you don't.

stooge-0.1.0/README.md

@@ -0,0 +1,99 @@
+# port
+
+A simple project framework.
+
+`port` facilitates rapid, reproducible development for local research projects.
+
+## Project structure
+
+port requires a specific project structure.
+
+An example project directory looks like this:
+
+my_project
+-> inputs/
+---> some_file.csv
+-> outputs/
+-> local.py
+-> environment.yml
+-> a010_clean_data.py
+-> a020_calculate.py
+-> a030_visualize.py
+
+Each script has an ID (the part of the name before the first `_`).
+
+The file called `local.py` defines the inputs and outputs of the scripts. In this file, outputs are also given the same prefix.
+
+For example:
+
+```python
+from pathlib import Path
+
+input_path = Path("inputs")
+output_path = Path("outputs")
+
+raw_data_path = input_path / "raw data.csv"
+
+a010_clean_data_path = output_path / "a010_cleaned_outputs.csv"
+a020_calculated_data_path = output_path / "a020_calculated_results.csv"
+a030_result_plot = output_path / "a030_result_plot.png"
+```
+
+This provides port with all the required information to figure out the relationships between scripts and their outputs.
+
+## Init
+Creates a port project skeleton.
+
+This provides a small Rich interface to get information about the project name and backend, or they can be provided via command-line flags.
+
+Supported backends are:
+- [uv](https://docs.astral.sh/uv/)
+- [miniforge](https://github.com/conda-forge/miniforge)
+- [marimo](https://marimo.io/)
+- python (use system python or provided interpreter path)
+
+```bash
+port init test_project --backend uv
+```
+
+## Run
+
+`port run` runs the entire project up to and including a target ID. It automatically calculates stale or missing results that `a030` depends on.
+
+For example:
+
+```bash
+port run a030
+```
+
+This first gets the directed acyclic graph (DAG) that defines `a030`'s dependencies. It then uses file output mtime values to determine if any results need to be re-run. This includes:
+
+- Requiring that, for a given output, all dependency outputs have an mtime less than or equal to the current output.
+- Requiring all outputs to have an mtime greater than or equal to the script that creates them.
+
+Flags include:
+- `--force`: rerun the specified task.
+- `--force-all`: rerun all affected tasks.
+- `--debug`: If true, drop into a pdb debugger on failure.
+
+## Remove
+
+Remove results from specified tasks.
+
+```bash
+port remove a020  # removes the results for a020
+```
+
+## Parse
+
+Although typically called automatically by other commands, it can be used manually to parse script structure/dependencies and update timestamps.
+
+```bash
+port parse  # parse current directory, or pass a path
+```
+
+The flag `--dryrun` can be used to simply validate the project structure.
+
+
+# Guiding principles
+- `port` is always optional. A project can be fully executed by running the scripts in order. It is there when you want it, and it gets out of your way when you don't.

stooge-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+
+# --- Build system configuration
+
+[build-system]
+requires = [ "setuptools>=41", ]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# --- Project Metadata
+
+[project]
+name = "stooge"
+version = "0.1.0"
+
+authors = [
+  { name="Derrick Chambers", email="chambers.ja.derrick@gmail.com" },
+]
+
+description = "A simple project framework to keep you from getting burned"
+readme = "README.md"
+license = { file="LICENSE" }
+requires-python = ">=3.13"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+]
+
+keywords = ["workflow", "projects"]
+
+# --- Dependencies
+
+dependencies = [
+    "typer",
+    "rich",
+    "jinja2",
+    "toml",
+    "pdbpp>=0.12.0.post1",
+]
+
+[project.optional-dependencies]
+
+test = [
+    "pytest",
+    "pre-commit",
+    "ruff",
+    "scikit-learn",
+]
+dev = ["stooge[test]"]
+
+[project.scripts]
+port = "port.cli:app"
+
+# --- URLs for project
+
+[project.urls]
+"Bug Tracker" = "https://github.com/d-chambers/port/issues"
+"Documentation" = "https://github.com/d-chambers/port"
+"Homepage" = "https://github.com/d-chambers/port"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: tests that run very slowly, skipped by default",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"

stooge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stooge-0.1.0/src/port/__init__.py

@@ -0,0 +1,11 @@
+"""port package exports."""
+
+from pathlib import Path
+
+from port.info import info
+from port.init import init
+from port.version import __version__
+
+_template_path = Path(__file__).parent / "data" / "project_template"
+
+__all__ = ["__version__", "_template_path", "info", "init"]

stooge-0.1.0/src/port/cli.py

@@ -0,0 +1,46 @@
+"""
+Port's CLI.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from port.info import info as info_project
+from port.init import init as init_project
+from port.version import __version__
+
+app = typer.Typer(help="CLI for port project scaffolding.")
+
+
+@app.command("init")
+def init(path: Optional[Path] = typer.Argument(None)):
+    """Create or initialize a port project directory."""
+    project_path = init_project(path)
+    typer.echo(str(project_path))
+
+
+@app.command("info")
+def info(path: Optional[Path] = typer.Argument(None)):
+    """Show metadata for a port project."""
+    data = info_project(path)
+    typer.echo(json.dumps(data))
+
+
+@app.command("version")
+def version():
+    """Print the installed port version."""
+    typer.echo(__version__)
+
+
+def main():
+    """Entrypoint used by executable wrappers."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

stooge-0.1.0/src/port/console.py

@@ -0,0 +1,6 @@
+"""
+The Rich console for nice printing.
+"""
+from rich.console import Console
+
+console = Console()

stooge-0.1.0/src/port/constants.py

@@ -0,0 +1,12 @@
+"""
+SPROF constants.
+"""
+
+backends = (
+    "uv",
+    "mamba",
+    "marimo",
+    "python",
+)
+
+local_path = "local.py"

stooge-0.1.0/src/port/data/project_template/a010_first_script.py

@@ -0,0 +1,6 @@
+"""
+A place-filler for the first script of the port project.
+"""
+
+if __name__ == "__main__":
+    pass

stooge-0.1.0/src/port/data/project_template/local.py

@@ -0,0 +1,38 @@
+"""
+# {{ project_name }}
+
+#### {Insert description of project} ####
+"""
+from pathlib import Path
+
+# --- Project functions
+# These are used in more than one script. Consider creating a separate utils
+# module if this section gets too large. However, never import any project
+# modules in local.py.
+
+
+def ensure_folder_exists(path: Path) -> Path:
+    """
+    Given a path to a directory, ensure the directory exists.
+
+    Returns a path to said directory.
+    """
+    path = Path(path)
+    path.mkdir(exist_ok=True, parents=True)
+    return path
+
+
+# --- Project Parameters
+
+# The base path for this project
+project_path = Path(__file__).parent
+
+# --- Inputs to project
+
+input_path = ensure_folder_exists(project_path / "inputs")
+
+# --- Outputs produced by project
+
+# outputs should have the same prefix as the script which creates them (eg a010)
+
+output_path = ensure_folder_exists(project_path / "outputs")

stooge-0.1.0/src/port/data/project_template/utils.py

@@ -0,0 +1,3 @@
+"""
+Utilities for {{ project_name }}.
+"""

stooge-0.1.0/src/port/data/spf_example/a010_clean_data.py

@@ -0,0 +1,21 @@
+"""
+The first script to run
+"""
+
+import pandas as pd
+from local import cleaned_csv, earthquake_csv
+
+
+def clean_earthquake_df(df):
+    """Clean the earthquake dataframe."""
+    # drop any rows with lat/long out of range or invalid event_id
+    bad_lat = abs(df["longitude"]) > 180
+    bad_long = abs(df["latitude"]) > 90
+    out = df[~(bad_long | bad_lat)].dropna(axis="rows", subset=["event_id"])
+    return out
+
+
+if __name__ == "__main__":
+    df = pd.read_csv(earthquake_csv)
+    out = clean_earthquake_df(df)
+    out.to_csv(cleaned_csv, index=False)

stooge-0.1.0/src/port/data/spf_example/a020_calculate.py

@@ -0,0 +1,25 @@
+"""
+This script simply adds a column to the dataframe.
+"""
+import local
+import pandas as pd
+
+
+def add_summary_string(df):
+    """Add a column to the df which is useful for displaying."""
+
+    def _get_summary_str(ser):
+        time_str = str(ser["time"])[:19]
+        depth_str = f"Depth={ser['depth']/1_000}km"
+        mag_str = f"ML={ser['magnitude']:02f}"
+        out = f"{time_str}  {depth_str}  {mag_str}"
+        return out
+
+    df["summary_string"] = df.apply(_get_summary_str, axis=1)
+    return df
+
+
+if __name__ == "__main__":
+    df = pd.read_csv(local.cleaned_csv)
+    out = add_summary_string(df)
+    out.to_csv(local.calc_csv)

stooge-0.1.0/src/port/data/spf_example/a030_visualize.py

@@ -0,0 +1,38 @@
+"""
+Script to create simple visualizations of earthquake data.
+"""
+import local
+import matplotlib.pyplot as plt
+import pandas as pd
+from local import magnitude_time_plot
+
+
+def plot_magnitude_histogram(df):
+    """Plot a histogram of magnitudes, return mpl figure."""
+    fig, ax = plt.subplots(1, 1)
+    ax.hist(df["magnitude"])
+    ax.set_xlabel("Local Magnitude")
+    ax.set_ylabel("Count")
+    plt.tight_layout()
+    return fig
+
+
+def time_mag_dot_plot(df):
+    """Create a dot plot of magnitude and time."""
+    time = pd.to_datetime(df["time"])
+    fig, ax = plt.subplots(1, 1)
+    ax.plot(time, df["magnitude"], ".")
+    ax.set_xlabel("Time")
+    ax.set_ylabel("Local Magnitude")
+    plt.tight_layout()
+    return fig
+
+
+if __name__ == "__main__":
+    df = pd.read_csv(local.calc_csv)
+    # plot magnitude histogram
+    fig = plot_magnitude_histogram(df)
+    fig.savefig(local.magnitude_histogram)
+    # plot magnitude vs time
+    fig = time_mag_dot_plot(df)
+    fig.savefig(magnitude_time_plot)

stooge-0.1.0/src/port/data/spf_example/local.py

@@ -0,0 +1,36 @@
+"""
+Project variables used by the example project.
+"""
+from pathlib import Path
+
+# --- Project functions
+# These are used in more than one script. Consider creating a separate utils
+# module if this section gets too large.
+
+
+def ensure_folder_exists(path: Path) -> Path:
+    """
+    Given a path to a directory, ensure the directory exists.
+
+    Returns a path to said directory.
+    """
+    path = Path(path)
+    path.mkdir(exist_ok=True, parents=True)
+    return path
+
+
+# The base path for this project
+project_path = Path(__file__).parent
+
+# --- Inputs to project
+
+input_path = ensure_folder_exists(project_path / "inputs")
+earthquake_csv = input_path / "bingham_earthquakes.csv"
+
+# --- Outputs produced by project
+
+output_path = ensure_folder_exists(project_path / "outputs")
+cleaned_csv = output_path / "a010_cleaned_earthquakes.csv"
+calc_csv = output_path / "a020_calculated_earthquakes.csv"
+magnitude_histogram = output_path / "a030_magnitude_hist.png"
+magnitude_time_plot = output_path / "a030_magnitude_time_plot"

stooge-0.1.0/src/port/data/spf_example/utils.py

@@ -0,0 +1,20 @@
+"""
+Example utilites
+"""
+from pathlib import Path
+from typing import Union
+
+
+def ensure_folder_exists(path: Union[Path, str]) -> Path:
+    """
+    Given a path to a directory, ensure the directory exists.
+
+    Returns a path to said directory.
+    """
+    path = Path(path)
+    path.mkdir(exist_ok=True, parents=True)
+    return path
+
+
+def some_function():
+    """Another function which might be used by multiple files."""

stooge-0.1.0/src/port/exceptions.py

@@ -0,0 +1,11 @@
+"""
+port exceptions.
+"""
+
+
+class SPFException(Exception):
+    """Base exception for port."""
+
+
+class SPFInitError(SPFException, RuntimeError):
+    """Raised with something is wrong the project setup."""

stooge-0.1.0/src/port/info.py

@@ -0,0 +1,24 @@
+"""Helpers for getting metadata from a port project."""
+
+from pathlib import Path
+from typing import Optional, Union
+
+from port.meta import read_metadata
+
+
+def info(project_path: Optional[Union[Path, str]] = None) -> dict:
+    """
+    Return metadata for a project.
+
+    Parameters
+    ----------
+    project_path
+        Path to project directory. Defaults to current working directory.
+
+    Returns
+    -------
+    dict
+        Metadata dictionary for the project.
+    """
+    data = read_metadata(project_path)
+    return data