viperx 0.9.14__py3-none-any.whl

viperx/templates/Base_General.ipynb.j2

@@ -0,0 +1,119 @@
+{
+"cells": [
+{
+"cell_type": "markdown",
+"metadata": {},
+"source": [
+"# {{ project_name }} - General Base\n",
+"\n",
+"**Author:** {{ author_name }}\n",
+"**Description:** {{ description }}\n",
+"\n",
+"This notebook demonstrates the **Smart Data Loader** capabilities.\n",
+"\n",
+"It supports two modes:\n",
+"1. **Global Cache (Default)**: Downloads to `~/.cache/viperx/data`. Ideal for shared datasets.\n",
+"2. **Local Project (Optional)**: Downloads to `./data`. Ideal for project-specific datasets."
+]
+},
+{
+"cell_type": "code",
+"execution_count": null,
+"metadata": {},
+"outputs": [],
+"source": [
+"# Universal Setup\n",
+"import sys\n",
+"from {{ package_name }} import get_config\n",
+"from {{ package_name }}.data_loader import load_csv, download_file\n",
+"\n",
+"print(f\"Project: {get_config('project_name')}\")"
+]
+},
+{
+"cell_type": "code",
+"execution_count": null,
+"metadata": {},
+"outputs": [],
+"source": [
+"# Standard Imports\n",
+"import numpy as np\n",
+"import pandas as pd\n",
+"import matplotlib.pyplot as plt\n",
+"import seaborn as sns\n",
+"\n",
+"{% if project_type == 'dl' %}\n",
+"{% if framework == 'pytorch' %}\n",
+"import torch\n",
+"print(f\"PyTorch Version: {torch.__version__}\")\n",
+"{% elif framework == 'tensorflow' %}\n",
+"import tensorflow as tf\n",
+"print(f\"TensorFlow Version: {tf.__version__}\")\n",
+"{% endif %}\n",
+"{% endif %}\n",
+"\n",
+"%matplotlib inline"
+]
+},
+{
+"cell_type": "code",
+"execution_count": null,
+"metadata": {},
+"outputs": [],
+"source": [
+"# Mode 1: Global Cache (Default)\n",
+"# Does NOT create a 'data/' folder in your project.\n",
+"# Uses config.yaml key 'iris'\n",
+"\n",
+"try:\n",
+" print(\"Loading Iris (Global Cache)...\")\n",
+" df_iris = load_csv('iris')\n",
+" display(df_iris.head())\n",
+"except Exception as e:\n",
+" print(f\"Error: {e}\")"
+]
+},
+{
+"cell_type": "code",
+"execution_count": null,
+"metadata": {},
+"outputs": [],
+"source": [
+"# Mode 2: Local Project Data\n",
+"# Forces download to ./data/ folder\n",
+"# Uses config.yaml key 'titanic'\n",
+"\n",
+"try:\n",
+" print(\"Loading Titanic (Local Download)...\")\n",
+" # Passing local=True triggers ./data creation\n",
+" df_titanic = load_csv('titanic', local=True)\n",
+" display(df_titanic.head())\n",
+" \n",
+" print(\"\\nCheck your project root: 'data/' folder should now exist!\")\n",
+"except Exception as e:\n",
+" print(f\"Error: {e}\")"
+]
+}
+],
+"metadata": {
+"kernelspec": {
+"display_name": "Python 3",
+"language": "python",
+"name": "python3"
+},
+"language_info": {
+"codemirror_mode": {
+"name": "ipython",
+"version": 3
+},
+"file_extension": ".py",
+"mimetype": "text/x-python",
+"name": "python",
+"nbconvert_exporter": "python",
+"pygments_lexer": "ipython3",
+"version": "3.11.0"
+}
+},
+"nbformat": 4,
+"nbformat_minor": 5
+}

viperx/templates/Base_Kaggle.ipynb.j2

@@ -0,0 +1,114 @@
+{
+"cells": [
+{
+"cell_type": "markdown",
+"metadata": {},
+"source": [
+"# {{ project_name }} - Kaggle Base\n",
+"\n",
+"**Author:** {{ author_name }}\n",
+"**Description:** {{ description }}\n",
+"\n",
+"This notebook demonstrates data loading using **KaggleHub**."
+]
+},
+{
+"cell_type": "code",
+"execution_count": null,
+"metadata": {},
+"outputs": [],
+"source": [
+"# Universal Setup (Local / Colab / Kaggle)\n",
+"import sys\n",
+"import os\n",
+"import yaml\n",
+"# Check if running on Colab\n",
+"if 'google.colab' in sys.modules:\n",
+" print('Detected Google Colab environment')\n",
+" # Clone/Install the package if needed\n",
+" # !pip install git+https://github.com/{{ author_name | lower | replace(' ', '') }}/{{ project_name }}.git\n",
+"\n",
+"from {{ package_name }} import get_config\n",
+"\n",
+"print(f\"Project: {get_config('project_name')}\")"
+]
+},
+{
+"cell_type": "code",
+"execution_count": null,
+"metadata": {},
+"outputs": [],
+"source": [
+"# Standard Imports\n",
+"import numpy as np\n",
+"import pandas as pd\n",
+"import matplotlib.pyplot as plt\n",
+"import seaborn as sns\n",
+"import kagglehub as kh\n",
+"\n",
+"{% if project_type == 'dl' %}\n",
+"{% if framework == 'pytorch' %}\n",
+"import torch\n",
+"print(f\"PyTorch Version: {torch.__version__}\")\n",
+"print(f\"CUDA Available: {torch.cuda.is_available()}\")\n",
+"{% elif framework == 'tensorflow' %}\n",
+"import tensorflow as tf\n",
+"print(f\"TensorFlow Version: {tf.__version__}\")\n",
+"print(f\"GPU Available: {len(tf.config.list_physical_devices('GPU')) > 0}\")\n",
+"{% endif %}\n",
+"{% endif %}\n",
+"\n",
+"%matplotlib inline"
+]
+},
+{
+"cell_type": "code",
+"execution_count": null,
+"metadata": {},
+"outputs": [],
+"source": [
+"# Load Dataset using Config + KaggleHub\n",
+"try:\n",
+" # Load dataset handle from config\n",
+" dataset_handle = get_config('datasets', {}).get('Base_Kaggle', 'titanic')\n",
+" print(f\"Loading dataset: {dataset_handle}...\")\n",
+" \n",
+" path = kh.dataset_download(dataset_handle)\n",
+" print(f\"Path: {path}\")\n",
+" \n",
+" # Logic to find csv in path\n",
+" import glob\n",
+" csv_files = glob.glob(f\"{path}/*.csv\")\n",
+" if csv_files:\n",
+" df = pd.read_csv(csv_files[0])\n",
+" display(df.head())\n",
+" df.info()\n",
+" else:\n",
+" print(\"No CSV found in dataset.\")\n",
+"except Exception as e:\n",
+" print(f\"Failed to load dataset: {e}\")"
+]
+}
+],
+"metadata": {
+"kernelspec": {
+"display_name": "Python 3",
+"language": "python",
+"name": "python3"
+},
+"language_info": {
+"codemirror_mode": {
+"name": "ipython",
+"version": 3
+},
+"file_extension": ".py",
+"mimetype": "text/x-python",
+"name": "python",
+"nbconvert_exporter": "python",
+"pygments_lexer": "ipython3",
+"version": "3.11.0"
+}
+},
+"nbformat": 4,
+"nbformat_minor": 5
+}

viperx/templates/README.md.j2

@@ -0,0 +1,122 @@
+# {{ project_name }}
+
+{{ description }}
+
+---
+
+## 🧐 Philosophy & Architecture
+
+Values transparency and standard tooling over "black box" magic.
+This project was generated with [ViperX](https://github.com/kpihx/viperx).sh/uv/)**, the extremely fast Python package and project manager written in Rust.
+
+### Why `uv`?
+Unlike traditional workflows (pip, poetry, venv mixing), `uv` manages the **entire lifecycle**:
+- **Python Version**: It installs and manages the correct Python version for this project automatically.
+- **Dependencies**: Locking is instant.
+{% if project_type == 'dl' %}
+- **Stack**: {{ framework|title }}
+{% endif %}
+- **Environment**: Virtual environments are managed internally, you just run `uv run`.
+
+### ⚙️ Configuration
+
+- **Config**: `src/{{ package_name }}/config.yaml` (Loaded automatically)
+{% if has_config %}
+- **Environment**: `src/{{ package_name }}/.env` (Isolated variables)
+{% endif %}
+
+Edit `config.yaml` to change parameters. The project uses a **Config-in-Package** architecture:
+1. `config.yaml` is inside the package.
+2. `config.py` loads it safely (even in production wheels).
+3. `.env` is isolated within the package source.
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+You only need **[uv](https://docs.astral.sh/uv/)**.
+No need to install Python or create venvs manually.
+
+### Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/{{ author_name | lower | replace(" ", "") }}/{{ project_name }}.git
+cd {{ project_name }}
+
+# Sync dependencies (creates .venv and installs python if needed)
+uv sync
+```
+
+## 🧑‍💻 Usage
+
+The entry point depends on your project type.
+
+### For Developers (Code)
+
+To run the package entry point or scripts:
+
+```bash
+# Run the main package
+uv run {{ package_name }}
+
+# Or run a specific script
+uv run python src/{{ package_name }}/main.py
+```
+
+{% if project_type in ['ml', 'dl'] %}
+### For Data Scientists (Notebooks)
+
+We use `uv` to launch Jupyter, ensuring it sees the local package and config.
+
+```bash
+uv run jupyter notebook
+```
+
+- Open `notebooks/Base.ipynb`.
+- Note how it imports `config` from the package.
+{% endif %}
+
+### ☁️ Cloud (Colab / Kaggle)
+
+You can use the code and config from this repository directly in cloud environments without cloning.
+
+**Step 1: Install directly from GitHub**
+```python
+!pip install git+https://github.com/{{ author_name | lower | replace(" ", "") }}/{{ project_name }}.git
+```
+
+**Step 2: Use the unified config**
+```python
+from {{ package_name }} import get_dataset_path, SETTINGS
+import kagglehub as kh
+
+# Transparency: You can inspect what was loaded
+print(f"Loaded config for: {SETTINGS['project_name']}")
+
+# Download datasets defined in config.yaml
+# The key 'titanic' maps to 'heptapod/titanic' in the yaml
+path = kh.dataset_download(SETTINGS['datasets']['titanic'])
+```
+
+## 🔧 Internal Structure
+
+```text
+{{ project_name }}/
+├── pyproject.toml      # The Single Source of Truth (Dependencies, Metadata)
+├── uv.lock             # Exact versions lockfile
+├── .python-version     # Pinned Python version
+├── src/
+│   └── {{ package_name }}/
+│       ├── __init__.py
+│       ├── config.yaml # EDIT THIS for project settings
+│       ├── config.py   # Code that loads the yaml above
+│       └── tests/      # Unit tests
+{% if project_type in ['ml', 'dl'] %}
+└── notebooks/          # Experimentation (Jupyter)
+{% endif %}
+```
+
+

viperx/templates/__init__.py.j2

@@ -0,0 +1,8 @@
+{% if has_config %}
+from .config import SETTINGS, get_config, get_dataset_path
+{% endif %}
+
+__version__ = "{{ version }}"
+
+def hello():
+    print(f"Hello from {{ project_name }} v{__version__}!")

viperx/templates/config.py.j2

@@ -0,0 +1,40 @@
+import yaml
+import importlib.resources
+from pathlib import Path
+from typing import Any, Dict
+{% if use_env %}
+from dotenv import load_dotenv
+
+# Load Environment Variables from the isolated .env file in this package
+load_dotenv(Path(__file__).parent / ".env")
+{% endif %}
+
+# Load configuration safely whether installed or local
+try:
+    # Modern Way (Python 3.9+) - works when installed as a package
+    _config_path = importlib.resources.files("{{ package_name }}").joinpath("config.yaml")
+    with _config_path.open("r") as f:
+        SETTINGS: Dict[str, Any] = yaml.safe_load(f)
+except Exception:
+    # Fallback for local dev without install or older python
+    _local_path = Path(__file__).parent / "config.yaml"
+    if _local_path.exists():
+        with open(_local_path, "r") as f:
+            SETTINGS = yaml.safe_load(f)
+    else:
+        SETTINGS = {}
+
+def get_config(key: str, default: Any = None) -> Any:
+    """Retrieve a value from the globally loaded settings."""
+    return SETTINGS.get(key, default)
+
+def get_dataset_path(notebook_name: str, key: str = "datasets", extension: str = ".csv") -> str | None:
+    """
+    Helper for notebook data loading.
+    Looks up 'notebook_name' in the 'key' section of config.yaml.
+    """
+    datasets = SETTINGS.get(key, {})
+    dataset_name = datasets.get(notebook_name)
+    if not dataset_name:
+        return None
+    return f"{dataset_name}{extension}"

viperx/templates/config.yaml.j2

@@ -0,0 +1,14 @@
+{% if project_type in ['ml', 'dl'] %}
+data_urls:
+  iris: "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv"
+  titanic: "https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv"
+
+datasets:
+  # Notebook Name: Kaggle Dataset Handle
+  Base_Kaggle: "titanic"
+  # Usage: kh.dataset_download(SETTINGS['datasets']['titanic'])
+  titanic: "heptapod/titanic"
+{% else %}
+# Configuration file for {{ package_name }}
+# Add your settings here.
+{% endif %}

viperx/templates/data_loader.py.j2

@@ -0,0 +1,112 @@
+import os
+import requests
+import hashlib
+from pathlib import Path
+from tqdm import tqdm
+import pandas as pd
+from {{ package_name }}.config import get_config
+
+def get_cache_dir(local: bool = False) -> Path:
+    """
+    Get the directory for storing data.
+    
+    Args:
+        local: If True, returns <project_root>/data. 
+               If False, returns ~/.cache/viperx/data (Global Cache).
+    """
+    if local:
+        # Project Root Strategy:
+        # This script is likely in src/pkg/data_loader.py or src/pkg/utils/data_loader.py
+        # We assume project root is grandparents of this file until we hit pyproject.toml ideally
+        # But simple fallback: 3 levels up from src/pkg/data_loader.py is root
+        current_file = Path(__file__).resolve()
+        # src/pkg/data_loader.py -> parent=pkg -> parent=src -> parent=root
+        # Verify structure:
+        # if in src/pkg/utils/data_loader.py -> 4 levels
+        # Let's try to detect root marker
+        root = current_file.parent
+        while not (root / "pyproject.toml").exists():
+            if root.parent == root: # hit filesystem root
+                 # Fallback to cwd if running from notebook
+                 return Path.cwd() / "data"
+            root = root.parent
+        
+        data_dir = root / "data"
+    else:
+        # Global Cache Strategy
+        data_dir = Path.home() / ".cache" / "viperx" / "data"
+
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir
+
+def download_file(url: str, filename: str = None, local: bool = False, force: bool = False) -> Path:
+    """
+    Download a file from a URL.
+    
+    Args:
+        url: Source URL.
+        filename: Target filename. If None, derived from URL.
+        local: If True, downloads to project 'data/' folder. If False, uses Global Cache.
+        force: If True, redownload even if exists.
+        
+    Returns:
+        Path to the downloaded file.
+    """
+    target_dir = get_cache_dir(local=local)
+    
+    if not filename:
+        filename = url.split("/")[-1]
+        
+    target_path = target_dir / filename
+    
+    if target_path.exists() and not force:
+        print(f"Using cached file: {target_path}")
+        return target_path
+        
+    print(f"Downloading {url} to {target_path}...")
+    
+    try:
+        response = requests.get(url, stream=True)
+        response.raise_for_status()
+        
+        total_size = int(response.headers.get('content-length', 0))
+        block_size = 1024 # 1 Kibibyte
+        
+        with open(target_path, "wb") as f, tqdm(
+            desc=filename,
+            total=total_size,
+            unit='iB',
+            unit_scale=True,
+            unit_divisor=1024,
+        ) as bar:
+            for data in response.iter_content(block_size):
+                size = f.write(data)
+                bar.update(size)
+                
+        print("Download complete.")
+        return target_path
+    except Exception as e:
+        print(f"Failed to download: {e}")
+        if target_path.exists():
+            target_path.unlink() # Clean up partial file
+        raise
+
+def load_csv(key_or_url: str, local: bool = False, **kwargs) -> pd.DataFrame:
+    """
+    Load a CSV file.
+    
+    Args:
+        key_or_url: Config key ('iris') OR direct URL.
+        local: If True, ensures file is in local 'data/' folder.
+    """
+    # 1. Check if it's a config key
+    urls_config = get_config("data_urls", {})
+    url = urls_config.get(key_or_url, key_or_url)
+    
+    # 2. Check if it's a URL
+    if url.startswith("http"):
+        path = download_file(url, local=local)
+        return pd.read_csv(path, **kwargs)
+    
+    # 3. Assume local path (pass through)
+    return pd.read_csv(url, **kwargs)

viperx/templates/main.py.j2

@@ -0,0 +1,13 @@
+from {{ package_name }} import hello
+{% if has_config %}
+from {{ package_name }} import SETTINGS
+{% endif %}
+
+def main():
+    hello()
+    {% if has_config %}
+    print(f"Project config loaded: {SETTINGS['project_name']}")
+    {% endif %}
+
+if __name__ == "__main__":
+    main()

viperx/templates/pyproject.toml.j2

@@ -0,0 +1,59 @@
+[project]
+name = "{{ project_name }}"
+version = "{{ version }}"
+description = "{{ description }}"
+{% if use_readme %}
+readme = "README.md"
+{% endif %}
+requires-python = ">={{ python_version }}"
+authors = [
+    { name = "{{ author_name }}", email = "{{ author_email }}" }
+]
+license = { text = "{{ license }}" }
+dependencies = [
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0.0",
+    "kagglehub>=0.2.0",
+    {% if project_type == 'ml' %}
+    "numpy>=1.24.0",
+    "pandas>=2.0.0",
+    "scikit-learn>=1.3.0",
+    "matplotlib>=3.7.0",
+    "seaborn>=0.12.0",
+    "requests>=2.30.0",
+    "tqdm>=4.65.0",
+    {% elif project_type == 'dl' %}
+    {% if framework == 'pytorch' %}
+    "torch>=2.0.0",
+    "torchvision>=0.15.0",
+    {% elif framework == 'tensorflow' %}
+    "tensorflow>=2.13.0",
+    # "keras>=3.0.0", # Optional, included in tf usually
+    {% endif %}
+    "numpy>=1.24.0",
+    "pandas>=2.0.0",
+    "matplotlib>=3.7.0",
+    "seaborn>=0.12.0",
+    "requests>=2.30.0",
+    "tqdm>=4.65.0",
+    {% endif %}
+]
+
+[build-system]
+{% if builder == 'hatch' %}
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+{% elif builder == 'flit' %}
+requires = ["flit_core>=3.2,<4"]
+build-backend = "flit_core.buildapi"
+{% else %}
+# Default to Setuptools (Standard/Robust) to avoid Hatchling unless requested
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+{% endif %}
+
+{% if use_uv %}
+[tool.uv]
+managed = true
+{% endif %}
+

viperx/templates/viperx_config.yaml.j2

@@ -0,0 +1,45 @@
+# 🐍 ViperX Project Configuration (v0.9.3)
+# =============================================================================
+# "Source of Truth" for your project infrastructure.
+# Run `viperx init -c viperx.yaml` to apply changes.
+# =============================================================================
+
+project:
+  # [Required] Root project name
+  name: "my-project"
+  
+  # [Optional] Defaults (Inferred from git/system if omitted)
+  # description: "My robust project"
+  # author: "KpihX"
+  # license: "MIT"
+  # builder: "uv"
+
+settings:
+  # [Optional] Project Defaults (Applied to root & workspace members)
+  
+  # Generate isolated .env files in src/<pkg>/? (Default: false)
+  use_env: false
+  
+  # Generate config.py embedded loader? (Default: true)
+  use_config: true
+  
+  # Generate tests/ directory? (Default: true)
+  use_tests: true
+  
+  # Project Type: classic | ml | dl (Default: classic, affects ROOT only)
+  type: "classic"
+  
+  # DL Framework: pytorch | tensorflow (Only if type is dl)
+  # framework: "pytorch"
+
+workspace:
+  # Define workspace members (Monorepo / Utility Packages).
+  # These are minimal packages created at the workspace root (Flat Layout).
+  packages:
+    # --- Example 1: Preprocess Package ---
+    # - name: "preprocess"
+    #   description: "reprocessing utilities"
+    #   use_env: false
+    #   use_config: true
+    #   use_tests: true
+