MadPUG Project Best Practices

A talk about best practices for python projects written for Madison Python Users Group

Transcript

1. DISTRIBUTING AND DOCUMENTING PYTHON PACKAGES Presented to MadPUG 14 July 2016
2. DISCLAIMER No C extensions here OSS examples only
3. TOPICS
4. TOPICS ➤ Project structure ➤ Projects involved in packaging ➤ distutils ➤ setuptools ➤ wheel ➤ twine ➤ pip ➤ Documentation & tooling ➤ sphinx ➤ mkdocs
5. PROJECT STRUCTURE current best practices
7. SETUP.PY & SETUP.CFG ➤ Used to generate project metadata ➤ Sometimes used to install project ➤ Historically, might use distutils ➤ All new projects should use setuptools
8. SETUP.PY & SETUP.CFG ➤ DISTUTILS & SETUPTOOLS ➤ distutils is a standard library module ➤ Currently frozen in time (~ 10 years ago or so) ➤ Very old, very few benefits ➤ setuptools is a third-party module ➤ Actively developed and released ➤ Builds on distutils’ legacy ➤ Both generate: ➤ metadata ➤ installation instructions
9. SETUP.PY & SETUP.CFG ➤ DISTUTILS & SETUPTOOLS ➤ distutils is a standard library module ➤ Currently frozen in time (~ 10 years ago or so) ➤ Very old, very few benefits ➤ setuptools is a third-party module ➤ Actively developed and released ➤ Builds on distutils’ legacy ➤ Both generate: ➤ metadata ➤ installation instructions
10. SETUP.PY & SETUP.CFG ➤ DISTUTILS & SETUPTOOLS ➤ distutils is a standard library module ➤ Currently frozen in time (~ 10 years ago or so) ➤ Very old, very few benefits ➤ setuptools is a third-party module ➤ Actively developed and released ➤ Builds on distutils’ legacy ➤ Both generate: ➤ metadata ➤ installation instructions
12. README ➤ Should contain ➤ an overview of what the project does ➤ specific examples of how to use it (or a link to those) ➤ alternatives (or competitors) that you’re aware of and why this project is better than them ➤ how to install the project (e.g., pip install flake8)
13. LICENSE ➤ Only necessary for OSS projects ➤ This is the standard location for the text of whatever license you pick ➤ No I’m not going to tell you what license is best ➤ https://opensource.org/licenses ➤ http://choosealicense.com/
14. CONTRIBUTING ➤ Answer these questions: ➤ How can other people help? ➤ Docs? ➤ Issues? ➤ Code submission? ➤ Other? ➤ How do others comport themselves? ➤ i.e., Code of Conduct ➤ Useful for open and closed source projects
15. CHANGELOG ➤ Documents ➤ Release number/version string ➤ Release date ➤ Changes to that release including ➤ Bug fixes ➤ Features ➤ Deprecations ➤ Changes to dependencies ➤ Anything else that may be interesting to users
18. WHY USE SRC? ➤ Testing purposes ➤ Want to only run tests against the installed version ➤ Want to run tests from directory containing “src” ➤ Want to avoid accidentally importing package in tests ➤ Makes it explicit what is the package source code
24. SETUP.PY HAS COMMANDS?! ➤ setuptools.setup actually will parse the arguments passed after it on the command-line and accepts: ➤ egg_info ➤ sdist ➤ build ➤ install ➤ test ➤ and more
25. WARNING ➤ Please NEVER use “python setup.py install” or “ez_install <package>” ➤ There is no “python setup.py uninstall” or “ez_uninstall” ➤ Always use pip for installation, it can uninstall what it installs
26. TOOLING pip, wheel, twine
27. PIP: PACKAGE INSTALLATION MANAGER ➤ Securely downloads things from pypi.python.org (or pypi.io) ➤ Verifies the download before installing ➤ Correctly installs and uninstalls packages ➤ Caches packages locally on disk for future installation speed ➤ Will cache wheels if it can build them
28. WHEEL: BINARY PYTHON PACKAGE FORMAT ➤ This is a recent binary format for Python packages ➤ Makes installations FAST ➤ pip install wheel ➤ https://www.python.org/dev/peps/pep-0427/ ➤ Advanced features: ➤ Universal wheels can be installed on Python 2 and 3 ➤ Can contain compiled extensions ➤ If not universal, will contain platform tags ➤ All of this can be chatted about afterwards
29. TWINE: UPLOADING PACKAGES ➤ Uploads packages to your repository (e.g., PyPI) ➤ Verifies HTTPS connection before upload ➤ Authenticates for you ➤ Will properly upload multiple package files ➤ Will GPG sign your package for you and upload signatures
30. DOCS, DOCS, DOCS, … providing documentation
35. DOCUMENTATION TOOLING ➤ Sphinx ➤ Uses reStructuredText ➤ Created by Python core developers to document Python ➤ Extendable, extends RST ➤ Used by docs.python.org ➤ Mkdocs ➤ Uses Markdown ➤ Both supported by readthedocs.org
36. BONUS - TOX virtual environment manager
37. TOX ➤ Configured by the tox.ini in our directory ➤ Primarily used for running tests ➤ Manages virtual environments for you ➤ Makes it a good tool for running things in a virtualenv ➤ E.g., docs generation, releasing projects, linting, etc.
40. THE END thanks for your attention!