pckgr 1.0.0

No project description provided

pckgr 📦

A comprehensive Python package management tool that simplifies the entire development workflow from initialization to deployment.

📑 Table of Contents

1. Features
2. Requirements
3. Installation
   • 3.1 Install Python 3.8+
   • 3.2 Install pckgr System-Wide
   • 3.3 Set Up GitHub Integration
4. Quick Start
   • 4.1 Initialize a New Package
   • 4.2 Multi-Repository Management
5. Command Reference
   • 5.1 Package Management
   • 5.2 Version Control
   • 5.3 Development Tools
   • 5.4 Configuration
6. Advanced Configuration
   • 6.1 Global Settings
   • 6.2 Git Configuration
   • 6.3 Package Aliases
7. Error Handling
8. Multi-Repository Workflow
9. Troubleshooting
   • 9.1 Common Issues
   • 9.2 Debug Mode
10. License
11. Contributing
12. Support
13. Examples
    • 13.1 Basic Package Development
    • 13.2 Multi-Project Management
    • 13.3 Development Workflow

✨ Features

• 🚀 Quick Package Initialization: Set up new Python packages with all necessary files
• 📋 Smart Dependency Management: Automatically detect and manage project dependencies
• 🔄 Multi-Repository Operations: Bulk push/pull operations across multiple git repositories
• 🛠️ Development Tools: TODO scanning, code statistics, and mini-games
• ⚙️ Configuration Management: Advanced git and build system configuration
• 🎯 Interactive CLI: User-friendly prompts with validation and error handling

📋 Requirements

• Python 3.8 or higher
• Git (for version control operations)
• GitHub CLI (gh) (for seamless GitHub integration)
• SSH keys configured with GitHub (recommended for secure authentication)
• Internet connection (for package installation and GitHub operations)

🔧 Installation

Step 1: Install Python 3.8+

Windows

1. Download Python from python.org
2. Important: Check "Add Python to PATH" during installation
3. Verify installation:

   python --version
   pip --version
   

macOS

# Using Homebrew (recommended)
brew install python@3.8

# Or download from python.org

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3.8 python3.8-pip python3.8-venv

Linux (CentOS/RHEL/Fedora)

# Fedora
sudo dnf install python3.8 python3.8-pip

# CentOS/RHEL (requires EPEL)
sudo yum install python3.8 python3.8-pip

Step 2: Install pckgr System-Wide

⚠️ Important: Install pckgr system-wide (not in a virtual environment) to enable pckgr init to work from any directory.

# Install from PyPI (recommended)
pip install pckgr

# Or install from GitHub (latest development version)
pip install git+https://github.com/HiDrNikki/pckgr.git

Verify Installation:

pckgr --help

Step 3: Set Up GitHub Integration

pckgr is designed to work seamlessly with GitHub. Follow these steps to set up proper authentication:

Install GitHub CLI

# Windows (using winget)
winget install --id GitHub.cli

# Windows (using Chocolatey)
choco install gh

# macOS (using Homebrew)
brew install gh

# Linux (Ubuntu/Debian)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Linux (CentOS/RHEL/Fedora)
sudo dnf install gh

Authenticate with GitHub

# Login to GitHub (opens browser for authentication)
gh auth login

# Choose:
# - GitHub.com
# - HTTPS or SSH (recommend SSH for better security)
# - Authenticate via web browser

Set Up SSH Keys (Recommended)

# Generate SSH key (replace with your email)
ssh-keygen -t ed25519 -C "[e-mail]"

# Start SSH agent
# Windows (PowerShell)
Start-Service ssh-agent
ssh-add ~/.ssh/id_ed25519

# macOS/Linux
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Add SSH key to GitHub (automatically)
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My Development Machine"

# Test SSH connection
ssh -T [e-mail]

Configure Git

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"
git config --global user.github "your-github-username"

# Set default branch name
git config --global init.defaultBranch main

# Optional: Enable signed commits (if you have GPG set up)
git config --global commit.gpgsign true

🚀 Quick Start

Initialize a New Package

mkdir new-package
cd new-package
pckgr init

This will:

• Create package structure (src/, tests/, etc.)
• Generate pyproject.toml with your details
• Set up virtual environment
• Initialize git repository
• Install detected dependencies

Multi-Repository Management

# From a directory containing multiple git repositories
cd /path/to/projects

# Push all repositories with changes
pckgr push --all -m "Update all projects"

# Interactive push (choose individual repositories)
pckgr push -m "Selective updates"

# Skip dependency updates for faster operation
pckgr push --skip-deps --all -m "Quick push"

📚 Command Reference

Package Management

pckgr init

Initialize a new Python package in the current directory.

pckgr init                    # Interactive setup
pckgr init --pull             # Pull from existing repository

What it does:

• Creates standard Python package structure
• Generates pyproject.toml with metadata
• Sets up virtual environment
• Detects and installs dependencies
• Initializes git repository
• Creates initial commit

pckgr build

Build and optionally upload the package.

pckgr build                             # Build only (minor version bump)
pckgr build --patch                     # Build with patch version bump
pckgr build --major                     # Build with major version bump
pckgr build --version "1.2.3"          # Build with specific version
pckgr build --upload                    # Build and upload to PyPI
pckgr build --test-pypi                 # Upload to Test PyPI
pckgr build --version "2.0.0" --upload # Set version and upload

Version Control

pckgr push

Commit and push changes to git repository.

pckgr push -m "Commit message"              # Basic push
pckgr push -m "Message" --tag               # Push with tags
pckgr push --all -m "Message"               # Multi-repo: push all
pckgr push --skip-deps -m "Message"         # Skip dependency updates
pckgr push --dry-run -m "Message"           # Preview without changes
pckgr push --version "1.2.3" -m "Message"  # Set specific version before push

Multi-Repository Features:

• Automatically detects git repositories in subdirectories
• Only shows repositories with uncommitted changes
• Interactive or bulk push modes
• Continues on errors with user choice
• Smart dependency updates per repository
• Note: --version flag not available for multi-repository pushes

pckgr pull

Pull latest changes from git repository.

pckgr pull                    # Pull from default branch
pckgr pull -b develop         # Pull from specific branch
pckgr pull -r upstream        # Pull from specific remote

pckgr patch

Apply patch files from .pckgr/patches/.

pckgr patch                   # Apply all patches

Development Tools

pckgr tools

Various development utilities and mini-tools.

# TODO Management
pckgr tools --todo                          # Scan for TODO items
pckgr tools --todo --priority               # Include priority parsing
pckgr tools --todo --tags todo,fixme        # Filter by tags
pckgr tools --todo --group-by priority      # Group by priority
pckgr tools --todo --group-by tag           # Group by tag type

# Code Statistics
pckgr tools --stats                         # Show code statistics

# Dependency Management
pckgr tools --update-dependencies           # Update dependencies

TODO Scanner Features:

• Supports: TODO, FIXME, HACK, XXX, NOTE, WARNING, BUG
• Priority parsing: (HIGH), [CRITICAL], !!!
• Multiple comment styles: #, //, /* */, <!-- -->
• Grouping and filtering options

Configuration

pckgr config

Manage pckgr and git configuration.

pckgr config --show          # Show current config
pckgr config --init          # Initialize with defaults

Configuration Features:

• Git remote management
• Custom build backends
• Upload targets (PyPI, Test PyPI)
• Command flags and hooks
• Author information storage

pckgr tree

Display project directory structure (respects .gitignore).

pckgr tree                    # Show project tree

pckgr help

Show help information.

pckgr help                    # General help
pckgr <command> --help        # Command-specific help

⚙️ Advanced Configuration

Global Settings

pckgr stores global settings in module_settings.json:

{
  "global": {
    "author": {
      "name": "Your Name",
      "email": "[e-mail]", 
      "github": "your-username"
    },
    "default_license": "MIT",
    "python_requires": ">=3.8"
  },
  "performance": {
    "max_parallel_processes": 4,
    "enable_parallel_processing": true
  }
}

Git Configuration

Project-specific git settings in .pckgr/settings.json:

{
  "git": {
    "default_remote": "origin",
    "default_branch": "main",
    "remotes": {
      "origin": {"url": "...", "type": "github"},
      "upstream": {"url": "...", "type": "github"}
    },
    "commands": {
      "push_flags": [],
      "pull_flags": [],
      "commit_flags": ["-S"]
    }
  }
}

Package Aliases

Common package name mappings for dependency detection:

{
  "common_aliases": {
    "cv2": "opencv-python",
    "PIL": "Pillow", 
    "sklearn": "scikit-learn",
    "bs4": "beautifulsoup4"
  }
}

🔍 Error Handling

pckgr uses numbered error codes for structured error handling:

• 100-199: File system errors
• 200-299: Git/version control errors
• 300-399: Package management errors
• 400-499: Configuration errors
• 500-599: User input errors
• 1000+: Soft errors (warnings)

🤝 Multi-Repository Workflow

Perfect for managing multiple projects:

# Directory structure
/projects/
  ├── project-a/     (git repo)
  ├── project-b/     (git repo)  
  ├── project-c/     (git repo)
  └── other-files

# From /projects/ directory
pckgr push --all -m "Update all projects"

Features:

• Only processes repositories with changes
• Interactive or automatic mode
• Continues on individual failures
• Per-project dependency updates
• Progress tracking and summaries

🐛 Troubleshooting

Common Issues

1. "Command not found" after installation

# Ensure Python scripts directory is in PATH
# Windows: Add %APPDATA%\Python\Python38\Scripts to PATH
# macOS/Linux: Add ~/.local/bin to PATH

2. "Permission denied" errors

# Use --user flag for user installation
pip install --user git+https://github.com/HiDrNikki/pckgr.git

3. Dependency update hanging

# Skip dependency updates
pckgr push --skip-deps -m "Message"

4. Virtual environment issues

# Ensure pckgr is installed globally, not in venv
pip list | grep pckgr

5. GitHub authentication issues

# Check if you're logged in
gh auth status

# Re-authenticate if needed
gh auth login

# Test SSH connection
ssh -T [e-mail]
# Should show: "Hi username! You've successfully authenticated..."

6. SSH key problems

# List SSH keys added to GitHub
gh ssh-key list

# Add existing SSH key
gh ssh-key add ~/.ssh/id_ed25519.pub

# Generate new SSH key if needed
ssh-keygen -t ed25519 -C "[e-mail]"

7. Git remote issues

# Check current remotes
git remote -v

# Switch from HTTPS to SSH (if needed)
git remote set-url origin [e-mail]:username/repository.git

Debug Mode

# Enable verbose output (if implemented)
pckgr --verbose <command>

📄 License

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

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📧 Support

• Issues: GitHub Issues
• Email: [e-mail]
• Documentation: This README and pckgr --help

🎯 Examples

Basic Package Development

# Create new package
mkdir my-package && cd my-package
pckgr init

# Develop your code...
# src/my_package/main.py

# Commit and push
pckgr push -m "Initial implementation"

# Build and upload
pckgr build --upload

Multi-Project Management

# From directory with multiple projects
pckgr push --all -m "Weekly updates"

# Interactive mode
pckgr push -m "Selective updates"
# Choose: [i]ndividual/[a]ll/[c]ancel: i
# Push repository 'project-a'? (y/N): y

Development Workflow

# Check TODOs before committing
pckgr tools --todo --priority

# Update dependencies
pckgr tools --update-dependencies

# Quick stats
pckgr tools --stats

# Push with clean dependencies
pckgr push -m "Clean update"

---

pckgr - Making Python package management simple and efficient! 🚀