Metadata-Version: 2.4
Name: vnma
Version: 0.3.0
Summary: Vendor Manager for Python — hermetic, zero-venv dependency management.
Author: VNMA Team
License: Copyright (c) 2026, GrandKenzy / VNMA Team and Contributors.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
           this list of conditions, and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions, and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Commercial Sale Restriction:
           Direct commercial sale or resale of this software itself, in whole or in
           substantial part, as a standalone product or service is strictly prohibited.
           Use, modification, and execution of this software to manage dependencies
           within proprietary or commercial applications is fully permitted without royalty.
        
        4. Vendor Share-Alike Distribution Requirement:
           Any downstream distribution, vendoring bundle, fork, or sub-component derived
           from this software must be distributed under these same license terms and include
           a copy of this license.
        
        5. Neither the name of the copyright holder nor the names of its contributors
           may be used to endorse or promote products derived from this software without
           specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
        IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
        INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
        BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
        DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
        LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
        OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
        ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/GrandKenzy/vnma
Project-URL: Documentation, https://github.com/GrandKenzy/vnma/tree/main/docs
Project-URL: Repository, https://github.com/GrandKenzy/vnma.git
Project-URL: Bug Tracker, https://github.com/GrandKenzy/vnma/issues
Keywords: vendoring,packaging,dependencies,hermetic,pip
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: packaging>=24.0
Dynamic: license-file

# VNMA (Vendor Manager)

> **Status:** Beta (v0.3.0)  
> **Platform Support:** CPython 3.11, 3.12, 3.13, 3.14 (Tested on Windows and Linux)

`vnma` is a dependency and vendoring manager for Python projects. It installs and manages dependencies inside a local project directory (`vendor/` or `vendor_vnma/`) instead of creating full Python virtual environments (`venv`).

---

## What VNMA Does (and What It Doesn't)

### What it does:
* **Installs packages locally:** Downloads, verifies, and unpacks wheels directly into `vendor/`.
* **Runtime path isolation:** Cleans `sys.path` so your application loads third-party libraries strictly from `vendor/`, ignoring global or user `site-packages`.
* **Automatic DLL registration (Windows):** Automatically calls `os.add_dll_directory()` for folders containing native binaries (e.g., SDL2, C extensions), preventing import errors.
* **Transactional operations:** Installations and updates are staged in a private directory and committed atomically; if an install fails or crashes, previous state is restored via a recovery journal.
* **Transitive dependency resolution:** Resolves dependencies and version constraints with bounded backtracking and PEP 508 marker evaluation.
* **Live development links (`vnma link`):** Connects local libraries in development without copying files, keeping dependencies synchronized.
* **IDE configuration:** Configures `extraPaths` in VS Code (`.vscode/settings.json`) and `PYTHONPATH` in PyCharm (`.env`, `.idea/*.iml`).

### What it doesn't do:
* **It does not virtualize the Python executable:** It uses your installed Python interpreter and standard library directly.
* **It cannot load multiple incompatible versions of the same library simultaneously:** Python's runtime has a single global `sys.modules`. Conflicting version requirements are rejected at resolution time.

---

## Step-by-Step Guide

### Step 1: Install VNMA

Install `vnma` using `pip`:

```bash
pip install vnma
```

Or install in editable mode from source:

```bash
git clone https://github.com/GrandKenzy/vnma.git
cd vnma
pip install -e .
```

Verify the installation:

```bash
vnma --help
```

---

### Step 2: Initialize Your Project

Navigate to your project folder and run:

```bash
cd my_project
vnma init
```

This command creates:
1. `vnma.toml`: Declarative manifest for your project and dependencies.
2. `vendor/`: Directory for vendored packages.
3. `vendor/__bootstrap__.py` & `vendor/__init__.py`: Runtime loader and path sanitizer.
4. `.gitignore` entries: Ignores vendored packages in Git.
5. IDE settings: Preconfigures VS Code (`.vscode/settings.json`) and PyCharm (`.env`).
6. `vnma.lock`: Lockfile for reproducible installs.

---

### Step 3: Install Packages

#### From PyPI:
```bash
# Latest compatible version:
vnma install requests

# Pinned version:
vnma install colorama==0.4.6

# Multiple packages:
vnma install flask pytest
```

#### From a local directory:
```bash
vnma install ../shared-library
```

#### From a Git repository:
```bash
vnma install git+https://github.com/psf/requests.git@main
```

---

### Step 4: Run Your Code

You have two ways to execute your code with vendored packages:

#### Option A: Using the CLI (Recommended)
```bash
vnma run main.py
```
`vnma run` sets `PYTHONPATH` to your vendor directory and disables user-site packages automatically.

#### Option B: Direct Python execution
Add this import at the very top of your entry script (`main.py`):
```python
import vendor.__bootstrap__
import requests

response = requests.get("https://httpbin.org/get")
print(response.status_code)
```
Then run normally with your system Python:
```bash
python main.py
```

---

### Step 5: Link Local Libraries for Development (`vnma link`)

When actively developing an internal library alongside an app, avoid re-installing wheels after every change:

```bash
vnma link ../my-library
```

* **Zero-copy:** Does not copy files; imports live directly from the library's source directory.
* **Auto-dependency resolution:** Reads the library's dependencies and installs them into `vendor/`.
* **To unlink:**
  ```bash
  vnma unlink my-library
  ```
* **To check and synchronize linked libraries:**
  ```bash
  vnma reload
  ```

---

### Step 6: Maintain and Clean Your Project

#### List installed packages:
```bash
vnma list
```

#### Update dependencies:
```bash
# Update all unpinned dependencies:
vnma update

# Update only PyPI packages:
vnma update --pip

# Update only Git repositories:
vnma update --git
```

#### Remove orphaned packages (packages no longer required):
```bash
# Preview what would be removed:
vnma prune --dry-run

# Remove unused packages:
vnma prune --yes
```

#### Uninstall a package:
```bash
# Remove from vendor directory:
vnma uninstall requests

# Remove from vendor directory AND delete from vnma.toml:
vnma uninstall requests -d
```

#### Restore dependencies on another machine or in CI:
```bash
vnma install
```

---

## Configuration Reference

### `vnma.toml` (Project Level)

```toml
[project]
name = "my-app"
version = "1.0.0"

[dependencies]
requests = ">=2.31.0"
colorama = "==0.4.6"
local-tool = { path = "../local-tool" }

[tool.vnma]
vendor_dir = "vendor"
ide_integration = ["vscode", "pycharm"]
```

### `vnma_config.toml` (Optional Library Manifest)

If developing a library with native DLLs or specific exports, place a `vnma_config.toml` in its root:

```toml
[package]
name = "my-library"
package = "my_library"  # Python import name (import my_library)
version = "0.1.0"

[runtime]
dll_directories = ["my_library/libs"]
hermetic = true

[exports]
modules = ["my_library"]
entry_points = { my-tool = "my_library.cli:main" }
```

---

## Command Summary

| Command | Description |
| :--- | :--- |
| `vnma init` | Initialize VNMA in the current project. |
| `vnma install <pkg>` | Install package(s) from PyPI, local path, or Git. |
| `vnma install` | Restore all dependencies declared in `vnma.toml`. |
| `vnma run <script>` | Run a Python script using the vendored runtime. |
| `vnma link <path>` | Link a local library in development (zero-copy live edits). |
| `vnma unlink <name>` | Unlink a previously linked local library. |
| `vnma reload` | Verify links, update dependencies, and auto-prune obsolete packages. |
| `vnma list` | Show all installed packages and their versions. |
| `vnma update` | Update unpinned dependencies to their latest compatible versions. |
| `vnma prune` | Remove unused packages that are no longer referenced in `vnma.toml`. |
| `vnma uninstall <pkg>` | Remove a package from `vendor/` (add `-d` to remove from `vnma.toml`). |
| `vnma sync-ide` | Reapply VS Code and PyCharm configuration files. |
| `vnma clean` | Safely remove vendor folders and lockfiles. |

---

## Documentation

Full documentation is available in the [`docs/`](docs/) directory:

* **Getting Started:** [docs/en/01-Use/01-getting-started.md](docs/en/01-Use/01-getting-started.md)
* **Dependency Management:** [docs/en/01-Use/02-dependency-management.md](docs/en/01-Use/02-dependency-management.md)
* **Configuration Specifications:** [docs/en/01-Use/03-configuration-specs.md](docs/en/01-Use/03-configuration-specs.md)
* **Runtime Execution Model:** [docs/en/01-Use/04-runtime-execution.md](docs/en/01-Use/04-runtime-execution.md)
* **IDE Integration:** [docs/en/01-Use/05-ide-integration.md](docs/en/01-Use/05-ide-integration.md)
* **Beta Status & Limitations:** [docs/en/02-Advice/01-beta-status.md](docs/en/02-Advice/01-beta-status.md)
* **Changelog:** [CHANGELOG.md](CHANGELOG.md)

---

## License

This software is released under a modified permissive license. See [LICENSE](LICENSE) for terms.
