Metadata-Version: 2.4
Name: safeenv-tool
Version: 0.1.0
Summary: Automatic Python environment manager for students and developers
Author-email: safeenv contributors <hello@safeenv.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/safeenv/safeenv
Project-URL: Repository, https://github.com/safeenv/safeenv
Project-URL: Issues, https://github.com/safeenv/safeenv/issues
Keywords: virtualenv,environment,dependencies,cli,developer-tools,beginner,education
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

<div align="center">

<h1>🛡 safeenv</h1>

<p><strong>Automatic Python environment manager for students and developers</strong></p>

<p>
  <a href="https://pypi.org/project/safeenv/"><img alt="PyPI" src="https://img.shields.io/pypi/v/safeenv?color=blue&label=PyPI"></a>
  <a href="https://pypi.org/project/safeenv/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/safeenv"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-green"></a>
  <a href="https://github.com/safeenv/safeenv/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/safeenv/safeenv/tests.yml?label=tests"></a>
</p>

</div>

---

## What is safeenv?

`safeenv` is a beginner-friendly Python CLI tool that **automatically sets up, fixes, and diagnoses Python project environments**.

Students and new developers often struggle with:

- Creating and activating virtual environments
- Generating `requirements.txt` files
- Getting a cloned project to run
- Mysterious `ModuleNotFoundError` messages
- Missing or broken dependencies

`safeenv` makes these problems disappear with simple, memorable commands.

---

## Features

| Command            | What it does                                                    |
|--------------------|------------------------------------------------------------------|
| `safeenv init`     | Create a `.venv` virtual environment in the current directory   |
| `safeenv freeze`   | Scan all `.py` files and generate `requirements.txt`            |
| `safeenv setup`    | Create `.venv` + install all dependencies (great after cloning) |
| `safeenv doctor`   | Diagnose missing venv, packages, or bad Python versions         |
| `safeenv fix`      | Repair the environment automatically                            |

---

## Installation

```bash
pip install safeenv
```

Or install in editable/development mode from source:

```bash
git clone https://github.com/safeenv/safeenv.git
cd safeenv
pip install -e ".[dev]"
```

After installation, the `safeenv` command will be available globally.

---

## Quick Start

### 1. Start a new project

```bash
mkdir my-project && cd my-project
safeenv init
```

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SafeEnv Initialization
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✓  Python version detected: 3.11
  ✓  Virtual environment created: .venv

  Your environment is ready.

  To activate:

    Mac / Linux:
      source .venv/bin/activate

    Windows:
      .venv\Scripts\activate
```

### 2. Scan your project and generate requirements.txt

```bash
safeenv freeze
```

```
  Scanning project for imports...

  ✓  Flask
  ✓  numpy
  ✓  pandas
  ✓  requests

  ✓  requirements.txt generated with 4 packages.
```

`safeenv freeze` uses Python **AST parsing** — it reads your source files without
executing them, so it is completely safe.

### 3. Get a cloned project running in one command

```bash
git clone https://github.com/someone/awesome-project.git
cd awesome-project
safeenv setup
```

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Project Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Checking environment...

  ✓  Python version compatible: 3.11
  ✓  Virtual environment created: .venv

  Installing dependencies...

  ✓  Flask installed
  ✓  numpy installed
  ✓  pandas installed

  Project setup complete.
```

### 4. Check project health

```bash
safeenv doctor
```

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Project Health Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Python version      :  3.11
  Virtual environment :  detected
  requirements.txt    :  found

  Issues found:

  ⚠  Missing dependency: torch
  ⚠  Missing dependency: fastapi

  Recommendation:

    Run:  safeenv fix
```

### 5. Fix problems automatically

```bash
safeenv fix
```

```
  Repairing environment...

  ✓  Virtual environment: OK
  
  Missing package detected: torch
  Installing torch...
  ✓  torch installed

  Missing package detected: fastapi
  Installing fastapi...
  ✓  fastapi installed

  ✓  Environment repaired successfully.
```

---

## Command Reference

### `safeenv init`

Creates a `.venv` virtual environment in the current directory using the
active Python interpreter.

```bash
safeenv init                    # current directory
safeenv init --dir /path/to/project
```

- Safe to run multiple times — will never overwrite an existing `.venv`
- Displays platform-specific activation instructions

---

### `safeenv freeze`

Scans all `.py` files in the project using Python AST parsing and writes
a `requirements.txt`.

```bash
safeenv freeze                           # writes requirements.txt
safeenv freeze --output deps.txt         # custom output file
safeenv freeze --dir /path/to/project    # specific directory
```

**How it works:**

1. Recursively walks all `.py` files (ignores `.venv`, `__pycache__`, etc.)
2. Parses each file with `ast.parse()` — no code is executed
3. Collects all `import` and `from ... import` statements
4. Filters out Python standard-library modules
5. Maps import names to correct PyPI names (e.g. `cv2` → `opencv-python`)
6. Writes a sorted `requirements.txt`

---

### `safeenv setup`

The single command to run after cloning a project. Combines `init` + dependency installation.

```bash
safeenv setup
safeenv setup --dir /path/to/project
```

**Steps performed:**
1. Checks Python version compatibility
2. Creates `.venv` if not present
3. Reads `requirements.txt`
4. Installs each package into `.venv`

---

### `safeenv doctor`

Performs a read-only health check and lists all issues. Never modifies anything.

```bash
safeenv doctor
safeenv doctor --dir /path/to/project
```

**Checks:**
- Python version (minimum: 3.7)
- `.venv` directory presence
- `requirements.txt` presence
- Packages listed in `requirements.txt` that are not installed

---

### `safeenv fix`

Automatically resolves issues reported by `safeenv doctor`.

```bash
safeenv fix
safeenv fix --dir /path/to/project
```

**Actions:**
- Creates `.venv` if missing
- Installs any missing packages from `requirements.txt`

---

## Import Name Mapping

`safeenv freeze` automatically translates common import names to their correct
PyPI package names:

| Import name  | PyPI package        |
|--------------|---------------------|
| `cv2`        | `opencv-python`     |
| `PIL`        | `Pillow`            |
| `sklearn`    | `scikit-learn`      |
| `bs4`        | `beautifulsoup4`    |
| `yaml`       | `PyYAML`            |
| `dotenv`     | `python-dotenv`     |
| `dateutil`   | `python-dateutil`   |
| `serial`     | `pyserial`          |
| `jwt`        | `PyJWT`             |
| `git`        | `GitPython`         |

_(and many more — see `dependency_scanner.py` for the full list)_

---

## Requirements

- Python 3.8 or newer
- Works on **Windows**, **macOS**, and **Linux**
- Runtime dependencies: `typer` and `rich` (both installed automatically)

---

## Development Setup

```bash
git clone https://github.com/safeenv/safeenv.git
cd safeenv
pip install -e ".[dev]"
```

### Run tests

```bash
pytest
```

### Run tests with coverage

```bash
pytest --cov=safeenv --cov-report=term-missing
```

---

## Project Structure

```
safeenv/
│
├── safeenv/
│   ├── __init__.py          # Package metadata and version
│   ├── cli.py               # Typer CLI commands (init, freeze, setup, doctor, fix)
│   ├── env_manager.py       # Virtual environment creation and detection
│   ├── dependency_scanner.py # AST-based import scanning and requirements generation
│   ├── installer.py         # pip-based package installation helpers
│   ├── doctor.py            # Project health diagnostics
│   └── utils.py             # Shared Rich console and styled print utilities
│
├── tests/
│   ├── conftest.py          # Shared pytest fixtures
│   ├── test_env_manager.py  # Tests for virtual environment logic
│   ├── test_dependency_scanner.py  # Tests for AST scanning
│   └── test_cli.py          # Integration tests for CLI commands
│
├── README.md
├── LICENSE
└── pyproject.toml
```

---

## Contributing

Contributions are welcome! Here is how to get started:

1. **Fork** the repository on GitHub
2. **Clone** your fork locally:
   ```bash
   git clone https://github.com/your-username/safeenv.git
   cd safeenv
   pip install -e ".[dev]"
   ```
3. **Create a branch** for your change:
   ```bash
   git checkout -b feature/my-improvement
   ```
4. **Make your changes** — follow the existing code style
5. **Run the tests** to make sure everything still works:
   ```bash
   pytest
   ```
6. **Open a Pull Request** with a clear description of what you changed and why

### Guidelines

- Keep the tool lightweight and beginner-friendly
- Add tests for any new functionality
- Write clear docstrings for new functions
- Use type hints throughout
- Prefer simple, readable code over clever one-liners

---

## License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

---

<div align="center">
  Built with ❤️ for students and developers who just want their code to run.
</div>
