stooge 0.1.0__py3-none-any.whl

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"]

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()

port/console.py

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

port/constants.py

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

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

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")

port/data/project_template/utils.py

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

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)

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)

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)

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"

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."""

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."""

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

port/init.py

@@ -0,0 +1,53 @@
+"""Code for creating new port projects."""
+
+from pathlib import Path
+from typing import Optional, Union
+
+import jinja2
+
+import port
+from port.meta import write_metadata
+
+
+def _init_directory(template_directory: Path, output_directory: Path, data: dict) -> None:
+    """Render each template file into the output directory."""
+    for path in Path(template_directory).rglob("*"):
+        if path.is_dir():
+            continue
+        template_contents = path.read_text()
+        template = jinja2.Template(template_contents)
+        out = template.render(data)
+        new_path = output_directory / path.relative_to(template_directory)
+        if new_path.exists():
+            continue
+        new_path.parent.mkdir(exist_ok=True, parents=True)
+        # Do not copy example script if an a010 script already exists.
+        is_a010 = new_path.name.startswith("a010")
+        has_a010 = bool(list(output_directory.glob("a010*.py")))
+        if is_a010 and has_a010:
+            continue
+        with new_path.open("w") as fi:
+            fi.write(out)
+
+
+def init(path: Optional[Union[Path, str]] = None) -> Path:
+    """
+    Initialize a port project in a target directory.
+
+    Parameters
+    ----------
+    path
+        The target directory path. If it does not exist, it is created.
+        If not provided, use the current working directory.
+
+    Returns
+    -------
+    Path
+        Path to the initialized project directory.
+    """
+    out_path = Path(path) if path is not None else Path.cwd()
+    out_path.mkdir(exist_ok=True, parents=True)
+    data = {"project_name": out_path.name}
+    _init_directory(port._template_path, out_path, data=data)
+    write_metadata(out_path)
+    return out_path

port/meta.py

@@ -0,0 +1,42 @@
+"""Helpers for port project metadata."""
+
+from pathlib import Path
+from typing import Union
+
+import port
+from port.utils import ensure_spf_project, path_or_cwd
+
+METADATA_DIRECTORY_NAME = ".port"
+METADATA_FILE_NAME = "spf_version.txt"
+SPF_VERSION_FILE_NAME = METADATA_FILE_NAME
+
+
+def _write_version(spf_path: Path) -> None:
+    """Write the current port version metadata file."""
+    with (spf_path / METADATA_FILE_NAME).open("w") as fi:
+        fi.write(port.__version__)
+
+
+def _read_version(spf_path: Path) -> str:
+    """Read the port version metadata value."""
+    with (spf_path / METADATA_FILE_NAME).open("r") as fi:
+        out = fi.read().rstrip()
+    return out
+
+
+def write_metadata(project_path: Union[str, Path]) -> None:
+    """Write project metadata for an initialized port project."""
+    spf_path = Path(project_path) / METADATA_DIRECTORY_NAME
+    spf_path.mkdir(exist_ok=True, parents=True)
+    _write_version(spf_path)
+
+
+def read_metadata(project_path: Union[str, Path, None]) -> dict[str, str]:
+    """Read metadata from an initialized port project."""
+    path = path_or_cwd(project_path)
+    ensure_spf_project(path)
+    spf_path = path / METADATA_DIRECTORY_NAME
+    out = {
+        "spf_version": _read_version(spf_path),
+    }
+    return out

port/project.py

@@ -0,0 +1,73 @@
+"""
+Read/write support for project structure.
+"""
+from pathlib import Path
+from dataclasses import dataclass
+
+import tomllib
+
+def _get_mtimes(files_or_folders) -> tuple[list[float], list[float]]:
+    """
+    Get timestamps for files or folders.
+    If a folder, find the most recent mtime, including files and folders inside.
+    """
+    def _get_min_max(entry):
+        path = Path(entry)
+        if path.is_file():
+            return (entry.stat().st_mtime, entry.stat().st_mtime)
+        # Go through the contents of the directory; return the min/max modified times.
+        time = path.stat().st_mtime
+        min_time, max_time = time, time
+        # iterate through contents, update min/max times.
+        for sub in path.rglob('*'):
+            subtime = sub.stat().st_mtime
+            if subtime < min_time:
+                min_time = subtime
+            if subtime > max_time:
+                max_time = subtime
+        return min_time, max_time
+
+    min_times, max_times = [], []
+    for entry in files_or_folders:
+        min_time, max_time = _get_min_max(entry)
+        min_times.append(min_time)
+        max_times.append(max_time)
+    return min_times, max_times
+
+
+            
+
+
+class Project(dataclass):
+    """A class to encapsulate information about a project."""
+    # A dict that contains the direct dependencies from one ID to another.
+    dependencies: dict[str, tuple[str, ...]]
+    # A mapping from an ID to the path (relative to project directory)
+    script_id_path_map: dict[str, Path]
+    # Output paths
+    out_id_path_map: dict[str, Path]
+    # Outputs that are directories rather than files
+    directory_ids: set[str]
+    # Time stamps of scripts/outputs (key is path not id)
+    time_stamps: dict[str, float]
+    # Run command
+    backend: str = "uv"
+    _toml_name = "port.toml"
+
+    def write_toml(self, path):
+        """Write the toml file containing information about the project."""
+
+    @classmethod
+    def from_path(cls, path):
+        """Create a project object from the path to a port project."""
+        # First, read existing toml, there is one, and get the back_end
+        outputs = {}
+        if (tomal_path := path / cls._toml_name).exists():
+            tom = tomllib.load(tomal_path)
+            outputs['backend'] = tom['backend']
+        # Next actually parse structure.
+
+
+
+def _read_dependencies():
+    """Read the script dependencies, parse into a dictionary."""

port/utils/__init__.py

@@ -0,0 +1,213 @@
+"""
+Utilities for port.
+"""
+import contextlib
+import fnmatch
+import hashlib
+import importlib.util
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+from port.exceptions import SPFInitError
+
+# def get_task_list(project_path):
+#     """
+#     Return a list of pre-DoIt style task dicts.
+#
+#     The dicts have the following keys:
+#         script_path - The path to the script relative to the project path.
+#         basename - The Name of the task
+#         inputs - A list of file inputs
+#         outputs - A list of file outputs
+#     """
+#     path = path_or_cwd(project_path)
+#     nodes = get_project_nodes(path)
+#     out = []
+#     for item, value in nodes.items():
+#         name = Path(item).name.split('_')[0]
+#         task = {
+#             'basename': name,
+#             'script_path': str(item),
+#             'inputs': [str(x) for x in value['inputs']],
+#             'outputs': [str(x) for x in value['outputs']],
+#         }
+#         out.append(task)
+#     return out
+
+
+def get_python_scripts(project_path) -> tuple[Path]:
+    """
+    Return a tuple of python scripts which *may* produce outputs.
+
+    Returned paths are relative to project path.
+    """
+    path = path_or_cwd(project_path)
+    out = []
+    for pypath in path.glob("*.py"):
+        name = pypath.name.split(".py")[0]
+        if len(name) < 4:
+            continue
+        letter = name[0]
+        numbers = name[1:4]
+        if letter.isalpha() and numbers.isnumeric():
+            out.append(pypath.relative_to(path))
+    return tuple(out)
+
+
+def _get_task_dict_from_script(path, project_path):
+    """Get the inputs and outputs for a python script."""
+    local_contents = get_local_contents(project_path)
+    script_str = (project_path / path).read_text()
+    script_lines = script_str.split("\n")
+    prefix = path.name.split("_")[0]
+    nodes = []
+    for name, value in local_contents.items():
+        if name not in script_str:
+            continue
+        # simple case where variable is used as local.{name}
+        if f"local.{name}" not in script_str:
+            # now need to check from local import name style
+            match = f"*from local import *{name}*"
+            has_from_input = [fnmatch.fnmatch(x, match) for x in script_lines]
+            # we only get here if an unrelated local variable shares a name
+            # with a project variable
+            if not any(has_from_input):
+                continue
+        nodes.append(name)
+
+    is_output = {x: local_contents[x].name.startswith(prefix) for x in nodes}
+    outputs = [str(local_contents[x]) for x in nodes if is_output[x]]
+    inputs = [str(local_contents[x]) for x in nodes if not is_output[x]]
+    out = dict(
+        file_outputs=tuple(outputs),
+        file_inputs=tuple(inputs),
+        name=Path(path).name.split("_")[0],
+        script_path=path,
+    )
+    return out
+
+
+def get_project_task_list(project_path):
+    """Get the inputs and outputs for each script in the project."""
+    project_path = path_or_cwd(project_path)
+    scripts = get_python_scripts(project_path)
+    return {x: _get_task_dict_from_script(x, project_path) for x in scripts}
+
+
+def get_local_contents(project_path) -> dict:
+    """Get a dict of variable_name: path for each input/output path"""
+
+    def _get_artifacts(local):
+        """extract all potential inputs/outputs from local."""
+        info = {}
+        input_str = str(input_path)
+        output_str = str(output_path)
+        for name in dir(local):
+            # skip any dunders and non-paths
+            if name.startswith("__"):
+                continue
+            var = getattr(local, name)
+            if not isinstance(var, (str, Path)):
+                continue
+            path_str = str(Path(var))
+            in_inputs = path_str.startswith(input_str) and path_str != input_str
+            in_outputs = path_str.startswith(output_str) and path_str != output_str
+            if in_inputs or in_outputs:
+                info[name] = Path(var).relative_to(project_path)
+        return info
+
+    # get path to local.py
+    path = path_or_cwd(project_path).absolute()
+    if not path.name.endswith("local.py"):
+        path = project_path / "local.py"
+    else:
+        project_path = path.parent
+    # load module
+    with working_directory(path.parent):  # chdir to local
+        spec = importlib.util.spec_from_file_location("local", str(path))
+        local = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(local)
+    input_path, output_path = local.input_path, local.output_path
+    return _get_artifacts(local)
+
+
+def path_or_cwd(path: Optional[Union[str, Path]] = None) -> Path:
+    """Return a Path from path or, if None, return Path of cwd."""
+    if path is None:
+        path = Path.cwd()
+    return Path(path)
+
+
+def ensure_spf_project(project_path: Union[str, Path]) -> Path:
+    """
+    Ensure the path is a port project by checking for port metadata.
+
+    Parameters
+    ----------
+    project_path
+        Path to project.
+
+    Returns
+    -------
+
+    """
+    path = path_or_cwd(project_path)
+    if not path.exists():
+        msg = (
+            f"{path.parent} is not yet an " f"port project. Try running `port init`."
+        )
+        raise SPFInitError(msg)
+    return path
+
+
+@contextlib.contextmanager
+def working_directory(path):
+    """Changes working directory and returns to previous on exit."""
+    prev_cwd = Path.cwd()
+    os.chdir(path)
+    try:
+        yield
+    finally:
+        os.chdir(prev_cwd)
+
+
+def file_hash(fname: Union[str, Path], algorithm="sha256") -> str:
+    """
+    Calculate the hash of a given file.
+
+    Useful for checking if a file has changed or been corrupted.
+
+    Parameters
+    ----------
+    fname : str
+        The name of the file.
+    algorithm : str
+        The type of the hashing algorithm
+
+    Examples
+    --------
+    >>> fname = "test-file-for-hash.txt"
+    >>> with open(fname, "w") as f:
+    ...     __ = f.write("content of the file")
+    >>> print(file_hash(fname))
+    0fc74468e6a9a829f103d069aeb2bb4f8646bad58bf146bb0e3379b759ec4a00
+    >>> import os
+    >>> os.remove(fname)
+
+    Notes
+    -----
+    This implementation was taken from the excellent Pooch project:
+    https://github.com/fatiando/pooch
+    """
+    if algorithm not in hashlib.algorithms_available:
+        raise ValueError(f"Algorithm '{algorithm}' not available in hashlib")
+    # Calculate the hash in chunks to avoid overloading the memory
+    chunksize = 65536
+    hasher = hashlib.new(algorithm)
+    with open(fname, "rb") as fin:
+        buff = fin.read(chunksize)
+        while buff:
+            hasher.update(buff)
+            buff = fin.read(chunksize)
+    return hasher.hexdigest()

port/utils/dag.py

@@ -0,0 +1,61 @@
+"""
+Utilities for working with the DAG
+"""
+
+from collections import deque
+
+
+def topological_sort(dependencies: dict[str, list[str]]) -> list[str]:
+    """
+    Return tasks in topological order for execution using Kahn's algorithm.
+
+    Parameters
+    ----------
+    dependencies
+        Dictionary mapping task_id -> [dependent_task_id, ...].
+
+    Returns
+    -------
+    List[str]
+        Task IDs in execution order.
+
+    Notes
+    -----
+    - (Kahn's algorithm)[https://en.wikipedia.org/wiki/Topological_sorting]
+
+    Raises
+    ------
+    ValueError
+        If circular dependency is detected in the task graph.
+    """
+    all_task_ids = set(dependencies.keys())
+    for task_dependents in dependencies.values():
+        all_task_ids.update(task_dependents)
+
+    # Kahn's algorithm for topological sorting
+    in_degree = {task_id: 0 for task_id in all_task_ids}
+    adjacency: dict[str, list[str]] = {task_id: [] for task_id in all_task_ids}
+
+    for task_id, task_dependents in dependencies.items():
+        for dependent_id in task_dependents:
+            adjacency[task_id].append(dependent_id)
+            in_degree[dependent_id] += 1
+
+    # Start with tasks that have no dependencies
+    queue = deque(task_id for task_id, degree in in_degree.items() if degree == 0)
+    result = []
+
+    while queue:
+        current = queue.popleft()
+        result.append(current)
+
+        # Reduce in-degree for dependent tasks
+        for downstream_id in adjacency[current]:
+            in_degree[downstream_id] -= 1
+            if in_degree[downstream_id] == 0:
+                queue.append(downstream_id)
+
+    if len(result) != len(all_task_ids):
+        raise ValueError("Circular dependency detected in pipe")
+
+    return result

port/utils/parse.py

@@ -0,0 +1,237 @@
+"""
+Utilities for parsing files dependencies.
+"""
+import ast
+import importlib.util
+from collections import defaultdict
+from pathlib import Path
+from types import ModuleType
+from typing import Mapping
+
+from port.constants import local_path
+
+
+def _load_module_from_path(path: Path) -> ModuleType:
+    """Load and return a module object from a python file path."""
+    spec = importlib.util.spec_from_file_location("local", str(path))
+    if spec is None or spec.loader is None:
+        raise ValueError(f"Could not load module from '{path}'")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def parse_local(path: Path) -> dict[str, Path]:
+    """
+    Parse path variables from a project's ``local.py`` module.
+
+    Parameters
+    ----------
+    path
+        Either the path to ``local.py`` or the project directory that
+        contains ``local.py``.
+
+    Returns
+    -------
+    dict[str, Path]
+        Mapping of variable name to ``Path`` value for top-level variables
+        in ``local.py`` that are ``Path`` instances.
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``local.py`` cannot be found.
+    ValueError
+        If a ``local.py`` module cannot be loaded from the given path.
+    """
+    local_path = Path(path)
+    if local_path.is_dir():
+        local_path = local_path / "local.py"
+    if not local_path.exists():
+        raise FileNotFoundError(f"Cannot find local.py at '{local_path}'")
+
+    local_module = _load_module_from_path(local_path)
+    out: dict[str, Path] = {}
+    for name in dir(local_module):
+        if name.startswith("_"):
+            continue
+        value = getattr(local_module, name)
+        if isinstance(value, Path):
+            out[name] = value
+    return out
+
+
+def parse_script(path: Path, param_dict: Mapping[str, Path]) -> dict[str, set[str]]:
+    """
+    Parse script usage of ``local`` variables into inputs and outputs.
+
+    Parameters
+    ----------
+    path
+        Path to the script file to parse.
+    param_dict
+        Mapping of ``local`` variable name to path, typically from
+        :func:`parse_local`.
+
+    Notes
+    -----
+    ``param_dict`` is of the form ``{variable_name: path}``.
+    Local variables are detected for these import styles:
+    - ``import local`` / ``import local as x``
+    - ``from local import var_name`` (with alias support)
+    - ``from local import *`` (best-effort static detection)
+    - variables that share the same ID (or the path shares the same id)
+      as the script are considered outputs. Otherwise, they are inputs.
+
+    Returns
+    -------
+    dict[str, set[str]]
+        Dictionary with keys ``inputs`` and ``outputs`` containing sets of
+        variable names used by the script. Output variables are those whose
+        variable name or artifact file name starts with the script prefix
+        (for example ``a010``).
+    """
+    script_path = Path(path)
+    tree = ast.parse(script_path.read_text())
+    local_names = set(param_dict)
+    script_prefix = script_path.name.split("_")[0]
+
+    module_aliases, direct_imports, has_star_import = _collect_local_imports(tree)
+    bound_names = _collect_bound_names(tree)
+    used_names = _collect_local_usages(
+        tree=tree,
+        local_names=local_names,
+        module_aliases=module_aliases,
+        direct_imports=direct_imports,
+        has_star_import=has_star_import,
+        bound_names=bound_names,
+    )
+
+    inputs: set[str] = set()
+    outputs: set[str] = set()
+    for name in used_names:
+        file_name = Path(param_dict[name]).name
+        is_output_name = name.startswith(script_prefix)
+        is_output_path = file_name.startswith(script_prefix)
+        if is_output_name or is_output_path:
+            outputs.add(name)
+        else:
+            inputs.add(name)
+    return {"inputs": inputs, "outputs": outputs}
+
+
+def _collect_local_imports(
+    tree: ast.AST,
+) -> tuple[set[str], dict[str, str], bool]:
+    """Collect local module aliases, direct imports, and wildcard imports."""
+    module_aliases: set[str] = set()
+    direct_imports: dict[str, str] = {}
+    has_star_import = False
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "local":
+                    module_aliases.add(alias.asname or "local")
+        elif isinstance(node, ast.ImportFrom) and node.module == "local":
+            for alias in node.names:
+                if alias.name == "*":
+                    has_star_import = True
+                else:
+                    direct_imports[alias.asname or alias.name] = alias.name
+    return module_aliases, direct_imports, has_star_import
+
+
+def _collect_bound_names(tree: ast.AST) -> set[str]:
+    """Collect names that are locally bound in the script."""
+    out: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            out.add(node.id)
+    return out
+
+
+def _collect_local_usages(
+    tree: ast.AST,
+    local_names: set[str],
+    module_aliases: set[str],
+    direct_imports: dict[str, str],
+    has_star_import: bool,
+    bound_names: set[str],
+) -> set[str]:
+    """Collect local variable names used in script."""
+    used_names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name):
+            if node.value.id in module_aliases and node.attr in local_names:
+                used_names.add(node.attr)
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+            if node.id in direct_imports:
+                if direct_imports[node.id] in local_names:
+                    used_names.add(direct_imports[node.id])
+            elif (
+                has_star_import
+                and node.id in local_names
+                and node.id not in bound_names
+            ):
+                used_names.add(node.id)
+    return used_names
+
+
+def build_dependency_graph(
+    project_path: Path,
+) -> dict[str, list[str]]:
+    """
+    Build a script dependency graph for a project.
+
+    Parameters
+    ----------
+    project_path
+        Path to the project directory.
+
+    Returns
+    -------
+    dict[str, list[str]]
+        Mapping of ``{task_id: [dependent_task_id, ...]}`` where each key is
+        a script id and each value lists downstream scripts that depend on it.
+    """
+    project_path = Path(project_path)
+    local_vars = parse_local(project_path / local_path)
+
+    # Collect parsed local-variable usage for each task script.
+    script_vars: dict[str, dict[str, set[str]]] = {}
+    for script_path in sorted(project_path.glob("*.py")):
+        task_id = _get_task_id(script_path)
+        if task_id is None:
+            continue
+        script_vars[task_id] = parse_script(script_path, local_vars)
+
+    # Map output variable name -> producing task id.
+    producers: dict[str, set[str]] = defaultdict(set)
+    for task_id, var_map in script_vars.items():
+        for output_var in var_map["outputs"]:
+            producers[output_var].add(task_id)
+
+    # Build adjacency: upstream task -> dependent downstream tasks.
+    dependencies: dict[str, set[str]] = {task_id: set() for task_id in script_vars}
+    for task_id, var_map in script_vars.items():
+        upstream_ids = {
+            producer_id
+            for input_var in var_map["inputs"]
+            for producer_id in producers.get(input_var, set())
+            if producer_id != task_id
+        }
+        for upstream_id in upstream_ids:
+            dependencies[upstream_id].add(task_id)
+
+    return {task_id: sorted(dependents) for task_id, dependents in dependencies.items()}
+
+
+def _get_task_id(script_path: Path) -> str | None:
+    """Return task id from script name if it matches the task pattern."""
+    stem = script_path.stem
+    if len(stem) < 4:
+        return None
+    if not stem[0].isalpha() or not stem[1:4].isdigit():
+        return None
+    return stem.split("_")[0]

port/version.py

@@ -0,0 +1,4 @@
+"""
+port version.
+"""
+__version__ = "0.0.0"

stooge-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,27 @@
+port/__init__.py,sha256=8aFefuNlnxNHNFB2DaomxAwVDpWwe71bqRZ3k_mPhGk,277
+port/cli.py,sha256=ZJRJFR8ltjqE7plAZ6YE_cRQ70Hdp-9xNIZWQCBQHkE,940
+port/console.py,sha256=3d7beBMU-_gvTk8ln-PvFZBfPgLZ1LVvZU34LRgruNw,98
+port/constants.py,sha256=DgkFhtbCY37xY0MJJaJ6tmiSS6oSYLJXpDQq3rAuPgk,117
+port/exceptions.py,sha256=v9xp_Z1_FR7bp-reGLvQ7RXYiEbmjyJSOF8JoKpFT3c,203
+port/info.py,sha256=dfeahttF3hmebcp28soh5e96QhWjTh1OWCsP32_vuUk,530
+port/init.py,sha256=PujSbES20iSLIocTy41xrYV9bn1VQHrrf66WZbVtUC4,1702
+port/meta.py,sha256=0E4ARTrdB2JYcrQp5r-0wrkarsvfPIgbAcO9UBP_s5Q,1263
+port/project.py,sha256=7bU6mNqxx2UY6nqptJi_L_2m6w4wmIW0ebpQQKPT0U0,2419
+port/version.py,sha256=NdlMsj9y8ABZ7HNYtSyMs1xJRrPl3ct8iyfEod7AQ98,44
+port/data/project_template/a010_first_script.py,sha256=NE-kIzAWS3RPoBQy1M9t-rXKbnZ0plfxROekdZEe0D0,102
+port/data/project_template/local.py,sha256=t_AIfqPYNBaU57FzYO1ofYnpCEcq-zp26N1YmXLg-3s,906
+port/data/project_template/utils.py,sha256=jtbycQRnTej-AEKJ0mT3rfI3lNpP6Ec0JpQfoZupQ_A,42
+port/data/spf_example/a010_clean_data.py,sha256=BlTcnd14WorP5Up3RjxFfQHMa_pB5J0XSG66tMvp5Qs,553
+port/data/spf_example/a020_calculate.py,sha256=BYkwaMPx55NmkrzgrBezlj0hzrzPdgPC3nSyLYtkA-8,640
+port/data/spf_example/a030_visualize.py,sha256=Mj4uQlvTCYYd8HWIODOjfLCl3ACNFSXzH3VCqhS328o,1000
+port/data/spf_example/local.py,sha256=TA8cUpibzjU7Gvje3BGXCkjV0tIE5zGCuG2ZunfWUYo,1023
+port/data/spf_example/utils.py,sha256=ERlqLwiApPxuvcWLhmPKkhfQI8A-PPlk-r3TtfTXXow,423
+port/utils/__init__.py,sha256=YFiryBF0727EF1vODxTfhmTf1f2g-7RIY_6X_YupMWQ,6697
+port/utils/dag.py,sha256=UACH7q6wPjGU4Gl8ahtwmW-XZk-g0o4aMRTh3G8fU6o,1732
+port/utils/parse.py,sha256=lTGf_tLojhTM2Ox29B5C1_10G35P0eJMbyzeV8KWZgA,7990
+stooge-0.1.0.dist-info/licenses/LICENSE,sha256=94pKobixYnFwavNd6FYQOOPPUgfpV2l7QmhyolWrm3Q,1073
+stooge-0.1.0.dist-info/METADATA,sha256=qhM9Tn1xYSsLqz1icIdhTgymwL96Y-dBREC-Jm-RnU8,5203
+stooge-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+stooge-0.1.0.dist-info/entry_points.txt,sha256=RTqTNzAw7Xo4juD-K3RxKtbFqrQFQS-nxz8hYdnTDso,38
+stooge-0.1.0.dist-info/top_level.txt,sha256=T2UTGKEM-1RD_6VLq7wiTrhY49fKyh8rqgUHarvGSYQ,5
+stooge-0.1.0.dist-info/RECORD,,

stooge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stooge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+port = port.cli:app

stooge-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+port