feat(cli): fallback to build-in poetry-core on build

[finswimmer]

Pull Request Check List

When we cannot find a [build-system] section or a build-backend within this section in a pyproject.toml we assume setuptools as the build backend This is fine according to PEP 517.

While this approach is valid for dependencies it would be surprising on poetry build, now that an isolated build happens if the build-system is not poetry-core.

Before #10059 poetry build had created the package even if no build backend was defined in the pyproject.toml. Now it would fallback to setuptools which would results in a broken package.

This PR checks if a there is a [build-system] section and has a build-backend defined in the pyproject.toml and will use the build-in poetry-core if none is define. In addition a warning is presented to the user to fix it.

• Added tests for changed code.
• Updated documentation for changed code.

Summary by Sourcery

Tests:

• Added a test to verify that the build command fails when no build system is defined in the pyproject.toml file.

Summary by Sourcery

Tests:

• Added a test to verify that the build command fails when no build system is defined in the pyproject.toml file.

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request ensures that a build backend is defined in the pyproject.toml file when running poetry build. It prevents the build process from falling back to setuptools, which could result in a broken package. The changes include adding a check for the build backend and a new test case to verify the behavior.

Sequence diagram for poetry build command with build backend check

sequenceDiagram
    actor User
    participant CLI
    participant BuildCommand
    participant PyProject

    User->>CLI: poetry build
    CLI->>BuildCommand: execute build
    BuildCommand->>PyProject: check build-backend
    alt No build backend defined
        PyProject-->>BuildCommand: build-backend not found
        BuildCommand-->>CLI: return error (1)
        CLI-->>User: Show error message
    else Build backend defined
        PyProject-->>BuildCommand: build-backend found
        BuildCommand->>BuildCommand: proceed with build
        BuildCommand-->>CLI: return success (0)
        CLI-->>User: Build completed
    end

Loading

File-Level Changes

Change	Details	Files
Added a check to ensure a build backend is defined in pyproject.toml.	Added a _has_build_backend_defined method to check for the presence of a build backend in the pyproject.toml file. Modified the build method to check if a build backend is defined and abort the build if it is not.	src/poetry/console/commands/build.py
Added a test case to verify that the build command fails when no build system is defined.	Added a new test case test_build_handler_raise_on_no_build_system to verify that the build command fails when no build system is defined in the pyproject.toml file.	tests/console/commands/test_build.py
Added new fixtures for testing the build command.	Added a pyproject.toml file without a build backend. Added a pyproject.toml file without a build system. Added a README.md file for the no_build_backend fixture. Added a README.md file for the no_build_system fixture.	tests/fixtures/build_systems/no_build_backend/pyproject.toml tests/fixtures/build_systems/no_build_system/pyproject.toml tests/fixtures/build_systems/no_build_backend/README.md tests/fixtures/build_systems/no_build_system/README.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @finswimmer - I've reviewed your changes - here's some feedback:

Overall Comments:

• Please update the documentation to explain this new validation check and behavior change, since this changes how Poetry handles projects without a build-system defined.

Here's what I looked at during the review

• 🟢 General issues: all looks good
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[finswimmer]

@sourcery-ai review

[sourcery-ai]

Hey @finswimmer - I've reviewed your changes - here's some feedback:

Overall Comments:

• Please update the documentation to describe this new validation check for build backend configuration. This is a user-facing change that should be documented.

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion: Consider making the error message more specific about whether the build-system section is missing or just the build-backend key

This would help users identify and fix configuration issues more quickly.

Suggested implementation:

    def _get_build_system_status(self) -> tuple[bool, bool]:
        pyproject_data = self.poetry.file.read()
        has_build_system = "build-system" in pyproject_data
        has_build_backend = "build-backend" in pyproject_data.get("build-system", {})
        return has_build_system, has_build_backend

        has_build_system, has_build_backend = self._get_build_system_status()
        if not has_build_system:
            self.io.write_error_line(
                "Missing [build-system] section in pyproject.toml. Please add this section with a build-backend."
            )
            return 1
        if not has_build_backend:
            self.io.write_error_line(
                "Missing build-backend key in [build-system] section. Please define one in pyproject.toml."
            )

[abn]

Would be good to move this to be something like self.poetry.pytpoject.build_system.is_fallback.

But that will need an additional property in https://github.com/python-poetry/poetry-core/blob/d97577e664d59173482a78f70e8f743cc5468851/src/poetry/core/pyproject/tables.py#L12

But for now something like this should work.

Suggested change

	return "build-backend" in self.poetry.file.read().get("build-system", {})
	return "build-backend" in self.poetry.pyproject.data.get("build-system", {})

[finswimmer]

Ah, I wasn't aware of the data attribute of pyproject 👍

I thought about a flag as well. But I don't wanted to change poetry-core before. And we would pollute again poetry-core with something we only need in poetry. Actually we only need it for poetry build.

[abn]

Won't this also be a surprise to users as this breaks previous behavior in the same way setuptools are being used? Not sure how many people leave out the section intentionally.

That said, I'd also say that the current use of setuptools is in accordance with PEP518.

Tools should not require the existence of the [build-system] table. A pyproject.toml file may be used to store configuration details other than build-related data and thus lack a [build-system] table legitimately. If the file exists but is lacking the [build-system] table then the default values as specified above should be used. If the table is specified but is missing required fields then the tool should consider it an error.

[finswimmer]

Won't this also be a surprise to users as this breaks previous behavior in the same way setuptools are being used?

It will surprise people for sure. But now they get an error message. Without it poetry build would build a package, but it won't contain the data people expect. So "fail fast" is a better surprise ;)

[abn]

The problem is, how do you determine if they intended to use setuptools by relying on PEP518 default?

It is not unreasonable to imagine that Poetry is used for dev but the package needs setuptools for build.

[abn]

But this is an edge enough case that it might be okay to enforce a build-system definition.

[dimbleby]

we assume setuptools as the build backend This is fine according to PEP 517.

it's not only "fine" - it's what PEP517 says tools should do.

Now it would fallback to setuptools which would results in a broken package.

only results in a broken package if the pyproject.toml is not understood by setuptools, presumably? In the new PEP621 world that is not going to be a problem.

Perhaps a warning would make sense, but I suggest that erroring out where the specs say tools should not error out is overshooting.

[finswimmer]

In the new PEP621 world that is not going to be a problem.

In the PEP 621 world, yes. But if the project doesn't (fully) use the project section it is a problem.

As an alternative we could trigger a non-isolated build if no build-backend is given and (optional) show a warning that it would be good idea to add one to the pyproject.toml. Than poetry would behave just like before #10059.

[abn]

Allowing the build to continue into isolated with a warning is safe enough, I reckon.

Let's not add more logic unless we need it.

That said I can already see the issues titled "why is poetry using setuptools" etc.

[radoering]

I am in favor of being backward compatible to the point of using poetry-core by default if no backend is defined. Printing a warning is fine.

It will be far more common that people have no backend defined and still used poetry build than that people that have no backend defined will be wondering that poetry-core is used instead of setuptools.

[abn]

I am okay with defaulting to poetry-core too to maintain backwards compat.

Although I was looking forward to just being able to build arbitrary setuptool projects (which a lot of times do not have the build-system specified by simply calling poetry build. But that is a niche use case.

[finswimmer]

@sourcery-ai review

[dimbleby]

I think this is a wrong direction, the specs are explicit about what the behaviour should be in case there is no backend defined.

It is not "fall back to poetry-core", and it is not "report an error". It is "use setuptools.build_meta:__legacy__".

Anyway you will want to have an answer ready for when folk turn up complaining that poetry is not behaving as it is supposed to.

[dimbleby]

eg poetry build will now give different results than building with any other front end. (Consider someone installing from a source distribution on PyPI.)

[finswimmer]

eg poetry build will now give different results than building with any other front end. (Consider someone installing from a source distribution on PyPI.)

This was always the case until now, because poetry build always used poetry-core to build the package, no matter if and what build-system was given in the pyproject.toml.

It's arguable to not throw in error in the future, if no build-system is given and instead use setuptools. But doing it now would be a breaking change and we should give people time to fix there packages and/or make the transition to PEP 621.

[dimbleby]

This was always the case until now

this is not correct, I think there are two cases and we are perhaps talking slightly past one another

In the case of a pyproject.toml with metadata defined in tool.poetry, the only build-backend that ever would have worked was poetry-core. You are right that poetry build always used that backend regardless. Other front-ends would almost certainly fail to produce anything at all if the backend was not specified. (Edit: this is not correct, they use setuptools and produce undesirable wheels)

In the case of a PEP-621 variant pyproject.toml, poetry is unambiguously going against the spec by falling back to poetry-core. And in this case other front-ends will use setuptools, and they likely will get a wheel but not a good one, and by not going with what the spec says we are introducing this confusion.

In the tool.poetry case, there is an argument for falling back to poetry-core: I agree anyway that this is preserving the old behaviour (though not necessarily that this is a good thing!)

In the PEP-621 case I really think that there is not a good argument for falling back to poetry-core and even that it is clearly the wrong thing to do.

[radoering]

I think there is one (and probably the only) good argument: backwards compatibility. As of now (no matter if PEP 621 or not) all released versions do use poetry-core as build-backend, no matter what is defined.

In my opinion, it still makes sense to default to poetry-core with a warning that this is deprecated and you should define a build-backend and in future we will fall back to setuptools because that is what the spec says.

I do not think that it is that important to be compatible with projects that do not define a build-backend (and expect setuptools) - famous last words. If you manage a project with poetry you should define a build-backend. Maybe, poetry check should give an error/warning if package-mode is true and no build-backend is defined.

[dimbleby]

If you manage a project with poetry you should define a build-backend.

Sure - we can go further - if you manage a project with anything at all, you should define a build backend.

So far as I know no-one thinks that omitting a build backend is the right thing to do, even the PEP517 stuff about how to handle that is (as I understand it) really aimed at projects that have not yet added a build backend.

The question is whether we are justified in overruling the specs and choosing a different fallback than we "should".

Defaulting to poetry-core clearly made sense pre-PE517 and pre-PEP621. If nothing else: poetry was here first, and it is hardly poetry's fault if the specs retrospectively asked it to do something else.

But anyway the poetry-core default made sense where there was no reasonable expectation of successfully building a poetry project except with poetry-core; and where there was definitely no hope of using poetry to build a project that used another backend. It wasn't really even a default: it was just "always use poetry-core".

But the world has moved on:

• poetry has adopted the standard format, it is now totally reasonable to use poetry for project management while choosing a different backend eg for projects with build scripts
• on the main branch poetry is now build-system-agnostic

IMO those changes really both drive big holes through "default to poetry-core": it is time to get in line with the standards.

(I think I've said my piece - possibly too many times, sorry! - and will leave it there)

[abn]

I agree with

In my opinion, it still makes sense to default to poetry-core with a warning that this is deprecated and you should define a build-backend and in future we will fall back to setuptools because that is what the spec says.

And that is my vote for now. We do a hard deprecation.

1. Issue a warning during build in the next release and fallback iff no build-backend is defined.
2. Call attention to this in the blog post.
3. Next release + 1 conform to spec (because in the long run this is the right thing to do).

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.