`pyproject.toml` în Python

Pachete și medii virtuale PEP 621 (tomllib: Python 3.11+)

Fișierul standard de configurare al unui proiect Python: nume, versiune, dependențe și setările uneltelor.

Sintaxă

[project]
name = "magazin"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["requests>=2.34"]

[dependency-groups]
dev = ["pytest>=9.0"]

Ce face `pyproject.toml`

pyproject.toml stă în folderul principal al proiectului și descrie proiectul într-un format standard (PEP 621), citit de pip, uv, Poetry, Hatch și alte unelte. Formatul este TOML: secțiuni între paranteze drepte, perechi cheie = valoare, texte între ghilimele și liste între [ ].

Secțiunea [project] conține name, version, requires-python (versiunea minimă de Python) și dependencies, lista pachetelor de care are nevoie proiectul, cu limite de versiune. [dependency-groups] (PEP 735) ține pachetele folosite doar la dezvoltare, ca pytest. [build-system] spune ce unealtă construiește pachetul, iar secțiunile [tool.nume] sunt setările uneltelor (de exemplu [tool.ruff]).

Din Python 3.11, modulul standard tomllib citește fișiere TOML, așa că poți citi pyproject.toml și din cod.

Parametri

Parametru	Descriere
`name`	Numele proiectului (cel de pe PyPI, dacă îl publici).
`version`	Versiunea proiectului, de exemplu `"0.1.0"`.
`requires-python`	Versiunile de Python acceptate, de exemplu `">=3.11"`.
`dependencies`	Lista dependențelor, în același format ca în requirements.txt.
`[project.optional-dependencies]`	Extra-uri opționale, instalate cu `pip install "proiect[extra]"`.
`[project.scripts]`	Comenzi de terminal create la instalare: `magazin = "magazin:main"`.

Ce returnează

Fișierul nu returnează nimic; uneltele îl citesc când instalează sau rulează proiectul.

Exemple

Exemplul 1: Citirea unui pyproject.toml cu tomllib

tomllib.loads() transformă textul TOML într-un dicționar Python. Pentru un fișier, folosește tomllib.load() cu fișierul deschis în mod binar ("rb").

import tomllib
from pathlib import Path

Path("pyproject.toml").write_text("""
[project]
name = "magazin-ana"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.34",
    "pandas>=3.0",
]

[dependency-groups]
dev = ["pytest>=9.0"]

[tool.ruff]
line-length = 100
""", encoding="utf-8")

with open("pyproject.toml", "rb") as f:
    config = tomllib.load(f)

proiect = config["project"]
print(proiect["name"], proiect["version"])
print("Python:", proiect["requires-python"])
for dependenta in proiect["dependencies"]:
    print(" -", dependenta)
print("Dezvoltare:", config["dependency-groups"]["dev"])
print("Ruff:", config["tool"]["ruff"])

Rezultat

magazin-ana 0.1.0
Python: >=3.11
 - requests>=2.34
 - pandas>=3.0
Dezvoltare: ['pytest>=9.0']
Ruff: {'line-length': 100}

Exemplul 2: Eroare de sintaxă TOML

Textele trebuie puse între ghilimele. Fără ele, tomllib (și orice unealtă) refuză fișierul și spune rândul greșit.

import tomllib

text = """
[project]
name = magazin
"""
try:
    tomllib.loads(text)
except tomllib.TOMLDecodeError as eroare:
    print("Fișier invalid:", eroare)