{"id":10126,"library":"pyproject-toml","title":"pyproject-toml","description":"pyproject-toml is a Python library designed to parse and manage `pyproject.toml` files according to various PEPs, including PEP 517, 518, 621, and 631. It provides a structured way to access project metadata and build system configuration. The current version is 0.1.0, and it follows an infrequent release cadence based on new PEP implementations or bug fixes.","status":"active","version":"0.1.0","language":"en","source_language":"en","source_url":"https://github.com/frostming/pyproject-toml","tags":["toml","pyproject","packaging","build system","pep"],"install":[{"cmd":"pip install pyproject-toml","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for parsing TOML formatted files.","package":"toml"},{"reason":"Used for handling version specifiers and other packaging-related metadata conforming to PEPs.","package":"packaging"}],"imports":[{"note":"The PyPI package is named `pyproject-toml` (with a hyphen), but the Python module for import uses an underscore: `pyproject_toml`.","wrong":"from pyproject-toml import PyProjectTOML","symbol":"PyProjectTOML","correct":"from pyproject_toml import PyProjectTOML"}],"quickstart":{"code":"import os\nfrom pyproject_toml import PyProjectTOML\n\n# Create a dummy pyproject.toml for the example\ndummy_toml_content = \"\"\"\n[project]\nname = \"my-dummy-project\"\nversion = \"0.1.0\"\ndescription = \"A short description.\"\nrequires-python = \">=3.9\"\nauthors = [\n  {name = \"Jane Doe\", email = \"jane@example.com\"},\n]\n\"\"\"\nwith open(\"pyproject.toml\", \"w\") as f:\n    f.write(dummy_toml_content)\n\ntry:\n    # Initialize and load the pyproject.toml file\n    pyproject = PyProjectTOML()\n    data = pyproject.load()\n\n    # Access project metadata\n    project_name = data[\"project\"][\"name\"]\n    project_version = data[\"project\"][\"version\"]\n\n    print(f\"Project Name: {project_name}\")\n    print(f\"Project Version: {project_version}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(\"pyproject.toml\"):\n        os.remove(\"pyproject.toml\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically create a dummy `pyproject.toml` file, load it using `PyProjectTOML`, and access common project metadata like name and version. The example cleans up the created file afterwards."},"warnings":[{"fix":"Always use `from pyproject_toml import PyProjectTOML` (with an underscore) in your Python code.","message":"The PyPI package name `pyproject-toml` (with a hyphen) differs from its Python import name `pyproject_toml` (with an underscore). Using the hyphenated name in import statements will result in a `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"all"},{"fix":"Explicitly specify the path to your `pyproject.toml` file using `PyProjectTOML(filename='/path/to/pyproject.toml').load()` or ensure your script's working directory is correct.","message":"When `PyProjectTOML().load()` is called without arguments, it implicitly searches for `pyproject.toml` in the current working directory. If your script is executed from a different directory, it might not find the file as expected.","severity":"gotcha","affected_versions":"all"},{"fix":"It is recommended to pin the exact library version (e.g., `pyproject-toml==0.1.0`) in your `requirements.txt` or `pyproject.toml` and carefully review changelogs when upgrading to new versions.","message":"As the library is currently in an early development stage (version 0.1.0) and implements evolving PEPs, future minor versions might introduce breaking changes to its API surface or the structure of the data returned, especially as new PEP features are added or interpretations solidify.","severity":"breaking","affected_versions":"0.x.x"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change your import statement from `import pyproject-toml` to `import pyproject_toml` or `from pyproject_toml import PyProjectTOML`.","cause":"Attempting to import the library using its PyPI package name (with a hyphen) instead of its module name (with an underscore).","error":"ModuleNotFoundError: No module named 'pyproject-toml'"},{"fix":"Ensure that `pyproject.toml` exists in the directory from which your Python script is executed, or provide the full, correct path to the file when initializing `PyProjectTOML(filename='/path/to/pyproject.toml')`.","cause":"The `pyproject.toml` file could not be found by the library in the current working directory or at the specified path.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'pyproject.toml'"},{"fix":"Review your `pyproject.toml` file for syntax errors. Use a TOML linter or an online TOML validator to identify and correct any issues.","cause":"The `pyproject.toml` file contains syntax errors or is malformed according to the TOML specification, preventing the `toml` backend from parsing it.","error":"toml.TomlParsingError: Invalid TOML structure for 'pyproject.toml'"},{"fix":"Install the library using pip and ensure the import statement is correct:\n```python\npip install pyproject-toml\nimport pyproject_toml\n```","cause":"The `pyproject-toml` library has not been installed in the current Python environment or the import statement uses an incorrect name (e.g., `pyproject-toml` instead of `pyproject_toml`).","error":"ModuleNotFoundError: No module named 'pyproject_toml'"},{"fix":"Correct the syntax errors in the `pyproject.toml` file. Use a TOML linter or editor with TOML support to identify and fix issues (e.g., ensure all string values are quoted):\n```toml\n# pyproject.toml\n[project]\nname = \"my-package\" # Ensure string values are quoted\nversion = \"0.1.0\"\n```","cause":"The `pyproject.toml` file contains syntax errors, is malformed, or does not conform to the TOML specification, preventing the `pyproject-toml` library from successfully parsing it.","error":"pyproject_toml.TomlParsingError: Invalid TOML file: ..."}]}