Python Packaging: History, Tools, and Best Practices with Poetry and Setuptools

Python packaging has evolved from the built‑in distutils module that relied on a setup.py script, through setuptools which added many features but still used setup.py , to modern tools like Poetry that manage virtual environments and dependencies declaratively via a pyproject.toml file.

Legacy approach (setuptools) : create a setup.py file, list install_requires , package_data , entry_points , etc., and run commands such as python setup.py sdist or python setup.py bdist_wheel . Wheels ( .whl ) are the current standard binary format defined by PEP 427, while eggs ( .egg ) are older and less portable.

Modern approach (Poetry) : initialize a project with poetry init , edit the generated pyproject.toml to specify strict direct dependencies, and let Poetry create an isolated virtual environment. Poetry can build source and binary distributions without needing a separate setup.py file.

The article also covers common dependency problems (conflicting versions, platform‑specific requirements) and shows how tools like pipenv or Poetry resolve them by generating a lock file that pins exact versions.

Key packaging commands and options are listed, including find_packages() , package_data , include_package_data , data_files , and the various setup.py sub‑commands ( sdist , bdist_wheel , develop , register , upload ). Example snippets illustrate a minimal setup.py : <code>from setuptools import setup, find_packages setup( name="HelloWorld", version="0.1", packages=find_packages(), scripts=['say_hello.py'], install_requires=['docutils>=0.3'], package_data={'': ['*.txt', '*.rst'], 'hello': ['*.msg']}, author="Me", author_email="[email protected]", description="This is an Example Package", url="http://example.com/HelloWorld/", classifiers=['License :: OSI Approved :: Python Software Foundation License'] ) </code>

Finally, the process for publishing to the Python Package Index (PyPI) is described: create a .pypirc file with credentials, register the project using python setup.py register , and upload the distribution with python setup.py sdist upload (or the newer twine workflow).