TL;DR

• Projects only have pyproject.toml (No setup.py)
  • Just use pip >= 19.0
• pip >= 10.0 starts to support PEP 518
• pip >= 19.0 starts to support PEP 517

Why not setup.py anymore?

Accroding to the "Rationale" section of PEP 518:

Using an executable file to specify build requirements under distutils isn't an issue as distutils is part of Python's standard library. Having the build tool as part of Python means that a setup.py has no external dependency that a project maintainer needs to worry about to build a distribution of their project. There was no need to specify any dependency information as the only dependency is Python.

But when a project chooses to use setuptools, the use of an executable file like setup.py becomes an issue. You can't execute a setup.py file without knowing its dependencies, but currently there is no standard way to know what those dependencies are in an automated fashion without executing the setup.py file where that information is stored. It's a catch-22 of a file not being runnable without knowing its own contents which can't be known programmatically unless you run the file.

Why pyproject.toml?

• Say goodbye to lots of requirements.txt files, you just need pyproject.toml
• Say goodbye to setup.py, you just need pyproject.toml
  • No need to write the dependencies in both requirements.txt and setup.py.
  • Or parsing the requirements.txt in setup.py.
• There are some tools start to read their config from pyproject.toml

Poetry

Pros

• It locks the dependency and generates poetry.lock file just like pipenv
• The reason why I use poetry instead of pipenv:
  • During my last job, we use pipenv at first.
  • One day, we encountered a strange bug which only showed on the production machine.
  • It turns out the problem is pipenv didn't lock the dependencies properly.
  • We confirmed the bug is made by pipenv.
  • We just give Poetry a try.
  • It fixed the problem.
• Other reasons why you should consider not using pipenv in 2020 can be found in this blog post: Pipenv: promises a lot, delivers very little | Chris Warrick
• Poetry is not the first package manager accepts pyproject.toml.
  • I use flit 1.0 back in Apirl, 2018, which supports pyproject.toml
  • And that's the time I know pyproject.toml
  • flit is still being developed and it's lastest version is 2.3.0 now.
  • But, Poetry has more features.

Cons

This project is young and still developing. So, like other young projects, lots of things are WIP:

• During the time I wrote this blog post. It hasn't support the platforms in setup.py, but it does have the platforms metadata in the code.
• Some documentations are not so clear, so you need to search GitHub issues and read lots of discussion to find the answer. And it might be changed in the future.
  • [tool.poetry.scripts] in pyproject.toml works like scripts in setuptools
    • while some people think it's a task runner.
  • [tool.poetry.plugins] in pyproject.toml works like entry_point in setuptools
    • and some people ask "Then why you use the word plugin?"

References

• PEP 517 -- A build-system independent format for source trees | Python.org
• PEP 518 -- Specifying Minimum Build System Requirements for Python Projects | Python.org
• pip — pip 20.1.1 documentation