A comprehensive, production-ready Go SDK for managing Python pip operations, virtual environments, and Python projects. This library provides a clean, type-safe interface for all common pip operations with enterprise-grade features and cross-platform support.
English | 简体中文
- Cross-platform support - Works seamlessly on Windows, macOS, and Linux
- Complete pip operations - Install, uninstall, list, show, freeze, search packages
- Virtual environment management - Create, activate, deactivate, remove, clone virtual environments
- Project initialization - Bootstrap Python projects with customizable templates
- Automatic pip installation - Detects and installs pip if missing with multiple installation methods
- Production-ready - Battle-tested in enterprise environments
- Comprehensive logging - Structured logging with multiple output formats (JSON, text)
- Advanced error handling - Rich error types with actionable suggestions and retry mechanisms
- Configuration management - Flexible configuration with environment variable support
- Security features - Certificate validation, trusted hosts, and secure package installation
- Type-safe API - Full Go type safety with comprehensive interfaces
- Extensive testing - 95%+ test coverage with unit and integration tests
- Rich documentation - Complete API documentation with examples
- Command-line interface - Full-featured CLI tool for direct usage
- Docker support - Official Docker images and containerized deployment options
go get github.com/scagogogo/go-pip-sdk
go get github.com/scagogogo/[email protected]
- Go: 1.19 or later
- Python: 3.7 or later (for pip operations)
- Operating System: Windows 10+, macOS 10.15+, or Linux (any modern distribution)
package main
import (
"fmt"
"log"
"github.com/scagogogo/go-pip-sdk/pkg/pip"
)
func main() {
// Create a new pip manager with default configuration
manager := pip.NewManager(nil)
// Check if pip is installed and install if missing
if installed, err := manager.IsInstalled(); err != nil {
log.Fatal(err)
} else if !installed {
fmt.Println("Installing pip...")
if err := manager.Install(); err != nil {
log.Fatal(err)
}
fmt.Println("✅ Pip installed successfully!")
}
// Install a package with version constraints
pkg := &pip.PackageSpec{
Name: "requests",
Version: ">=2.25.0,<3.0.0",
Extras: []string{"security"}, // Install with extras
}
fmt.Printf("Installing %s...\n", pkg.Name)
if err := manager.InstallPackage(pkg); err != nil {
log.Fatal(err)
}
fmt.Println("✅ Package installed successfully!")
// List installed packages
packages, err := manager.ListPackages()
if err != nil {
log.Fatal(err)
}
fmt.Printf("Found %d installed packages\n", len(packages))
}
package main
import (
"time"
"github.com/scagogogo/go-pip-sdk/pkg/pip"
)
func main() {
// Create custom configuration
config := &pip.Config{
PythonPath: "/usr/bin/python3",
Timeout: 120 * time.Second,
Retries: 5,
LogLevel: "INFO",
DefaultIndex: "https://pypi.org/simple/",
TrustedHosts: []string{"pypi.org", "pypi.python.org"},
Environment: map[string]string{
"PIP_CACHE_DIR": "/tmp/pip-cache",
},
}
manager := pip.NewManager(config)
// Your pip operations here...
}
// Install packages with various options
pkg := &pip.PackageSpec{
Name: "fastapi",
Version: ">=0.68.0,<1.0.0",
Extras: []string{"all"},
Upgrade: true,
ForceReinstall: false,
UserInstall: false,
}
err := manager.InstallPackage(pkg)
// Install from requirements file
err = manager.InstallRequirements("requirements.txt")
// Install from Git repository
gitPkg := &pip.PackageSpec{
Name: "git+https://github.com/user/[email protected]",
}
err = manager.InstallPackage(gitPkg)
// Uninstall packages
err = manager.UninstallPackage("requests")
// List installed packages with details
packages, err := manager.ListPackages()
for _, pkg := range packages {
fmt.Printf("%s==%s (%s)\n", pkg.Name, pkg.Version, pkg.Location)
}
// Show detailed package information
info, err := manager.ShowPackage("requests")
fmt.Printf("Name: %s\nVersion: %s\nSummary: %s\n",
info.Name, info.Version, info.Summary)
// Search for packages
results, err := manager.SearchPackages("web framework")
// Check for outdated packages
outdated, err := manager.CheckOutdated()
// Freeze packages (like pip freeze)
packages, err := manager.FreezePackages()
// Create virtual environment with options
opts := &pip.VenvOptions{
PythonVersion: "3.9",
SystemSitePackages: false,
Prompt: "my-project",
UpgradePip: true,
}
err := manager.CreateVenvWithOptions("/path/to/venv", opts)
// Activate virtual environment
err = manager.ActivateVenv("/path/to/venv")
// Check if virtual environment is active
isActive, venvPath := manager.IsVenvActive()
if isActive {
fmt.Printf("Active virtual environment: %s\n", venvPath)
}
// List all virtual environments
venvs, err := manager.ListVenvs("/path/to/envs")
// Get detailed virtual environment information
info, err := manager.GetVenvInfo("/path/to/venv")
fmt.Printf("Python version: %s\nPackages: %d\n",
info.PythonVersion, info.PackageCount)
// Clone virtual environment
err = manager.CloneVenv("/path/to/source", "/path/to/target")
// Remove virtual environment
err = manager.RemoveVenv("/path/to/venv")
// Initialize a comprehensive Python project
opts := &pip.ProjectOptions{
Name: "my-awesome-project",
Version: "0.1.0",
Description: "A comprehensive Python project",
Author: "Your Name",
AuthorEmail: "[email protected]",
License: "MIT",
Homepage: "https://github.com/user/my-awesome-project",
Repository: "https://github.com/user/my-awesome-project.git",
// Dependencies
Dependencies: []string{
"fastapi>=0.68.0",
"uvicorn[standard]>=0.15.0",
"pydantic>=1.8.0",
},
DevDependencies: []string{
"pytest>=6.0.0",
"black>=21.0.0",
"flake8>=3.8.0",
"mypy>=0.812",
},
// Project structure
CreateVenv: true,
CreateSrc: true,
CreateTests: true,
CreateDocs: true,
CreateGithubActions: true,
CreateDockerfile: true,
// Configuration files
CreateSetupPy: true,
CreatePyprojectToml: true,
CreateGitignore: true,
CreateReadme: true,
}
err := manager.InitProject("/path/to/project", opts)
// Read project configuration
config, err := manager.ReadProjectConfig("/path/to/project")
// Update project version
err = manager.UpdateProjectVersion("/path/to/project", "1.0.0")
// Build project
buildOpts := &pip.BuildOptions{
OutputDir: "./dist",
Format: "wheel",
Clean: true,
}
err = manager.BuildProject("/path/to/project", buildOpts)
config := &pip.Config{
// Python settings
PythonPath: "/usr/bin/python3",
PipPath: "/usr/bin/pip3",
// Network settings
Timeout: 120 * time.Second,
Retries: 5,
DefaultIndex: "https://pypi.org/simple/",
ExtraIndexes: []string{
"https://pypi.python.org/simple/",
"https://test.pypi.org/simple/",
},
TrustedHosts: []string{"pypi.org", "pypi.python.org"},
// Cache settings
CacheDir: "/tmp/pip-cache",
NoCache: false,
// Logging
LogLevel: "INFO",
LogFile: "/var/log/pip-sdk.log",
// Environment variables
Environment: map[string]string{
"PIP_CACHE_DIR": "/tmp/pip-cache",
"PIP_DISABLE_PIP_VERSION_CHECK": "1",
"PIP_TIMEOUT": "120",
},
}
manager := pip.NewManager(config)
// Enterprise-grade configuration with security features
config := &pip.Config{
PythonPath: "/opt/python/bin/python3",
DefaultIndex: "https://pypi.company.com/simple/",
ExtraIndexes: []string{
"https://pypi.org/simple/",
},
TrustedHosts: []string{
"pypi.company.com",
"pypi.org",
},
Timeout: 300 * time.Second,
Retries: 10,
// Security settings
ExtraOptions: map[string]string{
"cert": "/etc/ssl/certs/company-ca.pem",
"client-cert": "/etc/ssl/certs/client.pem",
"trusted-host": "pypi.company.com",
},
// Logging for audit trails
LogLevel: "INFO",
LogFile: "/var/log/pip-operations.log",
}
// Create structured logger with multiple outputs
loggerConfig := &pip.LoggerConfig{
Level: pip.LogLevelDebug,
Format: pip.LogFormatJSON,
EnableFile: true,
LogFile: "/var/log/pip-sdk.log",
MaxSize: 100, // 100MB
MaxBackups: 5,
MaxAge: 30, // 30 days
Compress: true,
// Add custom fields to all log entries
Fields: map[string]interface{}{
"service": "pip-manager",
"version": "1.0.0",
"environment": os.Getenv("ENVIRONMENT"),
},
}
logger, err := pip.NewLogger(loggerConfig)
if err != nil {
log.Fatal(err)
}
defer logger.Close()
// Set custom logger
manager.SetCustomLogger(logger)
// Use contextual logging
contextLogger := logger.WithFields(map[string]interface{}{
"operation": "package_install",
"user_id": "12345",
})
// Comprehensive error handling with retry logic
func installWithRetry(manager *pip.Manager, pkg *pip.PackageSpec, maxRetries int) error {
var lastErr error
for attempt := 0; attempt < maxRetries; attempt++ {
err := manager.InstallPackage(pkg)
if err == nil {
return nil // Success
}
lastErr = err
// Handle different error types
switch pip.GetErrorType(err) {
case pip.ErrorTypeNetworkError, pip.ErrorTypeNetworkTimeout:
// Retry network errors with exponential backoff
delay := time.Duration(1<<uint(attempt)) * time.Second
fmt.Printf("Network error, retrying in %v... (%d/%d)\n", delay, attempt+1, maxRetries)
time.Sleep(delay)
continue
case pip.ErrorTypePermissionDenied:
// Try user installation for permission errors
if attempt == 0 {
pkg.UserInstall = true
continue
}
return err
case pip.ErrorTypePackageNotFound:
// Suggest alternatives for missing packages
if results, searchErr := manager.SearchPackages(pkg.Name); searchErr == nil && len(results) > 0 {
fmt.Printf("Package '%s' not found. Similar packages:\n", pkg.Name)
for i, result := range results[:3] {
fmt.Printf("%d. %s - %s\n", i+1, result.Name, result.Summary)
}
}
return err
default:
return err // Don't retry other errors
}
}
return fmt.Errorf("failed after %d retries: %w", maxRetries, lastErr)
}
// Use context for timeout and cancellation
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()
manager := pip.NewManagerWithContext(ctx, config)
// Operations will respect context cancellation
err := manager.InstallPackage(pkg)
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
fmt.Println("Operation timed out")
} else if errors.Is(err, context.Canceled) {
fmt.Println("Operation was canceled")
}
}
// Monitor operation performance
func monitoredInstall(manager *pip.Manager, pkg *pip.PackageSpec) error {
start := time.Now()
defer func() {
duration := time.Since(start)
fmt.Printf("Package installation took %v\n", duration)
}()
return manager.InstallPackage(pkg)
}
The SDK includes a full-featured CLI tool for direct usage:
# Using Go install
go install github.com/scagogogo/go-pip-sdk/cmd/pip-cli@latest
# Or build from source
git clone https://github.com/scagogogo/go-pip-sdk.git
cd go-pip-sdk
make build
# Install packages
pip-cli install requests
pip-cli install "django>=4.0,<5.0"
# Manage virtual environments
pip-cli venv create ./myenv
pip-cli venv activate ./myenv
pip-cli venv deactivate
# Initialize projects
pip-cli project init ./myproject
# Get help
pip-cli help
# Run with Docker
docker run --rm scagogogo/pip-cli:latest help
# Use Docker Compose for development
cd cmd/pip-cli
docker-compose up pip-cli-dev
- 📖 Online Documentation - Complete API documentation and guides
- 🚀 Getting Started - Quick start guide and installation
- 📚 API Reference - Detailed API documentation with examples
- 💡 Examples - Comprehensive code examples and use cases
- 🔧 Configuration - Configuration options and best practices
- 🐛 Troubleshooting - Common issues and solutions
See the examples directory for more comprehensive examples:
// Main pip manager interface
type Manager interface {
// Package operations
InstallPackage(pkg *PackageSpec) error
UninstallPackage(name string) error
ListPackages() ([]*Package, error)
ShowPackage(name string) (*PackageInfo, error)
SearchPackages(query string) ([]*SearchResult, error)
// Virtual environment operations
CreateVenv(path string) error
ActivateVenv(path string) error
DeactivateVenv() error
// Project operations
InitProject(path string, opts *ProjectOptions) error
BuildProject(path string, opts *BuildOptions) error
// System operations
IsInstalled() (bool, error)
GetVersion() (string, error)
}
// Package specification for installation
type PackageSpec struct {
Name string // Package name
Version string // Version constraint
Extras []string // Extra dependencies
Upgrade bool // Upgrade if already installed
ForceReinstall bool // Force reinstallation
UserInstall bool // Install to user directory
Editable bool // Editable installation
}
// Project initialization options
type ProjectOptions struct {
Name string // Project name
Version string // Initial version
Description string // Project description
Author string // Author name
AuthorEmail string // Author email
License string // License type
Dependencies []string // Runtime dependencies
DevDependencies []string // Development dependencies
CreateVenv bool // Create virtual environment
CreateSrc bool // Create src/ directory
CreateTests bool // Create tests/ directory
}
// Configuration options
type Config struct {
PythonPath string // Python executable path
Timeout time.Duration // Operation timeout
Retries int // Number of retries
DefaultIndex string // Default package index
TrustedHosts []string // Trusted hosts
LogLevel string // Logging level
Environment map[string]string // Environment variables
}
// Error types for different failure scenarios
const (
ErrorTypePipNotInstalled ErrorType = "pip_not_installed"
ErrorTypePythonNotFound ErrorType = "python_not_found"
ErrorTypePackageNotFound ErrorType = "package_not_found"
ErrorTypePermissionDenied ErrorType = "permission_denied"
ErrorTypeNetworkError ErrorType = "network_error"
ErrorTypeVersionConflict ErrorType = "version_conflict"
ErrorTypeCommandFailed ErrorType = "command_failed"
)
// Check error types
if pip.IsErrorType(err, pip.ErrorTypeNetworkError) {
// Handle network errors specifically
}
Run the comprehensive test suite:
# Run all tests
go test ./...
# Run tests with coverage report
go test -cover ./...
# Generate detailed coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
# Run only unit tests (skip integration tests)
go test -short ./...
# Run integration tests (requires Python and pip)
go test -run Integration ./...
# Run benchmarks
go test -bench=. ./...
# Run tests with race detection
go test -race ./...
- Unit Tests: Fast tests that don't require external dependencies
- Integration Tests: Tests that require Python and pip installation
- Benchmark Tests: Performance tests for critical operations
- Example Tests: Ensure documentation examples work correctly
We welcome contributions! Please see our Contributing Guide for details.
-
Fork the repository
git clone https://github.com/your-username/go-pip-sdk.git cd go-pip-sdk
-
Set up development environment
# Install dependencies go mod download # Install development tools make install-tools # Run tests to ensure everything works make test
-
Create your feature branch
git checkout -b feature/amazing-feature
-
Make your changes and test
# Run tests make test # Run linting make lint # Format code make fmt
-
Commit and push
git commit -m 'feat: add amazing feature' git push origin feature/amazing-feature
-
Open a Pull Request
- Follow Go Code Review Comments
- Write tests for new functionality
- Update documentation for API changes
- Use conventional commit messages
- Ensure all CI checks pass
- Go: 1.19 or later
- Python: 3.7 or later (for pip operations)
- Operating System: Windows 10+, macOS 10.15+, or Linux
- Go: 1.19 or later
- Make: For build automation
- Git: For version control
- Python: 3.7+ with pip (for integration tests)
This project is licensed under the MIT License - see the LICENSE file for details.
This project uses several third-party libraries. See THIRD_PARTY_LICENSES.md for details.
- Python pip team - For creating the excellent pip package manager that inspired this project
- Go team - For providing an amazing programming language and standard library
- Contributors - Thanks to all the developers who have contributed to this project
- Community - Special thanks to users who provide feedback and report issues
- 📖 Documentation - Comprehensive guides and API reference
- 🐛 Issue Tracker - Report bugs or request features
- 💬 Discussions - Ask questions and share ideas
- 📧 Email - Direct support for enterprise users
For enterprise users, we offer:
- Priority support and bug fixes
- Custom feature development
- Training and consulting services
- SLA-backed support agreements
Contact us at [email protected] for more information.
Made with ❤️ by the Go Pip SDK team