evok 0.1.0__tar.gz

evok-0.1.0/LICENSE

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

evok-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: evok
+Version: 0.1.0
+Summary: Pure-Python high-performance packaging engine and virtualization runtime
+Author: ellainng
+Author-email: ellainng <299958882+ellainng@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Evok (`ev`)
+
+[![CI](https://github.com/wispsy/evok/actions/workflows/ci.yml/badge.svg)](https://github.com/wispsy/evok/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+> **Pure-Python high-performance package manager and zero-venv virtualization runtime.**
+
+Evok demonstrates that a clean-slate Python implementation leveraging modern OS primitives and stdlib capabilities can reach ~80% of `uv`'s speed while delivering native capabilities that compiled binaries cannot provide: first-class in-process APIs, zero-venv `sys.meta_path` virtualization, dynamic AST dependency inference, and single-file zero-binary `.pyz` bootstrapping.
+
+---
+
+## Key Highlights
+
+- **Zero-Copy Reflink Cache**: Unpacks wheels once into a global cache and installs in milliseconds using macOS APFS `clonefile`, Linux `FICLONE`, and hardlink (`os.link`) fallbacks.
+- **Bit-Packed PEP 440 Arithmetic**: Encodes release segments and lifecycle stages into single 64-bit scalar integers for microsecond comparisons.
+- **Async Metadata & Range Tail-Reads**: Fetches package metadata from remote ZIP central directories using HTTP Range requests without downloading full wheels.
+- **Zero-Venv Virtualization**: Run code with in-process `sys.meta_path` hooks that load dependencies directly from the cache without creating a `.venv` directory on disk.
+- **AST Dependency Scanner**: Scans project source code to automatically detect third-party imports, flag missing packages, and prune unused/dead dependencies.
+- **Pure-Python Wheel & Sdist Builder**: Standards-compliant PEP 427 wheel generator, PEP 625 sdist packager, and single-file `.pyz` executable bundler.
+
+---
+
+## Quickstart
+
+### Installation
+
+Evok runs on Python 3.12+ with zero external runtime dependencies:
+
+```bash
+# Using uv
+uv pip install evok
+
+# Or via pip
+pip install evok
+```
+
+### Command-Line Usage (`ev`)
+
+```bash
+# Initialize a new project
+ev init my-app
+
+# Inspect AST imports and compare with pyproject.toml
+ev scan
+
+# Automatically prune unused dependencies
+ev prune
+
+# Build standard wheel, sdist, and standalone zipapp
+ev build --zipapp
+
+# Run a script with in-process zero-venv dependency virtualization
+ev run script.py
+
+# Check platform reflink support and runtime info
+ev info
+```
+
+---
+
+## Programmatic Python API
+
+Evok is built as a first-class Python library:
+
+```python
+from evok import Environment, InMemoryProvider, Resolver
+
+# 1. Dependency Resolution
+provider = InMemoryProvider(
+    {
+        "httpx": {"0.27.0": ["httpcore>=1.0.0"]},
+        "httpcore": {"1.0.5": []},
+    }
+)
+resolver = Resolver(provider=provider)
+graph = resolver.resolve(["httpx>=0.24.0"])
+print(graph.get("httpx").version)  # 0.27.0
+
+# 2. Ephemeral Zero-Venv Execution
+with Environment.ephemeral(graph) as env:
+    mod = env.import_module("httpx")
+```
+
+---
+
+## Documentation
+
+- [System Architecture](docs/architecture.md)
+- [CLI Reference](docs/cli.md)
+- [Python API Reference](docs/api.md)
+- [Performance & Bottleneck Analysis](docs/benchmarks.md)
+- [Implementation Plan](IMPLEMENTATION_PLAN.md)
+
+---
+
+## License
+
+MIT License.

evok-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Evok (`ev`)
+
+[![CI](https://github.com/wispsy/evok/actions/workflows/ci.yml/badge.svg)](https://github.com/wispsy/evok/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+> **Pure-Python high-performance package manager and zero-venv virtualization runtime.**
+
+Evok demonstrates that a clean-slate Python implementation leveraging modern OS primitives and stdlib capabilities can reach ~80% of `uv`'s speed while delivering native capabilities that compiled binaries cannot provide: first-class in-process APIs, zero-venv `sys.meta_path` virtualization, dynamic AST dependency inference, and single-file zero-binary `.pyz` bootstrapping.
+
+---
+
+## Key Highlights
+
+- **Zero-Copy Reflink Cache**: Unpacks wheels once into a global cache and installs in milliseconds using macOS APFS `clonefile`, Linux `FICLONE`, and hardlink (`os.link`) fallbacks.
+- **Bit-Packed PEP 440 Arithmetic**: Encodes release segments and lifecycle stages into single 64-bit scalar integers for microsecond comparisons.
+- **Async Metadata & Range Tail-Reads**: Fetches package metadata from remote ZIP central directories using HTTP Range requests without downloading full wheels.
+- **Zero-Venv Virtualization**: Run code with in-process `sys.meta_path` hooks that load dependencies directly from the cache without creating a `.venv` directory on disk.
+- **AST Dependency Scanner**: Scans project source code to automatically detect third-party imports, flag missing packages, and prune unused/dead dependencies.
+- **Pure-Python Wheel & Sdist Builder**: Standards-compliant PEP 427 wheel generator, PEP 625 sdist packager, and single-file `.pyz` executable bundler.
+
+---
+
+## Quickstart
+
+### Installation
+
+Evok runs on Python 3.12+ with zero external runtime dependencies:
+
+```bash
+# Using uv
+uv pip install evok
+
+# Or via pip
+pip install evok
+```
+
+### Command-Line Usage (`ev`)
+
+```bash
+# Initialize a new project
+ev init my-app
+
+# Inspect AST imports and compare with pyproject.toml
+ev scan
+
+# Automatically prune unused dependencies
+ev prune
+
+# Build standard wheel, sdist, and standalone zipapp
+ev build --zipapp
+
+# Run a script with in-process zero-venv dependency virtualization
+ev run script.py
+
+# Check platform reflink support and runtime info
+ev info
+```
+
+---
+
+## Programmatic Python API
+
+Evok is built as a first-class Python library:
+
+```python
+from evok import Environment, InMemoryProvider, Resolver
+
+# 1. Dependency Resolution
+provider = InMemoryProvider(
+    {
+        "httpx": {"0.27.0": ["httpcore>=1.0.0"]},
+        "httpcore": {"1.0.5": []},
+    }
+)
+resolver = Resolver(provider=provider)
+graph = resolver.resolve(["httpx>=0.24.0"])
+print(graph.get("httpx").version)  # 0.27.0
+
+# 2. Ephemeral Zero-Venv Execution
+with Environment.ephemeral(graph) as env:
+    mod = env.import_module("httpx")
+```
+
+---
+
+## Documentation
+
+- [System Architecture](docs/architecture.md)
+- [CLI Reference](docs/cli.md)
+- [Python API Reference](docs/api.md)
+- [Performance & Bottleneck Analysis](docs/benchmarks.md)
+- [Implementation Plan](IMPLEMENTATION_PLAN.md)
+
+---
+
+## License
+
+MIT License.

evok-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "evok"
+version = "0.1.0"
+description = "Pure-Python high-performance packaging engine and virtualization runtime"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = []
+
+[[project.authors]]
+name = "ellainng"
+email = "299958882+ellainng@users.noreply.github.com"
+
+[project.scripts]
+ev = "evok.cli:main"
+evok = "evok.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.4",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

evok-0.1.0/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[project]
+name = "evok"
+version = "0.1.0"
+description = "Pure-Python high-performance packaging engine and virtualization runtime"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "ellainng", email = "299958882+ellainng@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+ev = "evok.cli:main"
+evok = "evok.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.4",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

evok-0.1.0/src/evok/__init__.py

@@ -0,0 +1,19 @@
+"""Evok: Pure-Python high-performance package manager and virtualization runtime."""
+
+from evok.environment import Environment
+from evok.pep440 import BitPackedVersion, SpecifierSet, VersionSpecifier
+from evok.resolver import InMemoryProvider, Requirement, ResolutionGraph, Resolver
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BitPackedVersion",
+    "Environment",
+    "InMemoryProvider",
+    "Requirement",
+    "ResolutionGraph",
+    "Resolver",
+    "SpecifierSet",
+    "VersionSpecifier",
+    "__version__",
+]

evok-0.1.0/src/evok/__main__.py

@@ -0,0 +1,6 @@
+from evok.cli import main
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())

evok-0.1.0/src/evok/ast_scanner.py

@@ -0,0 +1,217 @@
+"""AST-driven dependency inference and dead-dependency pruning.
+
+Inspects Python AST to discover third-party imports, maps module names to PyPI distributions,
+and compares against pyproject.toml to flag missing or unused dependencies.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Known mapping of top-level import name to canonical PyPI package name
+KNOWN_IMPORT_MAP: dict[str, str] = {
+    "yaml": "pyyaml",
+    "cv2": "opencv-python",
+    "PIL": "pillow",
+    "bs4": "beautifulsoup4",
+    "sklearn": "scikit-learn",
+    "dateutil": "python-dateutil",
+    "dotenv": "python-dotenv",
+    "fitz": "pymupdf",
+    "magic": "python-magic",
+    "jwt": "pyjwt",
+    "serial": "pyserial",
+    "usb": "pyusb",
+    "gi": "pygobject",
+    "git": "gitpython",
+    "jose": "python-jose",
+    "multipart": "python-multipart",
+}
+
+_IGNORED_DIRS = {
+    ".venv",
+    "venv",
+    ".git",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+    "build",
+    "dist",
+    "site-packages",
+}
+
+
+def get_stdlib_modules() -> set[str]:
+    """Return set of standard library module names."""
+    if hasattr(sys, "stdlib_module_names"):
+        return set(sys.stdlib_module_names)
+    # Fallback list for older or custom runtimes
+    return {
+        "os",
+        "sys",
+        "io",
+        "math",
+        "json",
+        "re",
+        "time",
+        "datetime",
+        "pathlib",
+        "typing",
+        "ast",
+        "unittest",
+        "logging",
+        "collections",
+        "urllib",
+        "http",
+        "subprocess",
+        "threading",
+        "multiprocessing",
+        "asyncio",
+        "contextlib",
+        "functools",
+        "itertools",
+        "shutil",
+        "tempfile",
+        "glob",
+        "hashlib",
+        "random",
+        "socket",
+        "ssl",
+        "inspect",
+        "importlib",
+        "ctypes",
+        "struct",
+        "copy",
+        "enum",
+    }
+
+
+def normalize_package_name(name: str) -> str:
+    """Normalize package name according to PEP 503."""
+    return name.lower().replace("_", "-").replace(".", "-")
+
+
+class ImportVisitor(ast.NodeVisitor):
+    """AST visitor collecting imported module names."""
+
+    def __init__(self) -> None:
+        self.imports: set[str] = set()
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            root = alias.name.split(".")[0]
+            if root:
+                self.imports.add(root)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        if node.level == 0 and node.module:
+            root = node.module.split(".")[0]
+            if root:
+                self.imports.add(root)
+        self.generic_visit(node)
+
+
+def scan_file_imports(file_path: Path | str) -> set[str]:
+    """Parse a single Python file and return all root imported module names."""
+    p = Path(file_path)
+    try:
+        content = p.read_text(encoding="utf-8", errors="ignore")
+        tree = ast.parse(content, filename=str(p))
+    except (SyntaxError, UnicodeDecodeError):
+        return set()
+
+    visitor = ImportVisitor()
+    visitor.visit(tree)
+    return visitor.imports
+
+
+@dataclass
+class ScanResult:
+    """Results of AST dependency scanning across a codebase."""
+
+    all_imports: set[str] = field(default_factory=set)
+    inferred_packages: set[str] = field(default_factory=set)
+    declared_dependencies: set[str] = field(default_factory=set)
+    missing_dependencies: set[str] = field(default_factory=set)
+    unused_dependencies: set[str] = field(default_factory=set)
+
+
+def map_module_to_package(module_name: str) -> str:
+    """Map an imported module name to its likely PyPI distribution name."""
+    if module_name in KNOWN_IMPORT_MAP:
+        return KNOWN_IMPORT_MAP[module_name]
+    return normalize_package_name(module_name)
+
+
+def scan_project(root_dir: Path | str) -> ScanResult:
+    """Recursively scan Python files under root_dir and audit against pyproject.toml."""
+    root = Path(root_dir).resolve()
+    stdlib = get_stdlib_modules()
+
+    # Discover local project packages/modules to avoid false positives
+    local_modules: set[str] = set()
+    for item in root.iterdir():
+        if item.name.startswith("."):
+            continue
+        if item.is_file() and item.suffix == ".py":
+            local_modules.add(item.stem)
+        elif item.is_dir() and (item / "__init__.py").exists():
+            local_modules.add(item.name)
+
+    # Check for src-layout
+    src_dir = root / "src"
+    if src_dir.is_dir():
+        for item in src_dir.iterdir():
+            if item.is_file() and item.suffix == ".py":
+                local_modules.add(item.stem)
+            elif item.is_dir() and (item / "__init__.py").exists():
+                local_modules.add(item.name)
+
+    all_imports: set[str] = set()
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _IGNORED_DIRS and not d.startswith(".")]
+        for f in filenames:
+            if f.endswith(".py"):
+                file_p = Path(dirpath) / f
+                all_imports.update(scan_file_imports(file_p))
+
+    # Filter out stdlib and local modules
+    third_party_modules = {
+        m for m in all_imports if m not in stdlib and m not in local_modules and not m.startswith("_")
+    }
+
+    inferred_packages = {map_module_to_package(m) for m in third_party_modules}
+
+    # Read declared dependencies from pyproject.toml if present
+    declared: set[str] = set()
+    pyproject_file = root / "pyproject.toml"
+    if pyproject_file.exists():
+        try:
+            with open(pyproject_file, "rb") as f:
+                data = tomllib.load(f)
+            deps = data.get("project", {}).get("dependencies", [])
+            for dep in deps:
+                # Strip version specifiers like '>=1.0.0', '==2.0'
+                name = dep.split(";")[0].split(">")[0].split("<")[0].split("=")[0].split("~")[0]
+                name = name.strip()
+                if name:
+                    declared.add(normalize_package_name(name))
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+
+    missing = inferred_packages - declared
+    unused = declared - inferred_packages
+
+    return ScanResult(
+        all_imports=all_imports,
+        inferred_packages=inferred_packages,
+        declared_dependencies=declared,
+        missing_dependencies=missing,
+        unused_dependencies=unused,
+    )