Upgrade to Pro — share decks privately, control downloads, hide ads and more …

MadPUG Project Best Practices

MadPUG Project Best Practices

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

C148356d89f925e692178bee1d93acf7?s=128

Ian Cordasco

July 14, 2016
Tweet

More Decks by Ian Cordasco

Other Decks in Technology

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

  6. None
  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
  11. None
  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
  16. None
  17. None
  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
  19. None
  20. None
  21. None
  22. None
  23. None
  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

  31. None
  32. None
  33. None
  34. None
  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.
  38. None
  39. None
  40. THE END thanks for your attention!