Pivvo

    ____  _                 
   / __ \(_)   ___   ______ 
  / /_/ / / | / / | / / __ \
 / ____/ /| |/ /| |/ / /_/ /
/_/   /_/ |___/ |___/\____/ 
  

A small, pragmatic CLI tool to initialize and manage Python projects with ease. Bootstrap your projects, manage dependencies, and streamline your workflow—all from the command line.

pivvo helps developers quickly set up Python projects with virtual environments, Git repositories, and essential files. It provides a suite of commands to manage dependencies, run scripts, and maintain your project's environment without leaving the terminal.

Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Quickstart
• 📖 Commands
• 🛠️ Development
• 🤝 Contributing
• 📄 License
• 👥 Authors

✨ Features

• Project Initialization: Create new Python projects with virtual environments, Git repos, and basic files in seconds
• Dependency Management: Install, list, freeze, upgrade, and remove packages within the project's venv
• Script Execution: Run Python scripts directly inside the project's virtual environment
• Beautiful Output: Rich terminal interface with progress indicators and colored output
• Error Handling: Comprehensive error logging for troubleshooting
• Cross-Platform: Works on Windows, macOS, and Linux
• Lightweight: Minimal dependencies for fast installation and execution

📦 Installation

From PyPI (Recommended)

pip install pivvo

From Source

git clone https://github.com/Flaxmbot/pivvo.git
cd pivvo
pip install -e .

Prerequisites

• Python 3.10 or higher
• pip (usually included with Python)

🚀 Quickstart

1. Install pivvo:

   pip install pivvo
   

2. Initialize a new project:

   pivvo init my-awesome-project
   cd my-awesome-project
   

3. Install dependencies:

   pivvo install-deps requests flask python-dotenv
   

4. Run your application:

   pivvo run app.py
   

That's it! Your project is ready with a virtual environment, Git repository, and all dependencies installed.

📖 Commands

pivvo provides the following commands:

Getting Help

# General help
pivvo --help

# Command-specific help
pivvo install-deps --help
pivvo init --help

🛠️ Development

Setting Up Development Environment

git clone https://github.com/Flaxmbot/pivvo.git
cd pivvo
python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
pip install -r requirements.txt

Project Structure

pivvo/
├── pivvo/
│   ├── __init__.py
│   ├── cli.py          # Main CLI implementation
│   └── main.py         # Package entry point
├── tests/              # Unit tests
├── requirements.txt    # Dependencies
├── pyproject.toml      # Package configuration
├── LICENSE
├── CONTRIBUTING.md
└── README.md

Running Tests

# Install test dependencies
pip install pytest

# Run tests
pytest

# Run with coverage
pytest --cov=pivvo

Development Notes

• CLI Implementation: Located in pivvo/cli.py using Typer for argument parsing
• Terminal Output: Uses Rich for beautiful, colored terminal output
• Error Logging: Failed subprocess commands are logged to pivvo-error.log
• Git Integration: Uses GitPython for repository initialization
• Cross-Platform: Handles different Python executable paths for Windows/macOS/Linux

Tips for Windows Development

When using Git Bash on Windows, you might see raw ANSI escape codes. Solutions:

• Force ANSI rendering: Modify cli.py to use Console(force_terminal=True, color_system="auto")
• Use winpty: winpty python pivvo/main.py ...
• Use PowerShell, CMD, or Windows Terminal instead of Git Bash

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Reporting bugs
• Requesting features
• Setting up your development environment
• Submitting pull requests
• Code style guidelines

Quick Contribution Flow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Add tests for your changes
4. Ensure all tests pass: pytest
5. Commit your changes: git commit -m "Add amazing feature"
6. Push to your branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

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

👥 Authors

• Devrat Kuntal - Creator & Maintainer - rdxdevbhai76@gmail.com