metaenv 0.1.0
Automated Python environment management tool that scans imports, installs dependencies, and generates requirements.txt
License: MIT
Requires Python: >=3.8

# 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

```bash
# Install metaenv
pip install -e .
```

### Basic Usage

```bash
# 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

```bash
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

```bash
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

```bash
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)

```bash
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)

```bash
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

```bash
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

```bash
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`:

```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:**
```bash
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:**
```bash
metaenv generate                          # Default output
metaenv generate --output requirements-prod.txt
```

### `metaenv scan [PATH]`
Scan project imports and list dependencies (no install).

**Examples:**
```bash
metaenv scan                      # Scan current directory
```

### `metaenv install [PATH]`
Install dependencies into existing environment.

**Examples:**
```bash
metaenv install                   # Install in current directory
```

### `metaenv clean [PATH]`
Remove the virtual environment.

**Options:**
- `--yes, -y` - Skip confirmation prompt

**Examples:**
```bash
metaenv clean                     # Remove with confirmation
metaenv clean --yes               # Remove without confirmation
```

### `metaenv run SCRIPT [ARGS...]`
Run a Python script using the managed environment.

**Examples:**
```bash
metaenv run app.py
metaenv run scripts/train.py --epochs 10
```

## Use Cases

### Starting a New Project
```bash
mkdir myproject
cd myproject
# Write your Python code with imports...
metaenv create
# Everything is set up automatically!
```

### Cloning a Repository
```bash
git clone https://github.com/user/repo.git
cd repo
metaenv create
# All dependencies detected and installed!
```

### Using a Specific Python Version
```bash
cd myproject
metaenv create --python 3.11
# Environment created with Python 3.11
```

### Generating Requirements for Deployment
```bash
metaenv generate
# requirements.txt created with pinned versions
```

### Scanning Project Before Setup
```bash
# First check what dependencies are needed
metaenv scan

# Then create environment
metaenv create
```

### Cleaning and Rebuilding Environment
```bash
# Remove old environment
metaenv clean --yes

# Create fresh environment
metaenv create
```

### Running Scripts in Managed Environment
```bash
# 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 ✅
- [x] AST-based import scanner
- [x] Smart import name resolution (cv2→opencv-python, etc.)
- [x] Automatic virtual environment creation
- [x] Automatic dependency installation
- [x] CLI: `create` and `generate` commands
- [x] 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](docs/QUICKSTART.md)** - Get up and running in 60 seconds
- **[Installation Guide](docs/INSTALLATION.md)** - Setup instructions and troubleshooting
- **[Project Summary](docs/PROJECT_SUMMARY.md)** - 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](https://typer.tiangolo.com/) - CLI framework
- [rich](https://rich.readthedocs.io/) - Terminal formatting
- Python's `ast` module - Code parsing

---

**Made with ❤️ to make Python dependency management effortless**