pyproject-toml

Common errors

• ModuleNotFoundError: No module named 'pyproject-toml'

  cause Attempting to import the library using its PyPI package name (with a hyphen) instead of its module name (with an underscore).
  fix Change your import statement from `import pyproject-toml` to `import pyproject_toml` or `from pyproject_toml import PyProjectTOML`.

• FileNotFoundError: [Errno 2] No such file or directory: 'pyproject.toml'

  cause The `pyproject.toml` file could not be found by the library in the current working directory or at the specified path.
  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')`.

• toml.TomlParsingError: Invalid TOML structure for 'pyproject.toml'

  cause The `pyproject.toml` file contains syntax errors or is malformed according to the TOML specification, preventing the `toml` backend from parsing it.
  fix Review your `pyproject.toml` file for syntax errors. Use a TOML linter or an online TOML validator to identify and correct any issues.

• ModuleNotFoundError: No module named 'pyproject_toml'

  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`).
  fix Install the library using pip and ensure the import statement is correct: ```python pip install pyproject-toml import pyproject_toml ```

• pyproject_toml.TomlParsingError: Invalid TOML file: ...

  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.
  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): ```toml # pyproject.toml [project] name = "my-package" # Ensure string values are quoted version = "0.1.0" ```

Warnings

• gotcha 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`.
  Fix: Always use `from pyproject_toml import PyProjectTOML` (with an underscore) in your Python code.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• pip install pyproject-toml Install stable version

Imports

• PyProjectTOML
  wrong:

  from pyproject-toml import PyProjectTOML

  correct:

  from pyproject_toml import PyProjectTOML

  The PyPI package is named `pyproject-toml` (with a hyphen), but the Python module for import uses an underscore: `pyproject_toml`.

Quickstart

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.

import os
from pyproject_toml import PyProjectTOML

# Create a dummy pyproject.toml for the example
dummy_toml_content = """
[project]
name = "my-dummy-project"
version = "0.1.0"
description = "A short description."
requires-python = ">=3.9"
authors = [
  {name = "Jane Doe", email = "jane@example.com"},
]
"""
with open("pyproject.toml", "w") as f:
    f.write(dummy_toml_content)

try:
    # Initialize and load the pyproject.toml file
    pyproject = PyProjectTOML()
    data = pyproject.load()

    # Access project metadata
    project_name = data["project"]["name"]
    project_version = data["project"]["version"]

    print(f"Project Name: {project_name}")
    print(f"Project Version: {project_version}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists("pyproject.toml"):
        os.remove("pyproject.toml")