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

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

    View full-size slide

  2. DISCLAIMER
    No C extensions here
    OSS examples only

    View full-size slide

  3. TOPICS
    ➤ Project structure
    ➤ Projects involved in packaging
    ➤ distutils
    ➤ setuptools
    ➤ wheel
    ➤ twine
    ➤ pip
    ➤ Documentation & tooling
    ➤ sphinx
    ➤ mkdocs

    View full-size slide

  4. PROJECT
    STRUCTURE
    current best practices

    View full-size slide

  5. SETUP.PY & SETUP.CFG
    ➤ Used to generate project metadata
    ➤ Sometimes used to install project
    ➤ Historically, might use distutils
    ➤ All new projects should use setuptools

    View full-size slide

  6. 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

    View full-size slide

  7. 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

    View full-size slide

  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

    View full-size slide

  9. 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)

    View full-size slide

  10. 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/

    View full-size slide

  11. 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

    View full-size slide

  12. 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

    View full-size slide

  13. 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

    View full-size slide

  14. 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

    View full-size slide

  15. WARNING
    ➤ Please NEVER use “python
    setup.py install” or “ez_install

    ➤ There is no “python setup.py
    uninstall” or “ez_uninstall”
    ➤ Always use pip for
    installation, it can uninstall
    what it installs

    View full-size slide

  16. TOOLING
    pip, wheel, twine

    View full-size slide

  17. 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

    View full-size slide

  18. 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

    View full-size slide

  19. 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

    View full-size slide

  20. DOCS, DOCS,
    DOCS, …
    providing documentation

    View full-size slide

  21. 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

    View full-size slide

  22. BONUS - TOX
    virtual environment
    manager

    View full-size slide

  23. 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.

    View full-size slide

  24. THE END
    thanks for your attention!

    View full-size slide