github-mirror/python-by-example
1
0
Fork 0
mirror of https://github.com/blshaer/python-by-example.git synced 2026-03-27 23:29:25 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity
10fc3566bb
python-by-example/10_best_practices/03_virtual_envs.py
balshaer1 10fc3566bb Initial commit: Python by Example structure
2025-12-30 08:50:00 +02:00

456 lines
14 KiB
Python
Raw Blame History

"""
================================================================================
File: 03_virtual_envs.py
Topic: Virtual Environments in Python
================================================================================
This file explains virtual environments in Python. Virtual environments are
isolated Python environments that allow you to manage dependencies separately
for each project, avoiding conflicts between different projects.
Key Concepts:
- What are virtual environments
- Creating and activating venvs
- Managing dependencies with pip
- requirements.txt
- Best practices
Note: This is a reference/tutorial file - the commands are shown as examples.
================================================================================
"""
# =============================================================================
# 1. WHAT ARE VIRTUAL ENVIRONMENTS?
# =============================================================================
print("=== What Are Virtual Environments? ===")
print("""
A virtual environment is an ISOLATED Python environment that:
✓ Has its own Python interpreter
✓ Has its own site-packages directory
✓ Doesn't affect global Python installation
✓ Allows different projects to have different dependencies
Why use virtual environments?
- Project A needs Django 3.2
- Project B needs Django 4.1
- Without venvs, you'd have conflicts!
With virtual environments, each project has its own Django version.
""")
# =============================================================================
# 2. CREATING A VIRTUAL ENVIRONMENT
# =============================================================================
print("\n=== Creating a Virtual Environment ===")
print("""
Using the built-in 'venv' module (Python 3.3+):
# Navigate to your project directory
cd my_project
# Create a virtual environment named 'venv'
python -m venv venv
# Or name it something else
python -m venv .venv # Hidden folder (common convention)
python -m venv env # Another common name
python -m venv my_env # Custom name
This creates a folder with:
venv/
├── Include/ # C header files
├── Lib/ # Python packages
│ └── site-packages/
├── Scripts/ # Activation scripts (Windows)
│ ├── activate
│ ├── activate.bat
│ └── python.exe
└── pyvenv.cfg # Configuration file
""")
# =============================================================================
# 3. ACTIVATING AND DEACTIVATING
# =============================================================================
print("\n=== Activating and Deactivating ===")
print("""
ACTIVATION (must do before using the venv):
Windows (Command Prompt):
venv\\Scripts\\activate.bat
Windows (PowerShell):
venv\\Scripts\\Activate.ps1
If you get execution policy error:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
macOS/Linux:
source venv/bin/activate
When activated, your prompt changes:
(venv) C:\\my_project>
(venv) user@computer:~/my_project$
DEACTIVATION:
deactivate
After deactivation, prompt returns to normal.
""")
# =============================================================================
# 4. INSTALLING PACKAGES
# =============================================================================
print("\n=== Installing Packages ===")
print("""
After activating your venv, use pip to install packages:
# Install a package
pip install requests
# Install specific version
pip install requests==2.28.0
# Install minimum version
pip install 'requests>=2.25.0'
# Install multiple packages
pip install requests numpy pandas
# Install from requirements.txt
pip install -r requirements.txt
# Upgrade a package
pip install --upgrade requests
# Uninstall a package
pip uninstall requests
# List installed packages
pip list
# Show package info
pip show requests
""")
# =============================================================================
# 5. REQUIREMENTS FILE
# =============================================================================
print("\n=== Requirements File ===")
print("""
The requirements.txt file lists all project dependencies:
CREATING requirements.txt:
# Generate from current environment
pip freeze > requirements.txt
EXAMPLE requirements.txt:
# requirements.txt
requests==2.28.1
numpy>=1.21.0
pandas~=1.5.0
python-dotenv
VERSION SPECIFIERS:
package==1.0.0 # Exact version
package>=1.0.0 # Minimum version
package<=1.0.0 # Maximum version
package~=1.0.0 # Compatible version (>=1.0.0, <2.0.0)
package!=1.0.0 # Exclude version
package>=1.0,<2.0 # Version range
INSTALLING FROM requirements.txt:
pip install -r requirements.txt
BEST PRACTICE: Create different files for different environments:
requirements.txt # Production dependencies
requirements-dev.txt # Development dependencies
requirements-test.txt # Testing dependencies
""")
# =============================================================================
# 6. VIRTUAL ENVIRONMENT ALTERNATIVES
# =============================================================================
print("\n=== Alternative Tools ===")
print("""
1. venv (built-in)
- Simple, included with Python
- Good for basic needs
python -m venv venv
2. virtualenv
- More features than venv
- Faster environment creation
pip install virtualenv
virtualenv venv
3. pipenv
- Combines venv + pip
- Uses Pipfile instead of requirements.txt
- Automatic locking of dependencies
pip install pipenv
pipenv install requests
pipenv shell
4. poetry
- Modern dependency management
- Better dependency resolution
- Build and publish packages
pip install poetry
poetry new my_project
poetry add requests
5. conda
- Package manager + environment manager
- Great for data science (NumPy, SciPy pre-compiled)
conda create -n myenv python=3.10
conda activate myenv
conda install numpy
""")
# =============================================================================
# 7. PROJECT STRUCTURE WITH VENV
# =============================================================================
print("\n=== Project Structure ===")
print("""
Recommended project structure:
my_project/
├── venv/ # Virtual environment (don't commit!)
├── src/
│ └── my_package/
│ ├── __init__.py
│ └── main.py
├── tests/
│ ├── __init__.py
│ └── test_main.py
├── .gitignore # Include 'venv/' here!
├── requirements.txt
├── requirements-dev.txt
├── setup.py or pyproject.toml
└── README.md
.gitignore should include:
venv/
.venv/
env/
__pycache__/
*.pyc
.pytest_cache/
""")
# =============================================================================
# 8. COMMON COMMANDS REFERENCE
# =============================================================================
print("\n=== Quick Reference ===")
print("""
╔══════════════════════════════════════════════════════════════════╗
║ VIRTUAL ENVIRONMENT COMMANDS ║
╠══════════════════════════════════════════════════════════════════╣
║ CREATE ║
║ python -m venv venv ║
║ ║
║ ACTIVATE ║
║ Windows: venv\\Scripts\\activate ║
║ Mac/Linux: source venv/bin/activate ║
║ ║
║ DEACTIVATE ║
║ deactivate ║
║ ║
║ INSTALL PACKAGES ║
║ pip install package_name ║
║ pip install -r requirements.txt ║
║ ║
║ EXPORT DEPENDENCIES ║
║ pip freeze > requirements.txt ║
║ ║
║ CHECK PYTHON LOCATION ║
║ Windows: where python ║
║ Mac/Linux: which python ║
║ ║
║ DELETE VENV (just remove the folder) ║
║ Windows: rmdir /s /q venv ║
║ Mac/Linux: rm -rf venv ║
╚══════════════════════════════════════════════════════════════════╝
""")
# =============================================================================
# 9. BEST PRACTICES
# =============================================================================
print("\n=== Best Practices ===")
print("""
1. ALWAYS use virtual environments
- Even for small projects
- Prevents "works on my machine" problems
2. Don't commit venv to version control
- Add 'venv/' to .gitignore
- Share requirements.txt instead
3. Use meaningful venv names
- venv, .venv, or env are common
- Use .venv to hide the folder
4. Pin your versions in production
- Use pip freeze > requirements.txt
- Review and clean up before committing
5. Separate dev and production dependencies
- requirements.txt for production
- requirements-dev.txt for testing, linting, etc.
6. Document how to set up the environment
- Include setup instructions in README.md
7. Use pip-tools for better dependency management
- pip install pip-tools
- Create requirements.in with direct dependencies
- pip-compile requirements.in creates pinned file
""")
# =============================================================================
# 10. TROUBLESHOOTING
# =============================================================================
print("\n=== Troubleshooting ===")
print("""
COMMON ISSUES AND SOLUTIONS:
1. "python not recognized" after activation
Solution: Use full path or reinstall Python with PATH option
2. PowerShell "execution policy" error
Solution:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
3. "pip install" uses global pip
Solution: Make sure venv is activated first
Check: python -c "import sys; print(sys.prefix)"
4. Can't delete venv folder (files in use)
Solution:
- Deactivate first
- Close any terminals/IDEs using it
- Restart computer if needed
5. requirements.txt has too many packages
Solution: Use pipreqs to generate minimal requirements
pip install pipreqs
pipreqs /path/to/project
6. Package conflicts
Solution: Create fresh venv and install carefully
Or use pip-compile for dependency resolution
""")
# =============================================================================
# 11. IDE INTEGRATION
# =============================================================================
print("\n=== IDE Integration ===")
print("""
VS CODE:
1. Open project folder
2. Select Python Interpreter (Ctrl+Shift+P)
3. Choose "Python: Select Interpreter"
4. Select the venv Python (./venv/Scripts/python.exe)
5. New terminals auto-activate venv
PYCHARM:
1. File > Settings > Project > Python Interpreter
2. Click gear icon > Add
3. Select "Existing environment" or create new
4. Point to venv/Scripts/python.exe
JUPYTER NOTEBOOK:
1. Activate venv
2. Install: pip install ipykernel
3. Register: python -m ipykernel install --user --name=myenv
4. Select kernel in Jupyter
""")
# =============================================================================
# 12. EXAMPLE WORKFLOW
# =============================================================================
print("\n=== Example Workflow ===")
print("""
STARTING A NEW PROJECT:
# 1. Create project folder
mkdir my_awesome_project
cd my_awesome_project
# 2. Create virtual environment
python -m venv venv
# 3. Activate it
venv\\Scripts\\activate # Windows
source venv/bin/activate # Mac/Linux
# 4. Upgrade pip (good practice)
python -m pip install --upgrade pip
# 5. Install packages
pip install requests numpy pandas
# 6. Create requirements.txt
pip freeze > requirements.txt
# 7. Create .gitignore
echo "venv/" > .gitignore
echo "__pycache__/" >> .gitignore
# 8. Start coding!
code .
JOINING AN EXISTING PROJECT:
# 1. Clone the repository
git clone https://github.com/user/project.git
cd project
# 2. Create virtual environment
python -m venv venv
# 3. Activate it
venv\\Scripts\\activate # Windows
# 4. Install dependencies
pip install -r requirements.txt
# 5. Start working!
""")
print("\n" + "=" * 60)
print("Virtual environments are essential for Python development!")
print("Always use them to keep your projects isolated and reproducible.")
print("=" * 60)
Reference in New Issue View Git Blame Copy Permalink