viperx 0.9.26

Professional Python Project Initializer with uv, ml/dl support, and embedded config.

🐍 ViperX

Professional Python Project Initializer The modern, snake-fast way to bootstrap Python projects.

ViperX is a CLI tool designed to generate production-ready Python projects instantly. It leverages uv for blazing fast dependency management and offers specialized templates for Machine Learning (ml) and Deep Learning (dl).

✨ Features

• Blazing Fast: Built on top of uv.
• Pre-configured: pyproject.toml, proper src layout, ruff ready.
• ML/DL First: Templates with torch, tensorflow, kagglehub and Smart Caching.
• Smart Caching: Auto-downloads and caches datasets to ~/.cache/viperx/data (or local data/).
• Strict Isolation: Environment variables (.env) isolated in src/<pkg>/ for better security.
• Config-in-Package: Solves the "Colab/Kaggle doesn't see my config" problem.
• Platform Agnostic: Works on Local, VSCode, Colab, and Kaggle.

📦 Installation

Recommended (Global Tool)

pipx install viperx

Alternative (uv)

uv tool install viperx

🚀 Usage

init

Initialize a new project (Classic, ML, or DL).

# Classic Lib (Standard Layout)
viperx init -n my-lib

# Machine Learning ( + Notebooks, Pandas, Scikit-learn, Smart Loader)
viperx init -n churn-pred -t ml

# Deep Learning ( + PyTorch/TensorFlow, CUDA checks)
viperx init -n deep-vision -t dl --framework pytorch
# Deep Learning ( + PyTorch/TensorFlow, CUDA checks)
viperx init -n deep-vision -t dl --framework pytorch

# ✨ Declarative Config (Infrastructure as Code)
viperx config get                   # Generate template
viperx init -c viperx.yaml          # Apply config

package

Manage workspace packages (Monorepo style).

# Add a new package to the current workspace
viperx package add -n my-api -t classic

# Remove a package
viperx package delete -n my-api

🚀 Quick Start

Initialize a new project with a single command:

# Classic Package
viperx init -n my-lib -d "My awesome library"

# Deep Learning Project (PyTorch ready)
viperx init -n deep-vision -t dl --description "Vision Transformer implementation"

# Machine Learning Project (Scikit-learn ready)
viperx init -n churn-prediction -t ml

🧱 Structure

📂 Standard Layout

my-lib/
├── pyproject.toml      # Managed by uv
├── README.md
├── README.md
├── .gitignore
└── src/
    └── my_lib/
        ├── __init__.py
        ├── main.py     # Entry point
        ├── config.yaml # Data URLs & Params
        ├── config.py   # Loader
        ├── .env        # Secrets (Isolated)
        └── utils/
            └── data_loader.py # Generic URL/CSV Loader

🧠 Machine Learning & Deep Learning

For type ml or dl, you get:

• Notebooks:
  • Base_Kaggle.ipynb: Loads data via kagglehub.
  • Base_General.ipynb: Loads data via data_loader.py (URL/Local).
• Data Loader: src/<pkg>/data_loader.py handles caching downloads to data/.
• Config: Pre-filled with "Hello World" datasets (Iris, Titanic).

⚙️ Configurationstalls dependencies (torch, pandas...).

deep-vision/
├── pyproject.toml
├── notebooks/
│   └── Base.ipynb      # Pre-configured notebook (Colab/Kaggle ready)
└── src/
    └── deep_vision/
        ├── ...         # Same robust package structure

💻 CLI Usage

init - Create a new project

viperx init [OPTIONS]

Options:

• -n, --name TEXT: Project name (Required).
• -t, --type TEXT: Project type (classic, ml, dl). Default: classic.
• -d, --description TEXT: Project description.
• -a, --author TEXT: Author name (defaults to git user).
• -l, --license TEXT: License type (MIT, Apache-2.0, GPLv3). Default: MIT.
• -f, --framework TEXT: DL Framework (pytorch, tensorflow). Default: pytorch (only for -t dl).
• -v, --verbose: Enable verbose logging for transparent output.

Examples:

# Classic Library
viperx init -n my-lib

# Deep Learning (PyTorch Default)
viperx init -n vision-ai -t dl

# Deep Learning (TensorFlow)
viperx init -n tf-legacy -t dl -f tensorflow
# Deep Learning (TensorFlow)
viperx init -n tf-legacy -t dl -f tensorflow

# From Config File
viperx init -c viperx.yaml

config - Declarative Mode

Manage your project infrastructure using a YAML file.

viperx config get

Generates a viperx.yaml template in the current directory.

viperx init --config viperx.yaml

Applies the configuration. This is idempotent:

• Creates the project if it doesn't exist.
• Hydrates the directory if it exists but is empty (e.g., git init).
• Updates the workspace if the project exists (adds missing packages defined in YAML).

package - Manage Workspace

Manage packages in your workspace hierarchy (add, update, delete).

add

Add a new package to your project. Upgrades standalone projects to workspaces automatically.

```bash
viperx package add -n worker-node -t classic --no-readme

Options:

• --readme / --no-readme: Generate a local README.md for the package. Default: True.
• --env / --no-env: Generate isolated .env and .env.example in src/<pkg>/.

delete

Remove a package from the workspace (deletes folder & updates pyproject.toml).

viperx package delete -n worker-node

update

Update a package's dependencies (runs uv lock --upgrade).

viperx package update -n worker-node

---## 📦 "Magical" Configuration

Every project comes with a robust config.py using importlib.resources.

In your code / notebooks:

from my_package import SETTINGS, get_dataset_path

# Works everywhere: Local, Installed, Colab, Kaggle
print(SETTINGS['project_name'])

🤝 Contributing

This project is built 100% with uv.

1. Clone the repo
2. Sync dependencies: uv sync
3. Run the CLI: uv run viperx

---

Built with ❤️ by KpihX