packaging python project by setuptools - basic usage

setuptools

fully-featured, actively-maintained, python-package-manager
commonly used tool

installation

python -m pip install setuptools

can also install build using pip

python -m pip install build

use setuptools

if have a Python-proj package , must provide a pyproject.toml file

and containing a build-system section

example:

[build-system]
requires = ['setuptools']
build-backend = 'setuptools.build_meta'

in a addition to specifying a build system contain dependencies you also will need to add some package imformation as metadata, content, dependencies, etc.

can be done in same setuptools.toml , or in a separated one : setup.cfg or setup.py

the following example a demonstrates minimun configuration:

# pyproject.tmol
[build-system]
name='example-package'
dependencies = [
    "requests",
    'importlib-metadata; python_version == "3.8"',
]

# setup.py
from setuptools import setup

setup(
    name="example-package",
    version="0.1",
    install_requires = [
        "requests",
        "importlib-metadata; python_version == "3.8",
    ]
)

# setup.cfg
[metadata]
name = 'example-package',
version = 0.1

[options]
install_requires = 
    requests
    importlib-metadata; python_version == "3.8"

finally, distributing you python code into something that looks like the following:

example-package
|
|---> pyproject.toml
|     or `setup.py` or `setup.cfg`
|---> package
|     |
|     |---> __init__.py
|     |---> other code file...

package discovery

specify all proj-package and all namespace is vital , if you proj that follow a simple directory structure , setuptools can automatically detect all packages and namespaces

as shown in the example below:

# setup.py
from setuptools import setup, find_packages

setup(
    packages=find_packages(),
    ...
)

# if proj is complex structure

setup(
    package=find_packages(
        where=".",
        include=['mypackage folder'],
        exclude=['some folder or file like test code']
    ),
    ....
)

# pyproject.toml, addtional section `[tool.setuptools.packages.find]`
[tool.setuptools.package.find]
where = ["."]
include = ["..."]
exclude = ["..."]

[options]
packages = find:

[options.packages.find]
include = mypackage*
exclude = mypackage.tests*

entry points and automatic script creation

entry points means cli command name , like pip install instead of having to type python -m pip install

# setup.py

setup(
    ...
    entry_points = {
        'console_scripts': [
            'mycliname=mypackage.somemodule:some_func'
        ]
    }
)

[project.script]
mycliname = 'mypackage.somemodule:some_func'

[options.entry_potins]
console_scripts = 
    mycliname = mypackage.somemodule:some_func

Dependency management

setuptools must specify all dependencies in configuration
its to be automatically installed when the package itself is installed

that looks like the following below:

# setup.py
setup(
    install_requires=[
        "requests",
        "flask == 0.1"
    ],
)

# pyproject.toml
[project]
dependencies = [
    "requests",
    "flask == 0.1"
]

# setup.cfg
[options]
install_requires=
    requests
    flask == 0.1