metaenv 0.1.0

Automated Python environment management tool that scans imports, installs dependencies, and generates requirements.txt

MetaEnv

Automated Python environment management tool

Ever cloned a Python project and spent 30 minutes figuring out dependencies? Yeah, me too. That's why I built MetaEnv.

MetaEnv automatically scans your project for imports, creates a virtual environment, installs everything you need, and generates a clean requirements.txt file. No more manual setup headaches.

Why you'll love it:

• 🚀 One command to set up any Python project
• 📦 No more "ModuleNotFoundError" surprises
• 🔧 Works across different machines (finally!)
• ⚡ Saves you from dependency hell

🎯 Overall Objective

✅ Automatically set up a Python virtual environment

✅ Detect dependencies directly by scanning project imports

✅ Install all required third-party libraries seamlessly

✅ Allow optional control over Python version

✅ Generate requirements.txt with pinned versions

✅ Provide utility commands for scanning, cleaning, running, and installing

✅ Ensure reproducible, consistent environments across machines

✅ Save onboarding time and simplify environment management

Quick Start

Installation

# Install metaenv
pip install -e .

Basic Usage

# 1. Full automatic setup (one command!)
metaenv create

# 2. Create with specific Python version
metaenv create --python 3.11

# 3. Generate requirements.txt
metaenv generate

# 4. Scan imports only (no install)
metaenv scan

# 5. Install into existing environment
metaenv install

# 6. Clean/remove environment
metaenv clean

# 7. Run script in managed environment
metaenv run app.py

🖥 CLI Command Overview

1. Default Command — Full Automatic Setup

metaenv create

What it does:

• ✅ Detects available Python version
• ✅ Creates a virtual environment
• ✅ Scans all .py files for imports
• ✅ Identifies third-party dependencies
• ✅ Installs all required libraries

One-step complete setup!

Example output:

MetaEnv - Creating Environment
Project: /home/user/myproject

1. Virtual Environment
  ✓ Creating virtual environment...
  Python: Python 3.11.4
  Pip: pip 23.2.1

2. Scanning Imports
  Scanned 15 file(s)
  Found 47 import statement(s)

3. Classifying Imports
  Third-party: 8 package(s)

4. Resolving Package Names
  cv2 → opencv-python
  sklearn → scikit-learn
  Resolved to 8 PyPI package(s)

5. Installing 8 Package(s)
  ✓ requests
  ✓ numpy
  ✓ opencv-python
  ...

✓ Environment created successfully!

2. Create Environment With a Specific Python Version

metaenv create --python 3.11
# or
metaenv create -p 3.11

What it does:

• Uses the specified Python version for the venv
• Scans imports
• Installs dependencies

Useful for compatibility or when multiple Python versions exist.

3. Generate Only a requirements.txt File

metaenv generate

What it does:

• Reads packages installed in the venv
• Generates a fully pinned requirements.txt

✔ Use after modifying your environment ✔ Works even if no scanning/install is needed

---

🧩 Optional / Utility Commands

4. Scan Only (No Install, No Env Creation)

metaenv scan

What it does:

• Scans project imports
• Lists third-party dependencies
• Does not create environment or install packages

✔ Useful for audit and checking missing libs

5. Install Only (Use Existing Environment)

metaenv install

What it does:

• Installs dependencies detected earlier
• Assumes environment already exists

✔ Great when environment exists but dependencies need updating

6. Clean/Delete Existing Environment

metaenv clean

What it does:

• Removes the existing virtual environment folder (.venv)

✔ Useful for resetting the environment ✔ Important before a fresh rebuild

7. Run a Script Using the Managed Environment

metaenv run app.py

What it does:

• Runs a Python script using the venv interpreter
• No need to manually activate the environment

✔ Convenience for developers ✔ Guarantees correct environment usage

Project Structure

After initialization, your project will have:

your-project/
├── .venv/                    # Virtual environment (auto-created)
├── .metaenv/                # MetaEnv metadata
│   ├── config.json          # Configuration
│   └── deps.json            # Per-file dependency map
├── requirements.txt         # Auto-generated dependencies
├── .gitignore               # Auto-updated to exclude .venv and .metaenv
└── your code...

Import Resolution

MetaEnv intelligently maps import names to PyPI packages:

Import	PyPI Package
cv2	opencv-python
sklearn	scikit-learn
skimage	scikit-image
bs4	beautifulsoup4
PIL	Pillow
yaml	PyYAML
dateutil	python-dateutil
dotenv	python-dotenv
MySQLdb	mysqlclient
psycopg2	psycopg2-binary

And many more! For most packages, import name = package name.

Configuration

Configuration is stored in .metaenv/config.json:

{
  "python_path": ".venv/bin/python",
  "pip_path": ".venv/bin/pip",
  "venv_path": ".venv",
  "exclude_patterns": [
    ".venv",
    "venv",
    "__pycache__",
    ".git",
    "node_modules",
    "build",
    "dist",
    "*.egg-info"
  ],
  "auto_install": true,
  "index_url": ""
}

You can edit this file to customize behavior.

Command Reference

metaenv create [PATH]

Create virtual environment and install all dependencies automatically.

Options:

• --python, -p VERSION - Python version to use (e.g., 3.11)

Examples:

metaenv create                    # Use default Python
metaenv create --python 3.11      # Use Python 3.11
metaenv create -p 3.11            # Short form

metaenv generate [PATH]

Generate requirements.txt with pinned versions.

Options:

• --output, -o PATH - Output file (default: requirements.txt)

Examples:

metaenv generate                          # Default output
metaenv generate --output requirements-prod.txt

metaenv scan [PATH]

Scan project imports and list dependencies (no install).

Examples:

metaenv scan                      # Scan current directory

metaenv install [PATH]

Install dependencies into existing environment.

Examples:

metaenv install                   # Install in current directory

metaenv clean [PATH]

Remove the virtual environment.

Options:

• --yes, -y - Skip confirmation prompt

Examples:

metaenv clean                     # Remove with confirmation
metaenv clean --yes               # Remove without confirmation

metaenv run SCRIPT [ARGS...]

Run a Python script using the managed environment.

Examples:

metaenv run app.py
metaenv run scripts/train.py --epochs 10

Use Cases

Starting a New Project

mkdir myproject
cd myproject
# Write your Python code with imports...
metaenv create
# Everything is set up automatically!

Cloning a Repository

git clone https://github.com/user/repo.git
cd repo
metaenv create
# All dependencies detected and installed!

Using a Specific Python Version

cd myproject
metaenv create --python 3.11
# Environment created with Python 3.11

Generating Requirements for Deployment

metaenv generate
# requirements.txt created with pinned versions

Scanning Project Before Setup

# First check what dependencies are needed
metaenv scan

# Then create environment
metaenv create

Cleaning and Rebuilding Environment

# Remove old environment
metaenv clean --yes

# Create fresh environment
metaenv create

Running Scripts in Managed Environment

# No need to activate venv manually
metaenv run main.py
metaenv run tests/test_app.py

Comparison with Other Tools

Feature	MetaEnv	pip	poetry	pipenv
Auto-scan imports	✅	❌	❌	❌
Auto-install from code	✅	❌	❌	❌
Venv management	✅	❌	✅	✅
Per-file deps	✅	❌	❌	❌
Zero config	✅	✅	❌	❌
Import resolution	✅	❌	❌	❌

Roadmap

v0.1.0 - Core Functionality ✅

• AST-based import scanner
• Smart import name resolution (cv2→opencv-python, etc.)
• Automatic virtual environment creation
• Automatic dependency installation
• CLI: create and generate commands
• Requirements.txt generation with pinned versions

v0.2.0 - Enhanced Features (Planned)

• Support for pyproject.toml
• Jupyter notebook support (.ipynb files)
• Enhanced error handling and logging
• Progress indicators for long operations

v0.3.0 - Advanced Features (Future)

• Watch mode (auto-detect file changes)
• Docker integration (Dockerfile generation)
• CI/CD templates (GitHub Actions)
• IDE plugins (VSCode, PyCharm)

Documentation

For more detailed information, see:

• Quick Start Guide - Get up and running in 60 seconds
• Installation Guide - Setup instructions and troubleshooting
• Project Summary - Technical overview and architecture

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Credits

Built with:

• typer - CLI framework
• rich - Terminal formatting
• Python's ast module - Code parsing

---

Made with ❤️ to make Python dependency management effortless