Creating a Great Python Package

On-Line Resources

setup.py

  • Been around for years
  • Uses built-in setuptools package
  • Lots of documentation

pyproject.toml

Tale of Two Build Systems

  • Newer
  • May want a build system like Poetry
  • Central place for project specs
  • Specify your own build system

setup.py

setuptools / distutils

Dunder Files

  • Python has "Magic" files and methods that are automatically called.
  • These files and methods are surrounded by double-underscores., "dunder" for short
  • For example, __init__(self) is auto-called when creating an instance of a class.
  • And for files, __init__.py is auto-called when importing a package.

Create Initial Files

My Projects  
├── pypi_package_example_setuptools
│   └── pypi_package_example_setuptools
│       └── __init__.py
│   └── setup.py

__init__.py

Must be in folder named same as package name.

"""
Documentation to introduce the package.
"""

# Version number of the project
__version__ = '0.1.0'

def my_function():
    """
    Sample function that prints Hi
    """
    print("Hi")

setup.py

Build Script

#!/usr/bin/env python

from setuptools import setup
from pypi_package_example_setuptools import __version__

if __name__ == "__main__":

    # This kicks off the build.
    setup(version=__version__)

setup.cfg

Build configuration

[metadata]
name = pypi_package_example_setuptools
author = Your Name Here
author-email = person@mail.example
home-page = https://pypi-package-example.readthedocs.io/
description = Sample Python Package With Setuptools
long-description = file: README.rst
license = MIT
platform = any
keywords = packaging
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
	Topic :: Software Development :: Libraries :: Python Modules

[options]
zip_safe = false
include_package_data = true
python_requires = >=3.6
packages = pypi_package_example_setuptools
test_suite = tests
setup_requires =
    setuptools >=38.3.0
install_requires =
tests_require =

Create Virtual Environment

PyCharm

Create Virtual Environment

py -m venv venv
.\venv\Scripts\activate
python3 -m venv venv
source venv/bin/activate

MacOS + Linux

Windows

Build

poetry build

pyproject.py

Poetry

Install Poetry

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/
poetry/master/get-poetry.py -UseBasicParsing).Content | python

Mac/Linux

Powershell

In the case of Windows, you need to add %USERPROFILE%\.poetry\bin to your %PATH%.

Create a new project

poetry new pypi_package_example_poetry

pypi_package_example_poetry
├── pyproject.toml
├── README.rst
├── pypi_package_example_poetry
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_pypi_package_example_poetry.py

__init__.py

Must be in folder named same as package name.

"""
Documentation to introduce the package.
"""

# Version number of the project
__version__ = '0.1.0'

def my_function():
    """
    Sample function that prints Hi
    """
    print("Hi")

pyproject.toml

Must be in folder named same as package name.

[tool.poetry]
name = "pypi_package_example_poetry"
version = "0.1.0"
description = ""
authors = ["Paul Vincent Craven <paul@cravenfamily.com>"]

[tool.poetry.dependencies]
python = "^3.7"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

Create Virtual Environment

poetry env use python

Build

python setup.py build
python setup.py bdist_wheel

Readme

Can be named README.rst or README.md depending if you prefer markdown or restructured text.

Welcome to The Sample PyPi Package!
===================================

This is a PyPi package which was made to 
document how to createa PyPi package.

Documentation
-------------

For full documentation see: 
https://pypi-package-example.readthedocs.io/

Badges
------

.. image:: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)
    :target: http://makeapullrequest.com
    :alt: Pull Requests Welcome
    
Latest Release
--------------

Latest version is 1.0.0 
released 2020-04-22.


Contact the Maintainer
----------------------

paul@cravenfamily.com

Git  Ignore

Named .gitignore

Try starting with a template:

https://github.com/github/gitignore/blob/master/Python.gitignore

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
pip-wheel-metadata/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
#  Usually these files are written by a python script from a template
#  before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest

License

Can be named license.rst or license.md depending if you prefer markdown or restructured text.

License
=======

Copyright (c) 2020 Paul Vincent Craven

The MyExampleLibrary library is licensed under the `MIT License`_.

Permission is hereby granted, free of charge, to any 
person obtaining a copy of this software and associated 
documentation files (the "Software"), to deal in the 
Software without restriction, including without limitation 
the rights to use, copy, modify, merge, publish, distribute, 
sublicense, and/or sell copies of the Software, and to permit 
persons to whom the Software is furnished to do so, 
subject to the following conditions:

Not sure what license?

Visit:

https://choosealicense.com/

Code of Conduct

Can be named:

code_of_conduct.rst

or

code_of_conduct.md

# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and 
welcoming environment, we as
contributors and maintainers pledge to 
making participation in our project and

...

This Code of Conduct is adapted from the 
[Contributor Covenant][homepage], version 1.4,
available at 
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code 
of conduct, see
https://www.contributor-covenant.org/faq

Coverage Testing

coveralls

Continuous Integration

Travis CI

Code Formatting

Flake8 / Black

Made with Slides.com