phistory 0.2.0__py3-none-any.whl

phistory/__init__.py

@@ -0,0 +1,40 @@
+"""
+phistory: seamless argparse execution history.
+
+Import this at the very top of your script:
+
+    import phistory
+
+Behaviour:
+- On import, if '--history' is present in sys.argv, prints history for the current
+  script and exits.
+- Patches argparse's parse_args/parse_known_args so that, on first call, the
+  invocation (script name + args) is appended to ~/.python-history/<script>.history
+  (excluding the --history flag itself).
+"""
+
+from .core import install as _install
+import os
+
+# Allow disabling automatic install during import for tests or introspection.
+# Set the environment variable PHISTORY_NO_AUTO_INSTALL=1 to suppress auto-hooks.
+if os.environ.get("PHISTORY_NO_AUTO_INSTALL") != "1":
+    _install()
+
+# phistory/__init__.py  (append to the bottom)
+from .yaml_args import (
+    load as yaml_args_load,
+    derive_params_filename,
+    load_yaml_params,
+)
+
+# nice namespace: phistory.yaml_args.load
+from . import yaml_args  # re-export module for ergonomic `from phistory import yaml_args`
+
+__all__ = [
+    # existing…
+    "yaml_args",
+    "yaml_args_load",
+    "derive_params_filename",
+    "load_yaml_params",
+]

phistory/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

phistory/core.py

@@ -0,0 +1,225 @@
+import argparse
+import os
+import sys
+import shlex
+import subprocess
+from pathlib import Path
+from typing import Iterable, Optional, Tuple
+from datetime import datetime
+
+# Guard to avoid writing multiple times per process execution.
+_HISTORY_WRITTEN = False
+
+# Valid suboptions that may follow --history
+_HISTORY_SUBOPTS = {"date", "unique"}
+
+
+def _history_dir() -> Path:
+    """
+    Compute the history directory dynamically each time so changes to HOME
+    are respected. On Windows, prefer LOCALAPPDATA (then APPDATA).
+    - Windows: %LOCALAPPDATA%/Python/phistory/history
+    - Others : ~/.python-history
+    """
+    if os.name == "nt":
+        base = os.getenv("LOCALAPPDATA") or os.getenv("APPDATA")
+        if base:
+            return Path(base) / "Python" / "phistory" / "history"
+        # Fallback if env vars are missing
+        return Path.home() / "AppData" / "Local" / "Python" / "phistory" / "history"
+    # POSIX default
+    return Path.home() / ".python-history"
+
+
+def _script_name() -> str:
+    # Fall back to "script" if argv[0] is empty.
+    return os.path.basename(sys.argv[0]) or "script"
+
+
+def _history_file_for(script_name: Optional[str] = None) -> Path:
+    if script_name is None:
+        script_name = _script_name()
+    return _history_dir() / f"{script_name}.history"
+
+
+def _ensure_dir():
+    _history_dir().mkdir(parents=True, exist_ok=True)
+
+
+def _parse_history_options(argv: Iterable[str]) -> Tuple[bool, bool]:
+    """
+    Scan argv for --history and its optional suboptions.
+    Returns: (want_date, want_unique).
+    """
+    want_date = False
+    want_unique = False
+    tokens = list(argv)
+    for i, tok in enumerate(tokens):
+        if tok == "--history":
+            # Consume following suboptions while valid (order agnostic)
+            j = i + 1
+            while j < len(tokens) and tokens[j] in _HISTORY_SUBOPTS:
+                if tokens[j] == "date":
+                    want_date = True
+                elif tokens[j] == "unique":
+                    want_unique = True
+                j += 1
+            break
+    return want_date, want_unique
+
+
+def _filter_args(argv: Iterable[str]) -> list[str]:
+    """
+    Remove --history and its recognized suboptions from the provided argv.
+    Leave everything else intact.
+    """
+    filtered = []
+    it = iter(list(argv))
+    for a in it:
+        if a == "--history":
+            # Skip any recognized suboptions that immediately follow (max two)
+            consumed = 0
+            while consumed < 2:
+                try:
+                    nxt = next(it)
+                except StopIteration:
+                    break
+                if nxt in _HISTORY_SUBOPTS:
+                    consumed += 1
+                    continue
+                # Not a recognized suboption: push back into filtered
+                filtered.append(nxt)
+                break
+            continue
+        filtered.append(a)
+    return filtered
+
+
+def _join_args_for_shell(args: list[str]) -> str:
+    """
+    Platform-appropriate quoting for replayable commands.
+    - Windows: use subprocess.list2cmdline (CreateProcess/CommandLineToArgvW rules)
+    - POSIX  : use shlex.quote
+    """
+    if os.name == "nt":
+        return subprocess.list2cmdline(args)
+    return " ".join(shlex.quote(a) for a in args)
+
+
+def _record_invocation(argv: Optional[Iterable[str]] = None):
+    """
+    Append a single line to the history file.
+    Stored format: "<ISO_DATETIME>\t<commandline>"
+    ISO datetime uses seconds precision in local time.
+    """
+    global _HISTORY_WRITTEN
+    if _HISTORY_WRITTEN:
+        return
+    if argv is None:
+        argv = sys.argv[1:]
+
+    args_list = list(argv)
+    args_list = _filter_args(args_list)
+
+    # Compose a fully copy/paste-able command line: "<script> <args...>"
+    command = _script_name()
+    if args_list:
+        command += " " + _join_args_for_shell(args_list)
+
+    _ensure_dir()
+    hf = _history_file_for()
+    ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    with hf.open("a", encoding="utf-8") as f:
+        f.write(f"{ts}\t{command}\n")
+
+    _HISTORY_WRITTEN = True
+
+
+def _render_history_line(raw_line: str, want_date: bool) -> Optional[str]:
+    """
+    Render one history line for output depending on want_date.
+    History lines may be either:
+      1) "<ts>\t<command>" (new format), or
+      2) "<command>" (legacy format)
+    Returns the printable string, or None if the line is empty.
+    """
+    line = raw_line.rstrip("\n")
+    if not line:
+        return None
+    if "\t" in line:
+        ts, cmd = line.split("\t", 1)
+        return f"{ts} {cmd}" if want_date else cmd
+    # legacy format (no timestamp)
+    return line if not want_date else line  # no ts to show; print command only
+
+
+def _print_history_and_exit():
+    want_date, want_unique = _parse_history_options(sys.argv[1:])
+    hf = _history_file_for()
+    seen = set()
+    output = []
+
+    if hf.exists():
+        with hf.open("r", encoding="utf-8") as f:
+            for raw in f:
+                # For uniqueness, dedupe by the *command* part (strip timestamp if present)
+                dedupe_key = raw.split("\t", 1)[-1].rstrip("\n")
+                if want_unique:
+                    if dedupe_key in seen:
+                        continue
+                    seen.add(dedupe_key)
+                rendered = _render_history_line(raw, want_date=want_date)
+                if rendered is not None:
+                    output.append(rendered)
+
+    if output:
+        sys.stdout.write("\n".join(output) + "\n")
+    else:
+        # No history yet; keep output friendly but still copyable (empty)
+        sys.stdout.write("")
+    raise SystemExit(0)
+
+
+def _check_and_handle_history_flag():
+    if "--history" in sys.argv[1:]:
+        _print_history_and_exit()
+
+
+def _patch_argparse():
+    """Monkey-patch argparse to record once per process when parse_* is called."""
+    # Only patch once
+    if getattr(argparse.ArgumentParser, "_phistory_patched", False):
+        return
+
+    _orig_parse_args = argparse.ArgumentParser.parse_args
+    _orig_parse_known_args = argparse.ArgumentParser.parse_known_args
+
+    def _wrap_parse_args(self, args=None, namespace=None):
+        # Normalize incoming args (explicit or sys.argv) and strip --history so argparse won't error.
+        incoming = list(args) if args is not None else list(sys.argv[1:])
+        filtered = _filter_args(incoming)
+        # If args is None, pass None so argparse reads from sys.argv; we still record using filtered.
+        result = _orig_parse_args(self, args=filtered if args is not None else None, namespace=namespace)
+        _record_invocation(filtered)
+        return result
+
+    def _wrap_parse_known_args(self, args=None, namespace=None):
+        incoming = list(args) if args is not None else list(sys.argv[1:])
+        filtered = _filter_args(incoming)
+        result = _orig_parse_known_args(self, args=filtered if args is not None else None, namespace=namespace)
+        _record_invocation(filtered)
+        return result
+
+    argparse.ArgumentParser.parse_args = _wrap_parse_args
+    argparse.ArgumentParser.parse_known_args = _wrap_parse_known_args
+    argparse.ArgumentParser._phistory_patched = True  # sentinel
+
+
+def install():
+    """
+    Entry point called by package import.
+    - If '--history' present, print history (with options) and exit.
+    - Otherwise patch argparse to record on first parse.
+    """
+    _check_and_handle_history_flag()
+    _patch_argparse()

phistory/yaml_args.py

@@ -0,0 +1,156 @@
+"""
+phistory.yaml_args
+Ultra-minimal YAML-based argument loader to complement phistory's zero-config history.
+
+Usage:
+    from phistory import yaml_args
+    args = yaml_args.load()  # looks in PWD for "<script>.params.yaml"
+    # or: args = yaml_args.load("/path/to/params.yaml")
+
+Conventions:
+- Default params filename is derived from your script name and searched in the
+  current working directory (pwd): "<script_stem>.params.yaml".
+- If the user supplies a single positional argument (that does not start with "-"),
+  it is treated as the params file path (absolute or relative).
+- You can also pass params_file explicitly.
+
+Returns:
+- argparse.Namespace by default (attribute access), or a dict with as_namespace=False.
+"""
+
+from __future__ import annotations
+import os
+import re
+import sys
+from argparse import Namespace
+from pathlib import Path
+from typing import Any, Dict, Iterable, Mapping, Optional
+
+try:
+    import yaml  # type: ignore
+except Exception as e:  # pragma: no cover
+    raise RuntimeError(
+        "PyYAML is required for phistory.yaml_args. "
+        "Install with: pip install PyYAML"
+    ) from e
+
+
+def derive_params_filename(script_path: Optional[str] = None, suffix: str = ".params.yaml") -> str:
+    """
+    Derive "<script_stem>.params.yaml" from a script path.
+    Example: "/x/run_experiment.py" -> "run_experiment.params.yaml"
+    """
+    if not script_path:
+        script_path = sys.argv[0] or "script.py"
+    stem = re.sub(r"\.py$", "", os.path.basename(script_path))
+    return f"{stem}{suffix}"
+
+
+def load_yaml_params(params_filename: str) -> Dict[str, Any]:
+    """
+    Load YAML from disk.
+    - Raises FileNotFoundError if the file does not exist.
+    - Returns {} if the YAML is empty.
+    """
+    path = Path(params_filename)
+    if not path.exists():
+        raise FileNotFoundError(f"Parameters file not found: {params_filename}")
+    with path.open("r", encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def require_keys(params: Mapping[str, Any], required: Iterable[str]) -> None:
+    """Raise ValueError if any required key is missing."""
+    missing = [k for k in required if k not in params]
+    if missing:
+        raise ValueError(f"Missing required parameter(s) in YAML: {', '.join(missing)}")
+
+
+def _positional_argv_candidate() -> Optional[str]:
+    """
+    Return the first positional (non-flag) argument from sys.argv (if any).
+    Flags start with '-'. Only checks argv[1], in keeping with the "single argument" UX.
+    """
+    if len(sys.argv) >= 2:
+        first = sys.argv[1]
+        if first and not first.startswith("-"):
+            return first
+    return None
+
+
+def load(
+    params_file: Optional[str] = None,
+    required: Optional[Iterable[str]] = None,
+    *,
+    as_namespace: bool = True,
+) -> Namespace | Dict[str, Any]:
+    """
+    Load parameters from YAML with zero script-side config.
+
+    Resolution order:
+      1) If params_file is provided, use it.
+      2) Else if a single positional (non-flag) argv is present and points to an existing file, use it.
+      3) Else look in the current working directory for "<script_stem>.params.yaml".
+
+    Args:
+        params_file: optional path to YAML.
+        required:    optional iterable of required keys to enforce.
+        as_namespace: if True (default) return argparse.Namespace; else a dict.
+
+    Returns:
+        argparse.Namespace (default) or dict with the YAML keys as attributes/keys.
+    """
+    searched: list[str] = []
+
+    # 1) Explicit path wins
+    if params_file:
+        pf_path = Path(params_file)
+        searched.append(str(pf_path))
+        if not pf_path.exists():
+            raise FileNotFoundError(
+                f"Parameters file not found: {pf_path}"
+            )
+        params = load_yaml_params(str(pf_path))
+    else:
+        # 2) Single positional argv candidate
+        cand = _positional_argv_candidate()
+        if cand:
+            cand_path = Path(cand)
+            searched.append(str(cand_path))
+            if cand_path.exists():
+                params = load_yaml_params(str(cand_path))
+            else:
+                # 3) Fall back to default in PWD
+                default_name = derive_params_filename(sys.argv[0])
+                default_path = Path.cwd() / default_name
+                searched.append(str(default_path))
+                if not default_path.exists():
+                    raise FileNotFoundError(
+                        "Could not locate a parameters YAML.\n"
+                        f"Tried:\n  - {cand_path}\n  - {default_path}\n\n"
+                        "Tips:\n"
+                        "  • Put '<script_stem>.params.yaml' in the current working directory, or\n"
+                        "  • Provide a single positional argument with the path to the YAML, or\n"
+                        "  • Call yaml_args.load(params_file='/path/to/file.yaml')."
+                    )
+                params = load_yaml_params(str(default_path))
+        else:
+            # 3) Default in PWD
+            default_name = derive_params_filename(sys.argv[0])
+            default_path = Path.cwd() / default_name
+            searched.append(str(default_path))
+            if not default_path.exists():
+                raise FileNotFoundError(
+                    f"Parameters file not found in current directory: {default_path}\n"
+                    "Tips:\n"
+                    "  • Put '<script_stem>.params.yaml' in the current working directory, or\n"
+                    "  • Provide a single positional argument with the path to the YAML, or\n"
+                    "  • Call yaml_args.load(params_file='/path/to/file.yaml')."
+                )
+            params = load_yaml_params(str(default_path))
+
+    if required:
+        require_keys(params, required)
+
+    return Namespace(**params) if as_namespace else params
+

phistory-0.2.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: phistory
+Version: 0.2.0
+Summary: Zero-config argparse history recorder and replayer
+Author: amorriso
+License: MIT
+Project-URL: Homepage, https://github.com/amorriso/phistory
+Project-URL: Source, https://github.com/amorriso/phistory
+Project-URL: Issues, https://github.com/amorriso/phistory/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# phistory
+
+`phistory` makes Python scripts remember how they were run, and provides a
+small YAML parameter loader for scripts that do not use `argparse`.
+
+It supports Python 3.10+.
+
+---
+
+## Quickstart
+
+```python
+# myscript.py
+import phistory  # must be first
+import argparse
+
+p = argparse.ArgumentParser()
+p.add_argument("--foo")
+p.add_argument("bar")
+args = p.parse_args()
+print(args)
+```
+
+### Run
+
+```bash
+python myscript.py --foo 123 hello
+python myscript.py --foo 999 world
+python myscript.py --history
+# outputs:
+# myscript.py --foo 123 hello
+# myscript.py --foo 999 world
+```
+
+---
+
+## What it does
+
+- Saves each execution’s CLI (`script name + args`) to `~/.python-history/<script>.history`.
+- When run with `--history`, prints previous runs (copy/paste friendly) and exits.
+- Only writes history when your script calls `argparse.parse_args` or `parse_known_args`.
+- The `--history` flag itself is never recorded.
+
+**History directory:** `~/.python-history/`
+
+Use `--history date` to include timestamps, `--history unique` to show only
+the first occurrence of each command, or both options together.
+
+> `phistory` intentionally monkey-patches `argparse.ArgumentParser` when it is
+> imported. Import it before importing or configuring `argparse` in a script
+> that should record history.
+
+---
+
+## YAML args (no argparse required)
+
+Skip `argparse` entirely and just load parameters from YAML.
+
+```python
+from phistory import yaml_args
+
+args = yaml_args.load()  # looks for "<script>.params.yaml" in the current directory
+print(args.outpath)      # access fields as attributes
+```
+
+### Behavior
+
+- Default file: `<script_stem>.params.yaml` (e.g. `runner.params.yaml`)
+- You can also provide the path explicitly or as a single argument:
+  ```bash
+  python runner.py configs/myexp.yaml
+  ```
+- Validate required keys:
+  ```python
+  args = yaml_args.load(required=["experiment-name", "outpath", "description"])
+  ```
+
+### Helper functions
+
+```python
+from phistory import derive_params_filename, load_yaml_params
+```
+
+---
+
+## Installation
+
+```bash
+pip install phistory
+```
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

phistory-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+phistory/__init__.py,sha256=I5uxXrQpzOMRLqU_bJX0t1vkPPVFGJe2LRMnhD2xT0s,1130
+phistory/__version__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+phistory/core.py,sha256=7hmdhEW3R8A9W1GNsHARRNh6SkwMkCQT4Ke-sWpDzR8,7451
+phistory/yaml_args.py,sha256=TxtwW1WcCuL4IRvU6AGLPFqDWnHf93adTSEPH8g3Sjs,5836
+phistory-0.2.0.dist-info/licenses/LICENSE,sha256=xmHWdB9nNzwGSfRRXQYlj7Bpr-6e88v2BFgnBWww7gI,1060
+phistory-0.2.0.dist-info/METADATA,sha256=Jkg8VlcFUyCfO7ZZ1MYBSXNyvqrQ9tF-71sjVrlnO2I,3274
+phistory-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+phistory-0.2.0.dist-info/top_level.txt,sha256=u0os2XEPdcZq-jXjJBBlDerXYzff-6AUjHQeihmxmYk,9
+phistory-0.2.0.dist-info/RECORD,,

phistory-0.2.0.dist-info/WHEEL

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

phistory-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tmo
+
+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.

phistory-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+phistory