in Python

Posted by chunyang on November 5, 2019
TAGS: #python

When we create a python package, we will distribute it. There are a couple of ways to achieve this purpose:

  • by source code
  • by whl
  • by uploading it to pypi

The last two methods require us to write a to build the package.


After finishing reading this blog, you are good to write a which behaves well in most cases.

Let’s create a simple package using

├── awesome
│   ├──
│   ├──
│   └── data
│       └── data.txt

The content of the files:

__version__ = "0.0.1"
# __main__
#!/usr/bin/env python
# coding: utf-8

def main():
    print("Hello awesome boy")

if __name__ == "__main__":
#!/usr/bin/env python
# coding: utf-8

from setuptools import find_packages, setup

import awesome

install_requires = ["wheel"]

extras_require = {
    "np": ["numpy"]

def install():
        description="awesome package",
        author="Some awesome team",
        packages=find_packages(where=".", exclude=["ghost"]),
        package_data={"awesome": ["data/data.txt"]},
            "console_scripts": ["awesome = awesome.__main__:main"]


Build an install

python bdist_wheel
cd dist && pip install *.whl && cd -

The first command will generate corresponding *.whl files under dist directory. We can distribute the wheel file or upload it to any pypi server.

Analysis of

The entrance is the setup function. It has a couple of arguments we are interested in.

name, version, description, author

These fields are the common information of your package. Usually we put information in package’s and read from there instead of hard coding them here.


Instruct setup function to find your packages.

find_packages(where='.', exclude=(), include=('*',))
    """Return a list all Python packages found within directory 'where'

    'where' is the root directory which will be searched for packages.  It
    should be supplied as a "cross-platform" (i.e. URL-style) path; it will
    be converted to the appropriate local path syntax.

    'exclude' is a sequence of package names to exclude; '*' can be used
    as a wildcard in the names, such that 'foo.*' will exclude all
    subpackages of 'foo' (but not 'foo' itself).

    'include' is a sequence of package names to include.  If it's
    specified, only the named packages will be included.  If it's not
    specified, all found packages will be included.  'include' can contain
    shell style wildcard patterns just like 'exclude'.


This describes the requirements of your package. Valid forms are:

  • numpy
  • numpy==1.0.0


This is optional. The type is a dict, keys are the extra requirement names, values are similar forms to install_requires. It is used to easily support different extensions without installing everything at the same time.

pip install awesome-0.0.1-py3-none-any.whl\[np\]  # in zsh, to escape

numpy; extra == "np" in /xx/lib/python3.6/site-packages (from awesome==0.0.1) (1.16.4)


We can package additional data with our package. After adding them, how can we retrieve them?

import pkg_resources
path = pkg_resources.resource_filename("awesome", "data/data.txt")


entry_points is used to execute the package as a shell command. We install the wheel file genereated in dist directory. For example, previous package can be directly executed as awesome. It will print “Hello awesome boy”.

> Hello awesome boy