py-env-studio 2.1.3__tar.gz → 2.1.4__tar.gz

{py_env_studio-2.1.3/py_env_studio.egg-info → py_env_studio-2.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-env-studio
-Version: 2.1.3
+Version: 2.1.4
 Summary: A comprehensive cross-platform GUI and CLI tool for managing Python virtual environments and packages with advanced features including environment lifecycle management, package operations, vulnerability scanning, security insights, project templates, Py-Tonic interactive learning mode, an extensible plugin system for custom functionality, and a local read-only MCP control plane (beta) for AI coding agents.
 Author-email: Py Env Studio Team <contact.shaikh.wasim@gmail.com>
 License: MIT License
@@ -109,7 +109,7 @@ Perfect for:
 - 🔌 Extensible **plugin system** with 18 lifecycle hooks
 - 📟 Full CLI with progress gauge and `-v` / `-q` / `--no-progress` controls
 - 🧪 **Beta:** local, read-only **MCP control plane** for AI coding agents
-  (stdio transport, 8 `pyenv_*` tools, opt-out via `enabled = false`)
+  (stdio transport, 8 `pes_*` tools, opt-out via `enabled = false`)
 
 ## 📥 Installation
 
@@ -161,7 +161,7 @@ Setup steps for VS Code and other clients:
 
 - Documentation home: [https://py-env-studio.readthedocs.io/](https://py-env-studio.readthedocs.io/)
 - Usage manual: [https://py-env-studio.readthedocs.io/en/latest/getting-started/usage.html](https://py-env-studio.readthedocs.io/en/latest/getting-started/usage.html)
-- Release notes: [https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.2.html](https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.2.html)
+- Release notes: [https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.4.html](https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.4.html)
 - Source code: [https://github.com/pyenvstudio/py-env-studio](https://github.com/pyenvstudio/py-env-studio)
 - Issue tracker: [https://github.com/pyenvstudio/py-env-studio/issues](https://github.com/pyenvstudio/py-env-studio/issues)
 

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/PYPI_README.md

@@ -44,7 +44,7 @@ Perfect for:
 - 🔌 Extensible **plugin system** with 18 lifecycle hooks
 - 📟 Full CLI with progress gauge and `-v` / `-q` / `--no-progress` controls
 - 🧪 **Beta:** local, read-only **MCP control plane** for AI coding agents
-  (stdio transport, 8 `pyenv_*` tools, opt-out via `enabled = false`)
+  (stdio transport, 8 `pes_*` tools, opt-out via `enabled = false`)
 
 ## 📥 Installation
 
@@ -96,7 +96,7 @@ Setup steps for VS Code and other clients:
 
 - Documentation home: [https://py-env-studio.readthedocs.io/](https://py-env-studio.readthedocs.io/)
 - Usage manual: [https://py-env-studio.readthedocs.io/en/latest/getting-started/usage.html](https://py-env-studio.readthedocs.io/en/latest/getting-started/usage.html)
-- Release notes: [https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.2.html](https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.2.html)
+- Release notes: [https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.4.html](https://py-env-studio.readthedocs.io/en/latest/releases/v2.1.4.html)
 - Source code: [https://github.com/pyenvstudio/py-env-studio](https://github.com/pyenvstudio/py-env-studio)
 - Issue tracker: [https://github.com/pyenvstudio/py-env-studio/issues](https://github.com/pyenvstudio/py-env-studio/issues)
 

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/README.md

@@ -29,26 +29,23 @@ Perfect for:
 
 ---
 
-## 🆕 What's new in v2.1.2
-
-- 🧪 **MCP control plane (beta)** — a local, read-only MCP server lets AI coding
-  agents (VS Code Copilot and other MCP clients) read authoritative
-  environment, package, dependency, security, and project state.
-  → [Setup steps](docs/reference/mcp.md)
-- 🧩 **Project templates** — built-in Python Script / CLI / Package templates,
-  your own templates from a local folder or GitHub, and GitHub
-  **Community Templates** discovery.
-- ⚙️ **Configuration center** (Tools → Configuration) — default venv path,
-  interpreter/runtime, package manager, project tool, template defaults,
-  appearance, and UI scaling in one validated dialog.
-- 🐍 **Official Python Install Manager integration** — detect, list, install,
-  and select official runtimes, with System/Custom providers alongside.
-- 🛡️ **Remediate from the dashboard** — `Update Now` per vulnerability and
-  `Upgrade all Packages` per environment, with partial-failure reporting.
-- 📊 **Native dashboard charts** (`tkinter-dash`, no matplotlib), 📶 a CLI
-  progress gauge and GUI status gauge, and consistent application icons.
-
-→ [Full v2.1.2 release notes](docs/releases/v2.1.2.md)
+## 🆕 What's new in v2.1.4
+
+- 🔗 **Project ↔ Environment association** — creating an environment from a
+  project template now registers it with the project by default, with an
+  explicit opt-out that creates an unregistered environment.
+- 🗂️ **Project environment panel** (Project menu) — view the environment
+  associated with a project, switch the association to another PES
+  environment, or unregister it without deleting the environment.
+- 🛡️ **Runtime mismatch guard** — PES compares the project's registered
+  environment with the runtime it can reliably observe, stays silent on a
+  match, and surfaces mismatches through `pes status`, `pes on`, and `pes run`
+  (warning once per unchanged mismatch).
+- 👁️ **Conservative runtime detection** — PES only reports runtime information
+  it can observe; it does not infer which interpreter VS Code or PyCharm
+  selected, does not switch IDE interpreters, and needs no IDE extension.
+
+→ [Full v2.1.4 release notes](docs/releases/v2.1.4.md)
 
 ---
 
@@ -105,7 +102,7 @@ PyEnvStudio now features a powerful plugin system that allows developers to exte
 - **Easy Development** - Simple plugin API with lifecycle management
 - **Examples Included** - Full working sample plugin with documentation
 
-See the [v2.1.2 release notes](docs/releases/v2.1.2.md) and the [plugin development guide](docs/plugins/development.md).
+See the [v2.1.4 release notes](docs/releases/v2.1.4.md) and the [plugin development guide](docs/plugins/development.md).
 
 ### Additional implemented capabilities
 

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/py_env_studio/commands.py

@@ -20,6 +20,12 @@ from py_env_studio.core.runtime_toggle import (
     init_project,
     list_registered_projects,
 )
+from py_env_studio.core.runtime_mismatch import (
+    RuntimeMatchState,
+    clear_mismatch_notification,
+    detect_runtime_mismatch,
+    notify_mismatch_once,
+)
 from py_env_studio.utils.app_logging import configure_logging
 from py_env_studio.utils.progress import TaskProgress
 
@@ -147,6 +153,7 @@ def handle_init(_: argparse.Namespace) -> None:
 
 
 def handle_on(_: argparse.Namespace) -> None:
+    _notify_runtime_mismatch()
     _print_runtime_result(enable_runtime())
 
 
@@ -166,6 +173,34 @@ def handle_status(_: argparse.Namespace) -> None:
         print(f"Environment Path: {status.get('environment_path', 'N/A')}")
         print(f"Python Version: {status['python_version']}")
 
+    root = Path(status["project_root"]) if status.get("project_root") else None
+    runtime = detect_runtime_mismatch(root)
+    if runtime.registered_environment_id:
+        print("Registered environment:")
+        print(f"  {runtime.registered_environment_id}")
+        print(f"  Python {runtime.registered_python_version or 'Unknown'}")
+    else:
+        print("Registered environment: None")
+    if runtime.current_python_executable:
+        print("Current runtime:")
+        print(f"  {runtime.current_python_executable}")
+        print(f"  Python {runtime.current_python_version or 'Unknown'}")
+    state_label = (
+        "ENVIRONMENT_MISMATCH"
+        if runtime.state is RuntimeMatchState.MISMATCH
+        else runtime.state.value
+    )
+    print(f"Status: {state_label}")
+
+
+def _notify_runtime_mismatch() -> None:
+    runtime = detect_runtime_mismatch()
+    if runtime.state is RuntimeMatchState.MISMATCH:
+        if notify_mismatch_once(runtime):
+            print("Environment mismatch detected")
+    elif runtime.state is RuntimeMatchState.MATCH and runtime.project_path:
+        clear_mismatch_notification(runtime.project_path)
+
 
 def handle_list_projects(_: argparse.Namespace) -> None:
     projects = list_registered_projects()
@@ -188,6 +223,7 @@ def handle_run(args: argparse.Namespace) -> None:
 
     # No gauge here: the child process owns the terminal and its output must
     # not be interleaved with redrawn status lines.
+    _notify_runtime_mismatch()
     logger.info("Running %s in the managed environment", list(args.args))
     result = execute_in_managed_env(Path.cwd(), list(args.args))
     if result:

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/py_env_studio/config.ini

@@ -1,5 +1,5 @@
 [project]
-version = 2.1.3
+version = 2.1.4
 
 [settings]
 venv_dir = ~/.py_env_studio/venvs

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/py_env_studio/core/mcp/tools/__init__.py

@@ -6,7 +6,7 @@ from . import analysis, environments, packages, project, security
 
 TOOL_DEFINITIONS = [
     {
-        "name": "pyenv_list_environments",
+        "name": "pes_list_environments",
         "description": "List Python environments known to Py Env Studio.",
         "inputSchema": {
             "type": "object",
@@ -16,7 +16,7 @@ TOOL_DEFINITIONS = [
         "handler": environments.list_environments,
     },
     {
-        "name": "pyenv_get_environment",
+        "name": "pes_get_environment",
         "description": "Return detailed information about one environment.",
         "inputSchema": {
             "type": "object",
@@ -27,7 +27,7 @@ TOOL_DEFINITIONS = [
         "handler": environments.get_environment,
     },
     {
-        "name": "pyenv_list_packages",
+        "name": "pes_list_packages",
         "description": "List installed packages in an environment (pip/uv aware).",
         "inputSchema": {
             "type": "object",
@@ -38,7 +38,7 @@ TOOL_DEFINITIONS = [
         "handler": packages.list_packages,
     },
     {
-        "name": "pyenv_get_project_context",
+        "name": "pes_get_project_context",
         "description": "Authoritative project/environment/runtime context for the current project.",
         "inputSchema": {
             "type": "object",
@@ -48,7 +48,7 @@ TOOL_DEFINITIONS = [
         "handler": project.get_project_context,
     },
     {
-        "name": "pyenv_get_environment_status",
+        "name": "pes_get_environment_status",
         "description": "Concise machine-readable environment status.",
         "inputSchema": {
             "type": "object",
@@ -59,7 +59,7 @@ TOOL_DEFINITIONS = [
         "handler": environments.get_environment_status,
     },
     {
-        "name": "pyenv_scan_vulnerabilities",
+        "name": "pes_scan_vulnerabilities",
         "description": "Return cached vulnerability findings for an environment (no network scan).",
         "inputSchema": {
             "type": "object",
@@ -70,7 +70,7 @@ TOOL_DEFINITIONS = [
         "handler": security.scan_vulnerabilities,
     },
     {
-        "name": "pyenv_get_dependency_information",
+        "name": "pes_get_dependency_information",
         "description": "Expose local dependency information (pip show based, offline).",
         "inputSchema": {
             "type": "object",
@@ -84,7 +84,7 @@ TOOL_DEFINITIONS = [
         "handler": project.get_dependency_information,
     },
     {
-        "name": "pyenv_analyze_project",
+        "name": "pes_analyze_project",
         "description": "Analyze a Python project using Py Env Studio and return authoritative environment, Python runtime, package manager, dependency, outdated-package, vulnerability, runtime, and PES project configuration information. This operation is read-only and does not modify the project or environment.",
         "inputSchema": {
             "type": "object",
@@ -94,7 +94,7 @@ TOOL_DEFINITIONS = [
         "handler": analysis.analyze_project,
     },
     {
-        "name": "pyenv_check_consistency",
+        "name": "pes_check_consistency",
         "description": "Before modifying any Python project's dependencies or running its tests, call this to determine which interpreter, environment, lockfile, and manifest the project actually uses, and whether they agree.",
         "inputSchema": {
             "type": "object",

py_env_studio-2.1.4/py_env_studio/core/runtime_mismatch.py

@@ -0,0 +1,133 @@
+"""Conservative comparison of a project's PES environment and a known runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from hashlib import sha256
+from pathlib import Path
+import os
+import sys
+
+from . import env_manager, runtime_toggle
+
+
+class RuntimeMatchState(str, Enum):
+    MATCH = "MATCH"
+    MISMATCH = "MISMATCH"
+    REGISTERED_ENVIRONMENT_UNAVAILABLE = "REGISTERED_ENVIRONMENT_UNAVAILABLE"
+    NO_PROJECT_ASSOCIATION = "NO_PROJECT_ASSOCIATION"
+    UNKNOWN = "UNKNOWN"
+
+
+@dataclass(frozen=True)
+class DetectedRuntime:
+    """Runtime facts supplied by PES or a future integration adapter."""
+
+    executable: str | None
+    python_version: str | None
+    reliable: bool = True
+
+
+@dataclass(frozen=True)
+class RuntimeMismatch:
+    project_path: str | None
+    project_name: str | None
+    registered_environment_id: str | None
+    registered_python_executable: str | None
+    registered_python_version: str | None
+    current_python_executable: str | None
+    current_python_version: str | None
+    state: RuntimeMatchState
+
+
+def _process_runtime() -> DetectedRuntime:
+    """Return the interpreter running PES, not an IDE's selected interpreter."""
+    version = sys.version_info
+    return DetectedRuntime(
+        executable=sys.executable or None,
+        python_version=f"{version.major}.{version.minor}.{version.micro}",
+        reliable=bool(sys.executable),
+    )
+
+
+def _canonical_path(path: str) -> str:
+    return os.path.normcase(str(Path(path).resolve()))
+
+
+def detect_runtime_mismatch(
+    project_root: Path | str | None = None,
+    current_runtime: DetectedRuntime | None = None,
+) -> RuntimeMismatch:
+    """Compare registered and current executables without inferring IDE state."""
+    root = Path(project_root).resolve() if project_root is not None else runtime_toggle.get_project_root()
+    metadata = runtime_toggle.load_project_metadata(root) if root else {}
+    runtime = current_runtime if current_runtime is not None else _process_runtime()
+    env_id = metadata.get("environment_id") or None
+
+    registered_executable = None
+    registered_version = None
+    state = RuntimeMatchState.UNKNOWN
+    if not env_id:
+        state = RuntimeMatchState.NO_PROJECT_ASSOCIATION
+    else:
+        info = env_manager.get_environment_info(str(env_id))
+        if info is None:
+            state = RuntimeMatchState.REGISTERED_ENVIRONMENT_UNAVAILABLE
+        else:
+            registered_executable = str(info.get("python_executable") or "") or None
+            registered_version = info.get("python_version") or metadata.get("python_version") or None
+            if not registered_executable or not Path(registered_executable).is_file():
+                state = RuntimeMatchState.REGISTERED_ENVIRONMENT_UNAVAILABLE
+            elif not runtime.reliable or not runtime.executable or not Path(runtime.executable).is_file():
+                state = RuntimeMatchState.UNKNOWN
+            else:
+                same_executable = _canonical_path(registered_executable) == _canonical_path(runtime.executable)
+                if same_executable:
+                    if runtime.python_version and registered_version and runtime.python_version != registered_version:
+                        state = RuntimeMatchState.MISMATCH
+                    elif runtime.python_version:
+                        state = RuntimeMatchState.MATCH
+                else:
+                    state = RuntimeMatchState.MISMATCH
+
+    return RuntimeMismatch(
+        project_path=str(root) if root else None,
+        project_name=metadata.get("project_name") if metadata else (root.name if root else None),
+        registered_environment_id=str(env_id) if env_id else None,
+        registered_python_executable=registered_executable,
+        registered_python_version=str(registered_version) if registered_version else None,
+        current_python_executable=runtime.executable,
+        current_python_version=runtime.python_version,
+        state=state,
+    )
+
+
+def notify_mismatch_once(result: RuntimeMismatch) -> bool:
+    """Persist a per-project mismatch signature and report only new mismatches."""
+    if result.state is not RuntimeMatchState.MISMATCH or not result.project_path:
+        return False
+
+    signature_data = "\0".join(
+        str(value or "")
+        for value in (
+            result.registered_environment_id,
+            result.registered_python_executable,
+            result.registered_python_version,
+            result.current_python_executable,
+            result.current_python_version,
+        )
+    )
+    signature = sha256(signature_data.encode("utf-8")).hexdigest()
+    root = Path(result.project_path)
+    if runtime_toggle.get_last_mismatch_signature(root) == signature:
+        return False
+    runtime_toggle.set_last_mismatch_signature(root, signature)
+    return True
+
+
+def clear_mismatch_notification(project_root: Path | str) -> None:
+    """Allow a later recurrence to notify after a project returns to a match."""
+    root = Path(project_root).resolve()
+    if runtime_toggle.get_last_mismatch_signature(root):
+        runtime_toggle.set_last_mismatch_signature(root, "")

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/py_env_studio/core/runtime_toggle.py

@@ -104,6 +104,7 @@ def save_project_metadata(project_root: Path, metadata: dict) -> None:
         parser["runtime"] = {
             "enabled": str(metadata.get("runtime_enabled", False)).lower(),
             "auto_init": str(metadata.get("auto_init", True)).lower(),
+            "last_mismatch_signature": metadata.get("last_mismatch_signature", ""),
         }
         with open(metadata_path, "w", encoding="utf-8") as f:
             parser.write(f)
@@ -112,6 +113,20 @@ def save_project_metadata(project_root: Path, metadata: dict) -> None:
         raise
 
 
+def get_last_mismatch_signature(project_root: Path) -> str:
+    """Read notification suppression state without expanding public metadata."""
+    parser = ConfigParser()
+    parser.read(get_project_metadata_path(project_root), encoding="utf-8")
+    return parser.get("runtime", "last_mismatch_signature", fallback="")
+
+
+def set_last_mismatch_signature(project_root: Path, signature: str) -> None:
+    """Persist a mismatch notification signature in the existing project file."""
+    metadata = load_project_metadata(project_root)
+    metadata["last_mismatch_signature"] = signature
+    save_project_metadata(project_root, metadata)
+
+
 def load_registry() -> dict:
     """Load the global registry."""
     import json
@@ -142,6 +157,70 @@ def save_registry(registry: dict) -> None:
         raise
 
 
+def associate_environment_with_project(
+    project_root: Path,
+    environment_id: str,
+) -> None:
+    """Associate an existing PES environment with a project."""
+    from . import env_manager
+
+    project_root = Path(project_root).resolve()
+    env_info = env_manager.get_environment_info(environment_id)
+    if env_info is None:
+        raise FileNotFoundError(f"Environment '{environment_id}' is unavailable")
+
+    metadata = load_project_metadata(project_root)
+    metadata.update(
+        {
+            "project_name": metadata.get("project_name", project_root.name),
+            "project_root": str(project_root),
+            "environment_id": environment_id,
+            "environment_path": env_info.get("path", ""),
+            "python_version": env_info.get("python_version") or "",
+            "package_manager": env_info.get("package_manager", "pip"),
+            "runtime_enabled": metadata.get("runtime_enabled", True),
+            "auto_init": metadata.get("auto_init", True),
+        }
+    )
+    save_project_metadata(project_root, metadata)
+
+    registry = load_registry()
+    project_name = metadata["project_name"]
+    project_entry = registry.setdefault(project_name, {})
+    project_entry.update(
+        {
+            "project_root": str(project_root),
+            "environment_id": environment_id,
+            "environment_path": metadata["environment_path"],
+            "python_version": metadata["python_version"],
+            "runtime_enabled": metadata["runtime_enabled"],
+        }
+    )
+    save_registry(registry)
+
+
+def unregister_project_environment(project_root: Path) -> None:
+    """Remove a project's environment association without deleting the environment."""
+    project_root = Path(project_root).resolve()
+    metadata = load_project_metadata(project_root)
+    metadata.update(
+        {
+            "project_name": metadata.get("project_name", project_root.name),
+            "project_root": str(project_root),
+            "environment_id": "",
+            "environment_path": "",
+            "last_mismatch_signature": "",
+        }
+    )
+    save_project_metadata(project_root, metadata)
+
+    registry = load_registry()
+    project_entry = registry.get(metadata["project_name"])
+    if project_entry and Path(project_entry.get("project_root", "")).resolve() == project_root:
+        project_entry.update({"environment_id": "", "environment_path": "", "python_version": ""})
+        save_registry(registry)
+
+
 def generate_environment_id(project_name: str) -> str:
     """Generate a unique environment ID for a project."""
     import hashlib

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/py_env_studio/core/templates/engine.py

@@ -37,6 +37,11 @@ class TemplateEngine:
     def __init__(self, registry: TemplateRegistry | None = None) -> None:
         self.registry = registry or get_default_registry()
 
+    @staticmethod
+    def environment_name_for_project(project_name: str) -> str:
+        """Return the generated environment name for a project name."""
+        return f"{project_name.strip().lower().replace(' ', '-')}-env".replace("_", "-")[:45]
+
     def list_templates(self):
         return self.registry.list_all()
 
@@ -98,6 +103,7 @@ class TemplateEngine:
                     project_path=project_path,
                     template=template,
                     log_callback=log_callback,
+                    associate_with_project=request.associate_environment_with_project,
                 )
                 deps = list(template.runtime_dependencies)
                 if request.install_dev_dependencies:
@@ -214,9 +220,10 @@ class TemplateEngine:
         self._log(log_callback, "Initializing git repository")
         subprocess.run(["git", "init"], cwd=project_path, check=False, capture_output=True, text=True)
 
-    def _create_and_configure_environment(self, request, project_path, template, log_callback):
-        env_name = f"{request.project_name.strip().lower().replace(' ', '-')}-env"
-        env_name = env_name.replace("_", "-")[:45]
+    def _create_and_configure_environment(
+        self, request, project_path, template, log_callback, associate_with_project=True
+    ):
+        env_name = self.environment_name_for_project(request.project_name)
         self._log(log_callback, f"Creating virtual environment: {env_name}")
 
         python_path = self._resolve_python_interpreter(request.python_version)
@@ -233,22 +240,16 @@ class TemplateEngine:
             log_callback=log_callback,
         )
 
-        from ..runtime_toggle import save_project_metadata
-
-        env_path = str(Path(env_manager.VENV_DIR) / env_name)
-        save_project_metadata(
-            Path(project_path),
-            {
-                "project_name": request.project_name,
-                "environment_id": env_name,
-                "environment_path": env_path,
-                "python_version": request.python_version,
-                "package_manager": env_manager.get_preferred_package_manager(),
-                "runtime_enabled": True,
-                "auto_init": True,
-            },
-        )
-        self._log(log_callback, "Configured project interpreter metadata")
+        if associate_with_project:
+            from ..runtime_toggle import associate_environment_with_project
+
+            associate_environment_with_project(
+                Path(project_path),
+                env_name,
+            )
+            self._log(log_callback, "Associated environment with project")
+        else:
+            self._log(log_callback, "Created environment without associating it with the project")
         return env_name
 
     def _resolve_python_interpreter(self, requested_version: str) -> str | None:

{py_env_studio-2.1.3 → py_env_studio-2.1.4}/py_env_studio/core/templates/models.py

@@ -55,6 +55,7 @@ class TemplateCreationRequest:
     author: Optional[str] = None
     license_name: Optional[str] = None
     install_dev_dependencies: bool = True
+    associate_environment_with_project: bool = True
 
 
 @dataclass