PEP 518

Overview Poetry represents a shift in how developers handle the Python ecosystem. It moves beyond the fragmented landscape of `requirements.txt` and `setup.py`, consolidating dependency management, virtual environment isolation, and package publishing into a single workflow. By utilizing the `pyproject.toml` standard defined in PEP 518, it ensures that your project remains reproducible and clean across different machines. Prerequisites To follow this guide, you should have a basic understanding of the terminal or command line. Familiarity with Python syntax and the concept of third-party libraries is necessary. You should have Python installed on your system, ideally version 3.8 or higher. Key Libraries & Tools - **Poetry**: The primary tool for dependency management and packaging. - **PyPI**: The Python Package Index, where Poetry fetches and publishes packages. - **Virtual Environments**: Isolated spaces where your project dependencies live. Code Walkthrough Managing dependencies involves a few core terminal commands. To add a new library like Pytest, use the `add` command: ```bash poetry add pytest ``` This command updates your `pyproject.toml` and creates a `poetry.lock` file. The lock file is crucial; it records the exact versions of every sub-dependency installed, preventing the "it works on my machine" syndrome. To see what is currently installed, run: ```bash poetry show ``` To enter the isolated environment created by Poetry, use the shell command: ```bash poetry shell ``` Syntax Notes Poetry uses specific symbols for versioning in `pyproject.toml`. The **caret (^)** symbol is the default. For example, `^2.3.0` allows updates that do not change the left-most non-zero digit (e.g., up to but not including 3.0.0). The **tilde (~)** symbol is more restrictive, typically allowing only patch-level changes if a minor version is specified. Practical Examples If you are building a web scraper, you might add Requests with a specific constraint: ```bash Adds requests but restricts it to version 2.2x poetry add requests@~2.2.0 ``` Tips & Gotchas Avoid manual edits to `poetry.lock`. Always let Poetry update this file via commands. If you encounter errors about a missing root folder during `poetry install`, use the `--no-root` flag if your current project isn't intended to be an installable package itself.