python-package-quickstart

Python Packages Tutorial 🐍 📦

A simple template for a Python project that can be installed with pip - includes docs and tutorial

Go to source code:

About

This project is a quick reference, tutorial and demo for making a Python project installable using the pip install PACKAGE command. For full details, see the linked resources.

• Python 3.6+
• Project settings configured for VS Code

Resources

Official docs

• Python Packaging site
  • packaging.python.org Homepage
  • Packaging Python Projects tutorial. Most of this guide is based on that.
  • Installing packages tutorial.
  • Key projects
    • twine package - for uploading to PyPI.
    • setuptools package.
    • wheel package.
• Python 3 docs
  • Modules tutorial.
• PyPI site
  • pypi.org homepage.
  • Help page. See Basics for answers:
    • What’s a package, project, or release?
    • How do I install a file (package) from PyPI?
    • How do I package and publish my code for PyPI?

Other

• How to Publish Your Own Python Package to PyPI

Source Distributions vs Wheels

Pre-built wheels are faster than using source distributions, but both are supported.

From pip docs

pip can install from either Source Distributions (sdist) or Wheels, but if both are present on PyPI, pip will prefer a compatible wheel.

Wheels are a pre-built distribution format that provides faster installation compared to Source Distributions (sdist), especially when a project contains compiled extensions.

If pip does not find a wheel to install, it will locally build a wheel and cache it for future installs, instead of rebuilding the source distribution in the future.

Publish with Poetry

As an alternative to using setup.py and twine, you can use Poetry to publish your package. This also avoids maintaining package versions in two places at once (requirements.txt and setup.py).

See Libraries on Poetry docs (though “Packages” is a better name) and see the Publish command.

Related projects

• MichaelCurrin/py-project-template

Guide

What you’ll get at the end of this tutorial

• A standard well-structured Python project outline.
• Your project can be installed using pip or python setup.py.
• Make your project installable using pip and a Github URL.

Note on publishing:

• This does not cover publishing to PyPI, as that is more restrictive especially if you’re a beginner for packaging. For PyPI, you have to setup an account, meet the quality standards (maybe get approval?) and your package becomes searchable.
• A GithHub package published to GitHub instead of PyPI is lower profile and has lower barriers to experiment with. Also, you can make your project private for your user or org, but still install it where you have access.

Typical structure

Here the repo or cloned folder is sample-project with a hyphen.

Inside the repo is sampleproject which may not have a hyphen (otherwise you can’t import it as package) and using an underscore is discouraged. See PEP-8.

sample-project
  sampleproject/
    foo/
      __init__.py
    __init__.py
    sampleproject.py
  tests/
  setup.py
  LICENSE
  README.md

Note that a directory and a script are both considered a “module” in Python if it can be imported.

Init file

See init file tutorial page.

Main file

See main file tutorial page.

A main file is a script or an entrypoint to be run directly, but it might be considered a module if you import it from elsewhere. A convention is that this main script matches package name as in the example. You can also make it __main__.py.

Intra-package references

See section of tutorial.

from . import echo
from .. import formats
from ..filters import equalizer

This site is open source. Improve this page.