Core Files and Directories

There are only two required files, and one required directory:

  • /pypi_package_example/ This is the main project directory where all the Python source code goes. The directory should be named the same as your package name. Check the PyPi Package Index to make sure there isn’t a conflict before picking your package name.
  • /pypi_package_example/__init__.py This is the starting file for your project. It is run when you import your package. It should not do much processing, it should just load in all the functions and classes that you plan on using in your project.

Setup File

  • /setup.py or /setup.cgf. This specifies how your project is to be built, and other meta information about the project. The /setup.py seems more common based on my limited experience, but in 2016 PEP 518 was provisionally accepted which specifies a different setup method, to be stored in a file called setup.cfg.

Setup File In Detail

When you run setup.py, you can get a full list of commands:

setup.py options
(venv) C:\pypi_package_example>python setup.py --help-commands
Standard commands:
  build             build everything needed to install
  build_py          "build" pure Python modules (copy to build directory)
  build_ext         build C/C++ extensions (compile/link to build directory)
  build_clib        build C/C++ libraries used by Python extensions
  build_scripts     "build" scripts (copy and fixup #! line)
  clean             clean up temporary files from 'build' command
  install           install everything from build directory
  install_lib       install all Python modules (extensions and pure Python)
  install_headers   install C/C++ header files
  install_scripts   install scripts (Python or otherwise)
  install_data      install data files
  sdist             create a source distribution (tarball, zip file, etc.)
  register          register the distribution with the Python package index
  bdist             create a built (binary) distribution
  bdist_dumb        create a "dumb" built distribution
  bdist_rpm         create an RPM distribution
  bdist_wininst     create an executable installer for MS Windows
  check             perform some checks on the package
  upload            upload binary package to PyPI

Extra commands:
  bdist_wheel       create a wheel distribution
  build_sphinx      Build Sphinx documentation
  flake8            Run Flake8 on modules registered in setup.py
  compile_catalog   compile message catalogs to binary MO files
  extract_messages  extract localizable strings from the project code
  init_catalog      create a new catalog based on a POT file
  update_catalog    update message catalogs from a POT file
  alias             define a shortcut to invoke one or more commands
  bdist_egg         create an "egg" distribution
  develop           install package in 'development mode'
  dist_info         create a .dist-info directory
  easy_install      Find/get/install Python packages
  egg_info          create a distribution's .egg-info directory
  install_egg_info  Install an .egg-info directory for the package
  rotate            delete older distributions, keeping N newest files
  saveopts          save supplied options to setup.cfg or other config file
  setopt            set an option in setup.cfg or another config file
  test              run unit tests after in-place build
  upload_docs       Upload documentation to PyPI

usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help

The setup.py file itself can be pretty simple. As it is Python, you can keep adding onto it as your project gets more complex and you need more customization. See the setup.py documentation for an idea of what you can do with that file.

setup.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
#!/usr/bin/env python

from os import path
from setuptools import setup

VERSION = "1.0.0"

if __name__ == "__main__":

    # List of all the required packages.
    install_requires = [
        "arcade",
    ]

    # Grab the long description out of the README
    fname = path.join(path.dirname(path.abspath(__file__)), "README.rst")
    with open(fname, "r") as f:
        long_desc = f.read()

    # Call the setup function with our setup parameters.
    # This kicks off the build.
    setup(
        name="arcade",
        version=VERSION,
        description="Sample Python Package",
        long_description=long_desc,
        author="Paul Vincent Craven",
        author_email="paul.craven@simpson.edu",
        license="MIT",
        url="https://pypi-package-example.readthedocs.io/en/latest/",
        install_requires=install_requires,
        packages=["pypi_package_example"],
        python_requires=">=3.6",
        classifiers=[
            "Development Status :: 5 - Production/Stable",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3.8",
            "Programming Language :: Python :: Implementation :: CPython",
            "Topic :: Software Development :: Libraries :: Python Modules",
        ],
        test_suite="tests",
        package_data={"arcade": ["examples/images/*.png"]},
        project_urls={
            "Documentation": "https://pypi-package-example.readthedocs.io/en/latest/",
            "Issue Tracker": "https://github.com/pvcraven/pypi_package_example/issues",
            "Source": "https://github.com/pvcraven/pypi_package_example",
        },
    )