safeenv-tool 0.1.0

Automatic Python environment manager for students and developers

🛡 safeenv

Automatic Python environment manager for students and developers

---

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

pip install safeenv

Or install in editable/development mode from source:

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

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

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

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

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

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.

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.

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.

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.

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.

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

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

Run tests

pytest

Run tests with coverage

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:

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

3. Create a branch for your change:

   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:

   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 file for details.

---

Built with ❤️ for students and developers who just want their code to run.