pam-python 0.2.1__tar.gz → 0.2.2__tar.gz

{pam_python-0.2.1/pam_python.egg-info → pam_python-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.1
+Version: 0.2.2
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -58,46 +58,42 @@ This README is a practical, step-by-step guide you can follow to create and run
 
 ---
 
-**Install**
-Recommended installation:
+**Create a uv project**
+
+Install PAM inside each project instead of installing the CLI globally:
 
 ```bash
 mkdir my_data_plugin
 cd my_data_plugin
-uv tool install pam-python
+uv init --python 3.12
+uv add pam-python
+uv run pam init
 ```
 
-Pip remains supported:
+`pam init` recognizes a fresh uv project, keeps its uv configuration, and adds
+the PAM scaffold. It refuses projects whose generated source files have already
+been edited.
+
+Pip remains supported for new projects that do not use uv:
 
 ```bash
+mkdir my_data_plugin
+cd my_data_plugin
 python3 -m venv venv
 source venv/bin/activate
 python -m pip install pam-python
-```
-
----
-
-**Initialize a Project**
-This creates a runnable project with templates, including `AGENT.md` for runtime
-rules and `REPORTS.md` for the managed-report public API and copyable examples.
-
-```bash
 pam init
 ```
 
-`pam init` asks you to select `uv` (default) or `pip`. A uv project contains
-`pyproject.toml`, `.python-version`, and `uv.lock`; a pip project contains
-`requirements.txt`. The two templates are independent and are never mixed.
-
-Initialization only supports a new project directory and will not migrate or
-overwrite an existing project.
+When run in an empty directory, `pam init` still asks whether to create a uv or
+pip project. PAM never migrates an existing application.
 
 ---
 
 **Create a Service**
 
 ```bash
-pam new service rfm_segment
+uv run pam new service rfm_segment
 ```
 
 The generator asks you to select Polars (default) or Pandas. Polars services use

{pam_python-0.2.1 → pam_python-0.2.2}/README.md

@@ -38,46 +38,42 @@ This README is a practical, step-by-step guide you can follow to create and run
 
 ---
 
-**Install**
-Recommended installation:
+**Create a uv project**
+
+Install PAM inside each project instead of installing the CLI globally:
 
 ```bash
 mkdir my_data_plugin
 cd my_data_plugin
-uv tool install pam-python
+uv init --python 3.12
+uv add pam-python
+uv run pam init
 ```
 
-Pip remains supported:
+`pam init` recognizes a fresh uv project, keeps its uv configuration, and adds
+the PAM scaffold. It refuses projects whose generated source files have already
+been edited.
+
+Pip remains supported for new projects that do not use uv:
 
 ```bash
+mkdir my_data_plugin
+cd my_data_plugin
 python3 -m venv venv
 source venv/bin/activate
 python -m pip install pam-python
-```
-
----
-
-**Initialize a Project**
-This creates a runnable project with templates, including `AGENT.md` for runtime
-rules and `REPORTS.md` for the managed-report public API and copyable examples.
-
-```bash
 pam init
 ```
 
-`pam init` asks you to select `uv` (default) or `pip`. A uv project contains
-`pyproject.toml`, `.python-version`, and `uv.lock`; a pip project contains
-`requirements.txt`. The two templates are independent and are never mixed.
-
-Initialization only supports a new project directory and will not migrate or
-overwrite an existing project.
+When run in an empty directory, `pam init` still asks whether to create a uv or
+pip project. PAM never migrates an existing application.
 
 ---
 
 **Create a Service**
 
 ```bash
-pam new service rfm_segment
+uv run pam new service rfm_segment
 ```
 
 The generator asks you to select Polars (default) or Pandas. Polars services use

{pam_python-0.2.1 → pam_python-0.2.2}/pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{pam_python-0.2.1 → pam_python-0.2.2}/pam/cli.py

@@ -8,6 +8,7 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import tomllib
 
 
 PROJECT_MARKER = ".pam-project"
@@ -159,6 +160,67 @@ def _assert_new_project(directory: Path):
         )
 
 
+def _requirement_name(requirement: str) -> str:
+    return re.split(r"[<>=!~;\s\[]", requirement, maxsplit=1)[0].lower()
+
+
+def _assert_fresh_uv_project(directory: Path):
+    pyproject_path = directory / "pyproject.toml"
+    try:
+        project = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))["project"]
+    except (OSError, tomllib.TOMLDecodeError, KeyError, TypeError) as exc:
+        raise FileExistsError(f"Invalid fresh uv project: {exc}") from exc
+
+    dependencies = project.get("dependencies", [])
+    if not isinstance(dependencies, list) or not any(
+        isinstance(item, str) and _requirement_name(item) == "pam-python"
+        for item in dependencies
+    ):
+        raise FileExistsError(
+            "Run `uv add pam-python` before `uv run pam init`"
+        )
+
+    python_version = directory / ".python-version"
+    if not python_version.is_file() or not python_version.read_text().strip().startswith("3.12"):
+        raise FileExistsError(
+            "A fresh uv project must pin Python 3.12; run `uv init --python 3.12`"
+        )
+
+    allowed = {
+        ".git",
+        ".gitignore",
+        ".python-version",
+        ".venv",
+        "README.md",
+        "main.py",
+        "pyproject.toml",
+        "uv.lock",
+    }
+    unexpected = sorted(path.name for path in directory.iterdir() if path.name not in allowed)
+    if unexpected:
+        raise FileExistsError(
+            "pam init only accepts a fresh uv project; existing files: "
+            + ", ".join(unexpected)
+        )
+
+    readme = directory / "README.md"
+    if readme.is_file() and readme.read_text(encoding="utf-8").strip():
+        raise FileExistsError("pam init will not overwrite a non-empty README.md")
+
+    main_file = directory / "main.py"
+    if main_file.is_file():
+        source = main_file.read_text(encoding="utf-8")
+        uv_placeholder = re.fullmatch(
+            r'def main\(\):\n'
+            r'    print\("Hello from [a-z0-9-]+!"\)\n\n\n'
+            r'if __name__ == "__main__":\n'
+            r'    main\(\)\n?',
+            source,
+        )
+        if uv_placeholder is None:
+            raise FileExistsError("pam init will not overwrite an edited main.py")
+
+
 def _run_uv(args: list[str], cwd: Path):
     uv = shutil.which("uv")
     if uv is None:
@@ -167,12 +229,20 @@ def _run_uv(args: list[str], cwd: Path):
 
 
 def init_project(package_manager: str | None = None):
-    package_manager = package_manager or _select_package_manager()
+    destination = Path.cwd()
+    preinitialized_uv = (destination / "pyproject.toml").is_file()
+    if preinitialized_uv:
+        if package_manager not in (None, "uv"):
+            raise FileExistsError("A uv project cannot be initialized as a pip project")
+        _assert_fresh_uv_project(destination)
+        package_manager = "uv"
+    else:
+        package_manager = package_manager or _select_package_manager()
+        _assert_new_project(destination)
+
     if package_manager not in PACKAGE_MANAGER_TEMPLATES:
         raise ValueError(f"Unsupported package manager: {package_manager}")
 
-    destination = Path.cwd()
-    _assert_new_project(destination)
     if package_manager == "uv" and shutil.which("uv") is None:
         raise RuntimeError("uv is required for this project but was not found on PATH")
 
@@ -184,6 +254,11 @@ def init_project(package_manager: str | None = None):
         **COMMON_PROJECT_TEMPLATES,
         **PACKAGE_MANAGER_TEMPLATES[package_manager],
     }
+    if preinitialized_uv:
+        templates = {
+            src: dest for src, dest in templates.items()
+            if dest not in {".gitignore", ".python-version", "pyproject.toml"}
+        }
 
     with tempfile.TemporaryDirectory(prefix=".pam-init-", dir=destination) as temp_dir:
         staging = Path(temp_dir)
@@ -202,7 +277,7 @@ def init_project(package_manager: str | None = None):
             encoding="utf-8",
         )
 
-        if package_manager == "uv":
+        if package_manager == "uv" and not preinitialized_uv:
             _run_uv(["lock"], staging)
 
         for path in staging.iterdir():

{pam_python-0.2.1 → pam_python-0.2.2/pam_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.1
+Version: 0.2.2
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python
@@ -58,46 +58,42 @@ This README is a practical, step-by-step guide you can follow to create and run
 
 ---
 
-**Install**
-Recommended installation:
+**Create a uv project**
+
+Install PAM inside each project instead of installing the CLI globally:
 
 ```bash
 mkdir my_data_plugin
 cd my_data_plugin
-uv tool install pam-python
+uv init --python 3.12
+uv add pam-python
+uv run pam init
 ```
 
-Pip remains supported:
+`pam init` recognizes a fresh uv project, keeps its uv configuration, and adds
+the PAM scaffold. It refuses projects whose generated source files have already
+been edited.
+
+Pip remains supported for new projects that do not use uv:
 
 ```bash
+mkdir my_data_plugin
+cd my_data_plugin
 python3 -m venv venv
 source venv/bin/activate
 python -m pip install pam-python
-```
-
----
-
-**Initialize a Project**
-This creates a runnable project with templates, including `AGENT.md` for runtime
-rules and `REPORTS.md` for the managed-report public API and copyable examples.
-
-```bash
 pam init
 ```
 
-`pam init` asks you to select `uv` (default) or `pip`. A uv project contains
-`pyproject.toml`, `.python-version`, and `uv.lock`; a pip project contains
-`requirements.txt`. The two templates are independent and are never mixed.
-
-Initialization only supports a new project directory and will not migrate or
-overwrite an existing project.
+When run in an empty directory, `pam init` still asks whether to create a uv or
+pip project. PAM never migrates an existing application.
 
 ---
 
 **Create a Service**
 
 ```bash
-pam new service rfm_segment
+uv run pam new service rfm_segment
 ```
 
 The generator asks you to select Polars (default) or Pandas. Polars services use

{pam_python-0.2.1 → pam_python-0.2.2}/tests/test_cli_templates.py

@@ -1,3 +1,4 @@
+import json
 import os
 from pathlib import Path
 import sys
@@ -114,6 +115,57 @@ class CLITemplateTest(unittest.TestCase):
                 calls,
             )
 
+    def test_init_adopts_a_fresh_uv_project_without_rewriting_uv_files(self):
+        calls = []
+        original_pyproject = """[project]
+name = "customer-plugin"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["pam-python>=0.2.1"]
+"""
+        uv_main = '''def main():
+    print("Hello from customer-plugin!")
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+        with tempfile.TemporaryDirectory() as temp_dir, WorkingDirectory(temp_dir):
+            root = Path(temp_dir)
+            (root / "pyproject.toml").write_text(original_pyproject)
+            (root / ".python-version").write_text("3.12\n")
+            (root / "uv.lock").write_text("version = 1\n")
+            (root / ".gitignore").write_text(".venv\n")
+            (root / "README.md").touch()
+            (root / "main.py").write_text(uv_main)
+
+            with mock.patch.object(cli.shutil, "which", return_value="/usr/bin/uv"), mock.patch.object(
+                cli, "_run_uv", side_effect=lambda args, cwd: calls.append(list(args))
+            ):
+                cli.init_project()
+
+            self.assertEqual(original_pyproject, (root / "pyproject.toml").read_text())
+            self.assertEqual("3.12\n", (root / ".python-version").read_text())
+            self.assertEqual("version = 1\n", (root / "uv.lock").read_text())
+            self.assertEqual(".venv\n", (root / ".gitignore").read_text())
+            self.assertIn("plugin_server = Server", (root / "main.py").read_text())
+            self.assertEqual("uv", json.loads((root / ".pam-project").read_text())["package_manager"])
+            self.assertEqual([], calls)
+
+    def test_init_rejects_an_edited_uv_project(self):
+        with tempfile.TemporaryDirectory() as temp_dir, WorkingDirectory(temp_dir):
+            root = Path(temp_dir)
+            (root / "pyproject.toml").write_text(
+                '[project]\nname = "plugin"\nversion = "0.1.0"\n'
+                'dependencies = ["pam-python"]\n'
+            )
+            (root / ".python-version").write_text("3.12\n")
+            (root / "main.py").write_text("print('real code')\n")
+
+            with self.assertRaisesRegex(FileExistsError, "edited main.py"):
+                cli.init_project()
+
     def test_init_rejects_an_existing_project_without_overwriting(self):
         with tempfile.TemporaryDirectory() as temp_dir, WorkingDirectory(temp_dir):
             original = Path("main.py")