phistory 0.2.0__tar.gz

phistory-0.2.0/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/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include phistory *.py
+recursive-include tests *.py

phistory-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,96 @@
+# 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/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-0.2.0/phistory/__version__.py

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

phistory-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-0.2.0/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/phistory.egg-info/PKG-INFO

@@ -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/phistory.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+phistory/__init__.py
+phistory/__version__.py
+phistory/core.py
+phistory/yaml_args.py
+phistory.egg-info/PKG-INFO
+phistory.egg-info/SOURCES.txt
+phistory.egg-info/dependency_links.txt
+phistory.egg-info/requires.txt
+phistory.egg-info/top_level.txt
+tests/test_phistory.py
+tests/test_yaml_args.py

phistory-0.2.0/phistory.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

phistory-0.2.0/phistory.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6.0

phistory-0.2.0/phistory.egg-info/top_level.txt

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

phistory-0.2.0/pyproject.toml

@@ -0,0 +1,7 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

phistory-0.2.0/setup.cfg

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

phistory-0.2.0/setup.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from setuptools import find_packages, setup
+
+ROOT = Path(__file__).parent
+version_ns = {}
+with open(ROOT / "phistory" / "__version__.py", "r", encoding="utf-8") as f:
+    exec(f.read(), version_ns)
+
+setup(
+    name="phistory",
+    version=version_ns["__version__"],
+    description="Zero-config argparse history recorder and replayer",
+    long_description=(ROOT / "README.md").read_text(encoding="utf-8"),
+    long_description_content_type="text/markdown",
+    author="amorriso",
+    license="MIT",
+    packages=find_packages(exclude=("tests",)),
+    python_requires=">=3.10",
+    install_requires=["PyYAML>=6.0"],
+    include_package_data=True,
+    project_urls={
+        "Homepage": "https://github.com/amorriso/phistory",
+        "Source": "https://github.com/amorriso/phistory",
+        "Issues": "https://github.com/amorriso/phistory/issues",
+    },
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development :: Libraries",
+    ],
+)

phistory-0.2.0/tests/test_phistory.py

@@ -0,0 +1,191 @@
+
+import importlib
+import os
+import sys
+from pathlib import Path
+import pytest
+
+
+def _reload_phistory_core():
+    """Reload phistory.core cleanly, without triggering auto-install on import."""
+    if "phistory.core" in sys.modules:
+        del sys.modules["phistory.core"]
+    if "phistory" in sys.modules:
+        del sys.modules["phistory"]
+    os.environ["PHISTORY_NO_AUTO_INSTALL"] = "1"
+    import phistory.core as core  # type: ignore
+    importlib.reload(core)
+    return core
+
+
+def _strip_ts_if_present(line: str) -> str:
+    """Return the command part of a history line regardless of timestamp presence."""
+    line = line.strip()
+    if "\t" in line:
+        return line.split("\t", 1)[1]
+    return line
+
+
+def test_records_invocation(tmp_path, monkeypatch):
+    # History should land under the tmp HOME
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("PYTHONIOENCODING", "utf-8")
+    script_name = "myscript.py"
+    monkeypatch.setattr(sys, "argv", [script_name, "--foo", "bar", "baz"])
+
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--foo")
+    parser.add_argument("positional")
+
+    import phistory  # noqa: F401  # installs hooks
+
+    ns = parser.parse_args()
+    assert ns.foo == "bar"
+    assert ns.positional == "baz"
+
+    hist_file = Path(tmp_path, ".python-history", f"{script_name}.history")
+    assert hist_file.exists()
+    content = hist_file.read_text(encoding="utf-8").strip().splitlines()
+    # The stored line is "<ts>\t<script> --foo bar baz". Compare command part only.
+    assert _strip_ts_if_present(content[-1]) == f"{script_name} --foo bar baz"
+
+
+def test_history_flag_prints_and_exits(tmp_path, monkeypatch, capsys):
+    script_name = "runme.py"
+    hist_dir = Path(tmp_path, ".python-history")
+    hist_dir.mkdir(parents=True, exist_ok=True)
+    hist_file = hist_dir / f"{script_name}.history"
+    # Legacy format (no timestamps) still supported
+    hist_file.write_text(
+        f"{script_name} --alpha 1\n{script_name} --beta two three\n",
+        encoding="utf-8",
+    )
+
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setattr(sys, "argv", [script_name, "--history"])
+
+    core = _reload_phistory_core()
+
+    with pytest.raises(SystemExit) as exc:
+        core.install()
+
+    assert exc.value.code == 0
+    out = capsys.readouterr().out
+    assert out.strip().splitlines() == [
+        f"{script_name} --alpha 1",
+        f"{script_name} --beta two three",
+    ]
+
+
+def test_ignores_history_flag_in_record(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    script_name = "cli.py"
+    monkeypatch.setattr(sys, "argv", [script_name])
+
+    # Reset modules so _HISTORY_WRITTEN is fresh
+    sys.modules.pop("phistory.core", None)
+    sys.modules.pop("phistory", None)
+    monkeypatch.delenv("PHISTORY_NO_AUTO_INSTALL", raising=False)
+
+    # 🔑 Also clear the argparse sentinel so a fresh patch is applied.
+    import argparse
+    if hasattr(argparse.ArgumentParser, "_phistory_patched"):
+        delattr(argparse.ArgumentParser, "_phistory_patched")
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--x")
+
+    import phistory  # noqa: F401  # installs hooks fresh
+
+    # Explicitly include --history in args; phistory must filter it out.
+    ns = parser.parse_args(["--history", "--x", "y"])
+    assert ns.x == "y"
+
+    hist_path = Path(tmp_path, ".python-history", f"{script_name}.history")
+    assert hist_path.exists()
+    lines = hist_path.read_text(encoding="utf-8").strip().splitlines()
+    assert _strip_ts_if_present(lines[-1]) == f"{script_name} --x y"
+
+
+def test_history_date_option_prints_timestamps(tmp_path, monkeypatch, capsys):
+    script_name = "show.py"
+    hist_dir = Path(tmp_path, ".python-history")
+    hist_dir.mkdir(parents=True, exist_ok=True)
+    hist_file = hist_dir / f"{script_name}.history"
+    hist_file.write_text(
+        "2024-12-31 23:59:59\tshow.py --a 1\n"
+        "2025-01-01 00:00:00\tshow.py --b 2 3\n",
+        encoding="utf-8",
+    )
+
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setattr(sys, "argv", [script_name, "--history", "date"])
+
+    core = _reload_phistory_core()
+    with pytest.raises(SystemExit) as exc:
+        core.install()
+    assert exc.value.code == 0
+
+    out_lines = capsys.readouterr().out.strip().splitlines()
+    assert out_lines == [
+        "2024-12-31 23:59:59 show.py --a 1",
+        "2025-01-01 00:00:00 show.py --b 2 3",
+    ]
+
+
+def test_history_unique_option_dedupes(tmp_path, monkeypatch, capsys):
+    script_name = "dedupe.py"
+    hist_dir = Path(tmp_path, ".python-history")
+    hist_dir.mkdir(parents=True, exist_ok=True)
+    hist_file = hist_dir / f"{script_name}.history"
+    # Two identical commands with different timestamps + one unique
+    hist_file.write_text(
+        "2025-01-01 10:00:00\tdedupe.py --x 1\n"
+        "2025-01-01 10:05:00\tdedupe.py --x 1\n"
+        "2025-01-01 10:10:00\tdedupe.py --y 2\n",
+        encoding="utf-8",
+    )
+
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setattr(sys, "argv", [script_name, "--history", "unique"])
+
+    core = _reload_phistory_core()
+    with pytest.raises(SystemExit) as exc:
+        core.install()
+    assert exc.value.code == 0
+
+    # With 'unique' only, dates are not shown; expect first occurrence only.
+    out_lines = capsys.readouterr().out.strip().splitlines()
+    assert out_lines == [
+        "dedupe.py --x 1",
+        "dedupe.py --y 2",
+    ]
+
+
+def test_history_date_unique_together(tmp_path, monkeypatch, capsys):
+    script_name = "both.py"
+    hist_dir = Path(tmp_path, ".python-history")
+    hist_dir.mkdir(parents=True, exist_ok=True)
+    hist_file = hist_dir / f"{script_name}.history"
+    hist_file.write_text(
+        "2025-01-01 10:00:00\tboth.py --x 1\n"
+        "2025-01-01 10:05:00\tboth.py --x 1\n"  # duplicate command
+        "2025-01-01 10:10:00\tboth.py --y 2\n",
+        encoding="utf-8",
+    )
+
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setattr(sys, "argv", [script_name, "--history", "date", "unique"])
+
+    core = _reload_phistory_core()
+    with pytest.raises(SystemExit) as exc:
+        core.install()
+    assert exc.value.code == 0
+
+    # With 'date unique', include the timestamp of the first occurrence only.
+    out_lines = capsys.readouterr().out.strip().splitlines()
+    assert out_lines == [
+        "2025-01-01 10:00:00 both.py --x 1",
+        "2025-01-01 10:10:00 both.py --y 2",
+    ]

phistory-0.2.0/tests/test_yaml_args.py

@@ -0,0 +1,44 @@
+# tests/test_yaml_args.py
+from pathlib import Path
+from phistory import yaml_args, derive_params_filename, load_yaml_params
+import pytest
+
+def test_derive_params_filename():
+    assert yaml_args.derive_params_filename("/x/run.py") == "run.params.yaml"
+    assert derive_params_filename("/x/runner.py") == "runner.params.yaml"
+
+def test_load_yaml_and_required(tmp_path: Path, monkeypatch):
+    # Prepare a params file in a temp PWD
+    pf = tmp_path / "runner.params.yaml"
+    pf.write_text("outpath: out\ndescription: d\nexperiment-name: e\n", encoding="utf-8")
+
+    # Make PWD be tmp_path so default discovery works (searches PWD)
+    monkeypatch.chdir(tmp_path)
+
+    # default discovery uses sys.argv[0] to derive name, but file is in PWD
+    monkeypatch.setenv("PYTHONIOENCODING", "utf-8")
+    monkeypatch.setattr("sys.argv", ["runner.py"])
+
+    args = yaml_args.load()
+    assert args.outpath == "out"
+
+    # required OK
+    yaml_args.load(required=["experiment-name", "outpath", "description"])
+
+    # missing required key should raise
+    pf.write_text("outpath: out\n", encoding="utf-8")
+    with pytest.raises(ValueError):
+        yaml_args.load(required=["experiment-name"])
+
+def test_single_positional_argument_path(tmp_path: Path, monkeypatch):
+    # Create a YAML in a non-PWD directory
+    custom = tmp_path / "custom.yaml"
+    custom.write_text("alpha: 42\nbeta: true\n", encoding="utf-8")
+
+    # Keep current PWD as-is; pass the path as the single positional arg
+    monkeypatch.setattr("sys.argv", ["runner.py", str(custom)])
+
+    args = yaml_args.load()
+    assert args.alpha == 42
+    assert args.beta is True
+