pyproject

Pyproject module.

Pep621

Bases: PyprojectCommon

Handler for PEP 621 [project] metadata in pyproject.toml.

This covers every backend that stores its metadata in the standard [project] table, i.e. uv, hatchling, flit, PDM, setuptools and Poetry 2.x. Only Poetry 1.x needs its own handler, see somesy.pyproject.writer.Poetry.

Source code in src/somesy/pyproject/writer.py

class Pep621(PyprojectCommon):
    """Handler for PEP 621 `[project]` metadata in pyproject.toml.

    This covers every backend that stores its metadata in the standard
    `[project]` table, i.e. uv, hatchling, flit, PDM, setuptools and
    Poetry 2.x. Only Poetry 1.x needs its own handler, see [somesy.pyproject.writer.Poetry][].
    """

    def __init__(self, path: Path, pass_validation: bool | None = False):
        """PEP 621 `[project]` config file handler parsed from pyproject.toml.

        See [somesy.core.writer.ProjectMetadataWriter.__init__][].
        """
        section = ["project"]
        mappings = {
            "homepage": ["urls", "homepage"],
            "repository": ["urls", "repository"],
            "documentation": ["urls", "documentation"],
        }
        super().__init__(
            path,
            section=section,
            direct_mappings=mappings,
            model_cls=Pep621Config,
            pass_validation=pass_validation,
        )

    @staticmethod
    def _from_person(person: Person | Entity):
        """Convert project metadata person object to a PEP 621 person table."""
        response = {"name": person.full_name}
        if person.email:
            response["email"] = person.email
        return response

    @staticmethod
    def _to_person(person_obj: str | dict) -> Entity | Person | None:
        """Parse a PEP 621 person entry to a Person/Entity."""
        # NOTE: for our purposes, does not matter what are given or family names,
        # we only compare on full_name anyway.
        if isinstance(person_obj, dict):
            temp = str(person_obj["name"])
            if "email" in person_obj:
                temp = f"{temp} <{person_obj['email']}>"
            person_obj = temp

        try:
            return Person.from_name_email_string(person_obj)
        except (ValueError, AttributeError):
            logger.info(f"Cannot convert {person_obj} to Person object, trying Entity.")

        try:
            return Entity.from_name_email_string(person_obj)
        except (ValueError, AttributeError):
            logger.warning(f"Cannot convert {person_obj} to Entity.")
            return None

    def sync(self, metadata: ProjectMetadata) -> None:
        """Sync metadata with pyproject.toml file and fix license field."""
        super().sync(metadata)
        if metadata.license:
            self.license = license_expression(metadata.license)

__init__

__init__(path: Path, pass_validation: bool | None = False)

PEP 621 [project] config file handler parsed from pyproject.toml.

See somesy.core.writer.ProjectMetadataWriter.init.

Source code in src/somesy/pyproject/writer.py

def __init__(self, path: Path, pass_validation: bool | None = False):
    """PEP 621 `[project]` config file handler parsed from pyproject.toml.

    See [somesy.core.writer.ProjectMetadataWriter.__init__][].
    """
    section = ["project"]
    mappings = {
        "homepage": ["urls", "homepage"],
        "repository": ["urls", "repository"],
        "documentation": ["urls", "documentation"],
    }
    super().__init__(
        path,
        section=section,
        direct_mappings=mappings,
        model_cls=Pep621Config,
        pass_validation=pass_validation,
    )

sync

sync(metadata: ProjectMetadata) -> None

Sync metadata with pyproject.toml file and fix license field.

Source code in src/somesy/pyproject/writer.py

def sync(self, metadata: ProjectMetadata) -> None:
    """Sync metadata with pyproject.toml file and fix license field."""
    super().sync(metadata)
    if metadata.license:
        self.license = license_expression(metadata.license)

Poetry

Bases: PyprojectCommon

Poetry config file handler parsed from pyproject.toml.

Source code in src/somesy/pyproject/writer.py

class Poetry(PyprojectCommon):
    """Poetry config file handler parsed from pyproject.toml."""

    def __init__(
        self,
        path: Path,
        pass_validation: bool | None = False,
        version: int | None = 1,
    ):
        """Poetry config file handler parsed from pyproject.toml.

        See [somesy.core.writer.ProjectMetadataWriter.__init__][].
        """
        self._poetry_version = version or 1
        v2_mappings = {
            "homepage": ["urls", "homepage"],
            "repository": ["urls", "repository"],
            "documentation": ["urls", "documentation"],
        }
        if version == 1:
            super().__init__(
                path,
                section=["tool", "poetry"],
                model_cls=PoetryConfig,
                pass_validation=pass_validation,
            )
        else:
            super().__init__(
                path,
                section=["project"],
                model_cls=PoetryConfig,
                pass_validation=pass_validation,
                direct_mappings=v2_mappings,
            )

    @staticmethod
    def _from_person(person: Person | Entity, poetry_version: int = 1):
        """Convert project metadata person object to poetry string for person format "full name <email>."""
        if poetry_version == 1:
            return person.to_name_email_string()
        else:
            response = {"name": person.full_name}
            if person.email:
                response["email"] = person.email
            return response

    @staticmethod
    def _to_person(
        person_obj: str | dict[str, str],
    ) -> Person | Entity | None:
        """Convert from free string to person or entity object."""
        if isinstance(person_obj, dict):
            temp = str(person_obj["name"])
            if "email" in person_obj:
                temp = f"{temp} <{person_obj['email']}>"
            person_obj = temp
        try:
            return Person.from_name_email_string(person_obj)
        except (ValueError, AttributeError):
            logger.info(f"Cannot convert {person_obj} to Person object, trying Entity.")

        try:
            return Entity.from_name_email_string(person_obj)
        except (ValueError, AttributeError):
            logger.warning(f"Cannot convert {person_obj} to Entity.")
            return None

    def sync(self, metadata: ProjectMetadata) -> None:
        """Sync metadata with pyproject.toml file."""
        # Store original _from_person method
        original_from_person = self._from_person

        # Override _from_person to include poetry_version
        self._from_person = lambda person: original_from_person(  # type: ignore
            person, poetry_version=self._poetry_version
        )

        # Call parent sync method
        super().sync(metadata)

        # Restore original _from_person method
        self._from_person = original_from_person  # type: ignore

        if metadata.license:
            self.license = license_expression(metadata.license)

        # For Poetry v2, convert authors and maintainers from array of tables to inline tables
        if self._poetry_version == 2:
            if (
                "description" in self._data["project"]
                and "\n" in self._data["project"]["description"]
            ):
                self._data["project"]["description"] = tomlkit.string(
                    self._data["project"]["description"], multiline=True
                )
            # Move urls section to the end if it exists
            if "urls" in self._data["project"]:
                urls = self._data["project"].pop("urls")
                self._data["project"]["urls"] = urls

__init__

__init__(
    path: Path,
    pass_validation: bool | None = False,
    version: int | None = 1,
)

Poetry config file handler parsed from pyproject.toml.

See somesy.core.writer.ProjectMetadataWriter.init.

Source code in src/somesy/pyproject/writer.py

def __init__(
    self,
    path: Path,
    pass_validation: bool | None = False,
    version: int | None = 1,
):
    """Poetry config file handler parsed from pyproject.toml.

    See [somesy.core.writer.ProjectMetadataWriter.__init__][].
    """
    self._poetry_version = version or 1
    v2_mappings = {
        "homepage": ["urls", "homepage"],
        "repository": ["urls", "repository"],
        "documentation": ["urls", "documentation"],
    }
    if version == 1:
        super().__init__(
            path,
            section=["tool", "poetry"],
            model_cls=PoetryConfig,
            pass_validation=pass_validation,
        )
    else:
        super().__init__(
            path,
            section=["project"],
            model_cls=PoetryConfig,
            pass_validation=pass_validation,
            direct_mappings=v2_mappings,
        )

sync

sync(metadata: ProjectMetadata) -> None

Sync metadata with pyproject.toml file.

Source code in src/somesy/pyproject/writer.py

def sync(self, metadata: ProjectMetadata) -> None:
    """Sync metadata with pyproject.toml file."""
    # Store original _from_person method
    original_from_person = self._from_person

    # Override _from_person to include poetry_version
    self._from_person = lambda person: original_from_person(  # type: ignore
        person, poetry_version=self._poetry_version
    )

    # Call parent sync method
    super().sync(metadata)

    # Restore original _from_person method
    self._from_person = original_from_person  # type: ignore

    if metadata.license:
        self.license = license_expression(metadata.license)

    # For Poetry v2, convert authors and maintainers from array of tables to inline tables
    if self._poetry_version == 2:
        if (
            "description" in self._data["project"]
            and "\n" in self._data["project"]["description"]
        ):
            self._data["project"]["description"] = tomlkit.string(
                self._data["project"]["description"], multiline=True
            )
        # Move urls section to the end if it exists
        if "urls" in self._data["project"]:
            urls = self._data["project"].pop("urls")
            self._data["project"]["urls"] = urls

Pyproject

Bases: ObjectProxy

Class for syncing pyproject file with other metadata files.

Source code in src/somesy/pyproject/writer.py

class Pyproject(wrapt.ObjectProxy):
    """Class for syncing pyproject file with other metadata files."""

    __wrapped__: Pep621 | Poetry

    def __init__(self, path: Path, pass_validation: bool | None = False):
        """Pyproject wrapper class. Wraps either PEP 621 `[project]` or Poetry metadata.

        The handler is picked based on the metadata tables present in the file,
        not on the configured build backend.

        Args:
            path (Path): Path to pyproject.toml file.
            pass_validation (bool, optional): Whether to pass validation. Defaults to False.

        Raises:
            FileNotFoundError: Raised when pyproject.toml file is not found.
            ValueError: Neither project nor tool.poetry object is found in pyproject.toml file.

        """
        data = None
        if not path.is_file():
            raise FileNotFoundError(f"pyproject file {path} not found")

        with open(path, "r") as f:
            data = load(f)

        # inspect file to pick suitable project metadata writer
        is_poetry = "tool" in data and "poetry" in data["tool"]
        has_project = "project" in data

        if is_poetry and has_project and not _builds_with_poetry(data):
            # another backend builds the project, so it reads the metadata from
            # [project] and what remains in [tool.poetry] is only configuration
            logger.log(
                VERBOSE,
                "Ignoring the tool.poetry section, the project is not built with Poetry",
            )
            is_poetry = False

        if is_poetry:
            if has_project:
                logger.log(
                    VERBOSE,
                    "Found Poetry 2.x metadata with project section in pyproject.toml",
                )
            else:
                logger.log(VERBOSE, "Found Poetry 1.x metadata in pyproject.toml")
            self.__wrapped__ = Poetry(
                path, pass_validation=pass_validation, version=2 if has_project else 1
            )
        elif has_project and not is_poetry:
            # brackets are escaped, the log handler renders rich markup
            logger.log(VERBOSE, "Found PEP 621 \\[project] metadata in pyproject.toml")
            self.__wrapped__ = Pep621(path, pass_validation=pass_validation)
        else:
            msg = (
                "The pyproject.toml file is ambiguous. Ensure it has either a PEP 621 "
                "[project] section (uv, hatchling, flit, PDM, setuptools, Poetry 2.x) "
                "or a [tool.poetry] section (Poetry 1.x)."
            )
            raise ValueError(msg)

        super().__init__(self.__wrapped__)

__init__

__init__(path: Path, pass_validation: bool | None = False)

Pyproject wrapper class. Wraps either PEP 621 [project] or Poetry metadata.

The handler is picked based on the metadata tables present in the file, not on the configured build backend.

Parameters:

Name	Type	Description	Default
path	Path	Path to pyproject.toml file.	required
pass_validation	bool	Whether to pass validation. Defaults to False.	False

Raises:

Type	Description
FileNotFoundError	Raised when pyproject.toml file is not found.
ValueError	Neither project nor tool.poetry object is found in pyproject.toml file.

Source code in src/somesy/pyproject/writer.py

def __init__(self, path: Path, pass_validation: bool | None = False):
    """Pyproject wrapper class. Wraps either PEP 621 `[project]` or Poetry metadata.

    The handler is picked based on the metadata tables present in the file,
    not on the configured build backend.

    Args:
        path (Path): Path to pyproject.toml file.
        pass_validation (bool, optional): Whether to pass validation. Defaults to False.

    Raises:
        FileNotFoundError: Raised when pyproject.toml file is not found.
        ValueError: Neither project nor tool.poetry object is found in pyproject.toml file.

    """
    data = None
    if not path.is_file():
        raise FileNotFoundError(f"pyproject file {path} not found")

    with open(path, "r") as f:
        data = load(f)

    # inspect file to pick suitable project metadata writer
    is_poetry = "tool" in data and "poetry" in data["tool"]
    has_project = "project" in data

    if is_poetry and has_project and not _builds_with_poetry(data):
        # another backend builds the project, so it reads the metadata from
        # [project] and what remains in [tool.poetry] is only configuration
        logger.log(
            VERBOSE,
            "Ignoring the tool.poetry section, the project is not built with Poetry",
        )
        is_poetry = False

    if is_poetry:
        if has_project:
            logger.log(
                VERBOSE,
                "Found Poetry 2.x metadata with project section in pyproject.toml",
            )
        else:
            logger.log(VERBOSE, "Found Poetry 1.x metadata in pyproject.toml")
        self.__wrapped__ = Poetry(
            path, pass_validation=pass_validation, version=2 if has_project else 1
        )
    elif has_project and not is_poetry:
        # brackets are escaped, the log handler renders rich markup
        logger.log(VERBOSE, "Found PEP 621 \\[project] metadata in pyproject.toml")
        self.__wrapped__ = Pep621(path, pass_validation=pass_validation)
    else:
        msg = (
            "The pyproject.toml file is ambiguous. Ensure it has either a PEP 621 "
            "[project] section (uv, hatchling, flit, PDM, setuptools, Poetry 2.x) "
            "or a [tool.poetry] section (Poetry 1.x)."
        )
        raise ValueError(msg)

    super().__init__(self.__wrapped__)