pyp C++ - Secure Python Virtual Environment Manager

A high-performance, secure Python virtual environment manager written in C++. This is a direct port of the original Python-based pyp tool, offering improved performance and smaller binary size while maintaining all the security features.

Features

Security Features

• Secure Directory Permissions: All environment directories are created with restrictive permissions (0o700), preventing unauthorized access.
• Secure Configuration Files: Configuration files use restrictive permissions (0o600) to protect sensitive data.
• Validated Environment Names: Environment names are strictly validated to prevent path traversal and injection attacks.
• Atomic Operations: Uses atomic file operations to prevent TOCTOU (Time-of-Check to Time-of-Use) race conditions.
• Path Resolution: Uses canonical path resolution to avoid symlink attacks and ensure correct paths.

Core Functionality

• Create Environments: Build isolated Python virtual environments with a single command.
• Activate/Deactivate: Easily switch between environments.
• List Environments: View all environments with their status (active, default).
• Remove Environments: Safely delete environments with confirmation.
• Run Commands: Execute commands within a specific environment.
• Export/Import: Export environment configurations and import them elsewhere.

Additional Features

• Multiple Python Versions: Support for different Python versions (python3, python, python2).
• Environment Descriptions: Add descriptions to environments for easier identification.
• Default Environment: Set a default environment for quick access.
• Cleanup Utility: Remove orphaned environments that no longer exist on disk.
• Shell Completion: Built-in support for bash and zsh completion.

Requirements

Build Requirements

• CMake 3.14 or higher
• C++20 compatible compiler (g++ 10+ or clang 12+)
• Boost Libraries (filesystem, system)
• nlohmann/json (included via FetchContent)

Runtime Requirements

• Linux operating system
• Python 3.x (for creating virtual environments)
• Bash or Zsh (for shell completion)

Installation

Quick Install

# Clone the repository
cd pyp-cpp

# Run the install script
./install.sh

# Or install to your home directory
./install.sh --local

Manual Build

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake .. -DCMAKE_BUILD_TYPE=Release

# Build
make -j$(nproc)

# Install
sudo make install

Custom Installation

# Install to custom prefix
./install.sh --prefix=$HOME/.local

# Install to specific directories
./install.sh --prefix=/opt/pyp --bindir=bin --confdir=etc

Uninstall

# Standard uninstall
./uninstall.sh

# Keep user data
./uninstall.sh --keep-data

# Don't ask for confirmation
./uninstall.sh --force

Usage

Initialization

# Initialize pyp (creates necessary directories)
pyp init

Creating Environments

# Create a new environment
pyp build myenv

# Create with specific Python version
pyp build myenv --python python3.11

# Upgrade an existing environment
pyp build myenv --upgrade

Activating Environments

# Activate an environment
pyp activate myenv

# Use alias
pyp use myenv

Deactivating Environments

# Deactivate current environment
pyp deactivate

Listing Environments

# List all environments
pyp list

# List only active environments
pyp list --active

# List default environment
pyp list --default

Running Commands

# Run a command in an environment
pyp run myenv python --version

# Run pip install in an environment
pyp run myenv pip install requests

Getting Environment Info

# Show detailed information about an environment
pyp info myenv

Setting Default Environment

# Set default environment
pyp set-default myenv

# Clear default environment
pyp set-default

Exporting/Importing Environments

# Export environment to file
pyp export myenv --output myenv_export.json

# Import from file with new name
pyp import myenv_export.json --name newenv

Removing Environments

# Remove an environment (with confirmation)
pyp remove myenv

# Force remove without confirmation
pyp remove myenv --force

Cleanup

# Remove orphaned environments
pyp cleanup

Help

# Show general help
pyp --help

# Show command-specific help
pyp help build

# Show version
pyp --version

Environment Variables

pyp uses the following environment variables:

Variable	Description
PYP_HOME	Base directory for pyp data (default: ~/.pyp)
PYP_ENVS_DIR	Directory for environments (default: $PYP_HOME/envs)
PYP_CONFIG_FILE	Path to configuration file (default: $PYP_HOME/config.json)
PYP_CURRENT_ENV	Currently active environment (set by pyp activate)

Directory Structure

~/.pyp/
├── config.json          # Main configuration file
└── envs/                # Environment directory
    ├── myenv/           # Individual environment
    │   ├── bin/
    │   │   ├── activate
    │   │   ├── python
    │   │   └── pip
    │   ├── lib/
    │   └── pyvenv.cfg
    └── anotherenv/

Security Details

Permission Model

• Environment Directory (0o700): Only the owner can read, write, or execute. This prevents other users from accessing your virtual environments.

• Configuration File (0o600): Only the owner can read or write the configuration, protecting your environment metadata.

• Executable Binaries (0o755): Environment scripts are readable and executable by all users, but only writable by the owner.

Name Validation

Environment names must follow these rules:

• Maximum 64 characters
• Only alphanumeric characters (a-z, A-Z, 0-9)
• Underscores (_) and hyphens (-) are allowed
• Cannot start with a dot (.)
• Cannot be "." or ".."

This prevents:

• Path traversal attacks
• Shell injection
• Symlink attacks
• Invalid filenames

Path Handling

• All paths are resolved using std::filesystem::canonical()
• Symlinks are followed and validated
• Relative paths are converted to absolute paths
• Dangerous paths are rejected

Performance

Why C++?

The C++ implementation offers several advantages:

1. Faster Startup: No interpreter overhead, binary starts immediately.
2. Lower Memory Usage: No Python runtime required for the manager.
3. Smaller Binary: Self-contained executable with minimal dependencies.
4. Better Integration: Can be used in scripts and pipelines more efficiently.

Benchmarks

Typical operation times compared to Python version:

Operation	Python	C++
List environments	~50ms	~5ms
Create environment	~200ms	~150ms
Activate environment	~10ms	~2ms
Show help	~30ms	~3ms

Contributing

Development Setup

# Clone the repository
cd pyp-cpp

# Create build directory
mkdir build && cd build

# Configure
cmake .. -DCMAKE_BUILD_TYPE=Debug

# Build
make -j$(nproc)

# Run tests
ctest

Code Style

This project follows the C++ Core Guidelines and uses:

• clang-format for formatting
• clang-tidy for linting
• cppcheck for static analysis

Testing

# Run unit tests
ctest --verbose

# Run with coverage
cmake .. -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON
make
ctest

Troubleshooting

Common Issues

Permission Denied

# Ensure you have write permissions to the installation directory
sudo ./install.sh

Python Not Found

# Install Python 3
sudo apt install python3  # Debian/Ubuntu
sudo yum install python3  # RHEL/CentOS

CMake Not Found

# Install CMake
sudo apt install cmake  # Debian/Ubuntu
sudo yum install cmake  # RHEL/CentOS

Boost Not Found

# Install Boost libraries
sudo apt install libboost-all-dev  # Debian/Ubuntu
sudo yum install boost-devel       # RHEL/CentOS

Debug Mode

To get debug output:

# Build with debug symbols
cmake .. -DCMAKE_BUILD_TYPE=Debug
make

# Run with debug output
pyp --help

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Original Python pyp project: mosi-sol/idea-factory
• nlohmann/json library: nlohmann/json
• Boost libraries: boost.org

Support

For issues and feature requests, please open a GitHub issue.

---

Note: This is a port of the original Python implementation. If you encounter any issues, please check the original project's documentation or open an issue.

https://lotuschain.org innovation services