mauvehed.com
mauvehed's dotfiles for personal and work environments
1# Python Usage
2
3This document provides a guide to setting up and using Python for development, focusing on version management with `pyenv`, and modern project/dependency management with tools like Poetry and `venv`.
4
5## Overview
6
7[Python](https://www.python.org/) is a versatile, high-level programming language. Effective Python development involves managing Python versions and project dependencies robustly.
8
9## Python Version Management with `pyenv`
10
11It is highly recommended to use [pyenv](https://github.com/pyenv/pyenv) to manage multiple Python versions.
12
13### Installation of `pyenv`
14
15* **Homebrew (macOS)**:
16 ```sh
17 brew install pyenv
18 ```
19* **Other Systems/Manual Install**: Follow the [official `pyenv` installation guide](https://github.com/pyenv/pyenv#installation).
20
21### `pyenv` Initialization
22
23Add `pyenv` init to your shell configuration file (e.g., `.zshrc`), managed by `chezmoi`:
24```sh
25# Example for .zshrc
26# if command -v pyenv 1>/dev/null 2>&1; then
27# eval "$(pyenv init -)"
28# eval "$(pyenv virtualenv-init -)" # If using pyenv-virtualenv (optional)
29# fi
30```
31
32### Installing Python Versions with `pyenv`
33
341. **List available Python versions**: `pyenv install --list`
352. **Install a Python version**: `pyenv install <version>` (e.g., `pyenv install 3.10.4`)
363. **Set Python version**:
37 * **Globally**: `pyenv global <version>`
38 * **Locally (per-project)**: `pyenv local <version>` (creates `.python-version`)
39 * **Shell specific**: `pyenv shell <version>`
40
41## Project & Dependency Management
42
43Isolating project dependencies is crucial.
44
45### Option 1: Poetry (Recommended for New Projects)
46
47[Poetry](https://python-poetry.org/) is a modern tool for Python dependency management and packaging. It helps you declare, manage, and install dependencies of Python projects, ensuring you have the right stack everywhere.
48
49**Key Benefits of Poetry:**
50* **Dependency Resolution**: Advanced resolver for compatible dependencies.
51* **Unified Tool**: Manages project metadata, dependencies, virtual environments, building, and publishing.
52* **`pyproject.toml`**: Uses the standard `pyproject.toml` file to manage project information.
53* **Lock File**: Creates a `poetry.lock` file for deterministic builds.
54* **Virtual Environment Management**: Automatically creates and manages virtual environments for your projects.
55
56**Installation of Poetry:**
57
58Refer to the [official Poetry installation guide](https://python-poetry.org/docs/#installation). A common method is using their custom installer or `pipx`:
59```sh
60# Using pipx (recommended for CLI tools)
61brew install pipx # If not already installed
62pipx ensurepath
63pipx install poetry
64
65# Or using the official installer
66# curl -sSL https://install.python-poetry.org | python3 -
67```
68
69**Common Poetry Commands:**
70
71* **`poetry new <project_name>`**: Creates a new Python project with a standard structure.
72* **`poetry init`**: Interactively creates a `pyproject.toml` in an existing project.
73* **`poetry install`**: Installs dependencies defined in `pyproject.toml` (and `poetry.lock`). If a virtual environment doesn't exist, Poetry creates one.
74* **`poetry add <package_name>`**: Adds a new dependency to `pyproject.toml` and installs it.
75 * `poetry add requests`
76 * `poetry add pytest --group dev` (for development dependencies)
77* **`poetry remove <package_name>`**: Removes a dependency.
78* **`poetry show`**: Lists all installed packages.
79* **`poetry update`**: Updates dependencies to their latest allowed versions according to `pyproject.toml` and updates `poetry.lock`.
80* **`poetry run <command>`**: Runs a command within the project's virtual environment.
81 * `poetry run python my_script.py`
82 * `poetry run pytest`
83* **`poetry shell`**: Activates the project's virtual environment in your current shell.
84* **`poetry build`**: Builds your project into a source archive (sdist) and a wheel (bdist_wheel).
85* **`poetry publish`**: Publishes your package to a repository like PyPI.
86
87Poetry can be configured to use Python versions installed by `pyenv`:
88```sh
89poetry env use $(pyenv which python) # Or specify a path/version
90```
91
92### Option 2: `venv` and `pip` (Traditional)
93
94Python 3.3+ includes the `venv` module for creating virtual environments.
95
961. **Create a virtual environment**: `python -m venv .venv`
972. **Activate**:
98 * Unix/macOS: `source .venv/bin/activate`
99 * Windows: `.\.venv\Scripts\activate.bat` or `.\.venv\Scripts\Activate.ps1`
1003. **Deactivate**: `deactivate`
101
102**Package Management with `pip` (within an active `venv`)**:
103
104* Install: `pip install <package_name>`, `pip install -r requirements.txt`
105* List: `pip list`
106* Generate `requirements.txt`: `pip freeze > requirements.txt`
107
108### `pyenv-virtualenv` (Plugin for `pyenv`)
109
110The [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) plugin integrates `venv` management with `pyenv` if you prefer this workflow over Poetry's built-in virtual environment handling.
111
112## Common Python Development Tools
113
114Install these within your project's virtual environment (via `poetry add --group dev tool_name` or `pip install tool_name`) or globally via `pipx`.
115
116* **Linters**: `flake8`, `pylint`
117* **Formatters**: `black`, `autopep8`, `isort`
118* **Test Runners**: `pytest`, `unittest` (built-in)
119* **`pipx`**: For installing and running Python CLI applications in isolated environments (`brew install pipx`).
120 * Example: `pipx install black`
121
122## Resources
123
124* **Official Python Documentation**: [https://docs.python.org/3/](https://docs.python.org/3/)
125* **`pyenv` GitHub Repository**: [https://github.com/pyenv/pyenv](https://github.com/pyenv/pyenv)
126* **Poetry Documentation**: [https://python-poetry.org/docs/](https://python-poetry.org/docs/)
127* **Python `venv` Documentation**: [https://docs.python.org/3/library/venv.html](https://docs.python.org/3/library/venv.html)
128* **`pip` Documentation**: [https://pip.pypa.io/](https://pip.pypa.io/)
129* **Python Packaging User Guide**: [https://packaging.python.org/](https://packaging.python.org/)
130* **`pipx`**: [https://pipx.pypa.io/](https://pipx.pypa.io/)
131
132This document covers essentials for a modern Python development setup. Choose the tools that best fit your project needs.