You wrote a Python library. I'm sure it's amazing! Wouldn't it be neat if it was easy for people to use it? Here is a checklist of things to think about and concrete steps to take when open sourcing your Python library.
1. Source
Put the code up on GitHub, where most open source projects happen and where it is easiest for people to submit pull requests.
2. License
Choose an open source license. A good, permissive default is the MIT License. If you have specific requirements, Creative Common's Choose a License can guide you through the alternatives. Most importantly, there are three rules to keep in mind when choosing a license:
- Don't create your own license.
- Don't create your own license.
- Don't create your own license.
3. README
Put a file called README.rst, formatted with ReStructured Text, at the top of your tree.
GitHub will render ReStructured Text just as well as Markdown, and ReST plays better with Python's documentation ecosystem.
4. Tests
Write tests. This is not useful just for you: it is useful for people who want to make patches that avoid breaking related functionality.
Tests help collaborators collaborate.
Usually, it is best if they are runnable with pytest. There are other test runners—but very little reason to use them.
5. Style
Enforce style with a linter: PyLint, Flake8, or Black with --check. Unless you use Black, make sure to specify configuration options in a file checked into source control.
6. API documentation
Use docstrings to document modules, functions, classes, and methods.
There are a few styles you can use. I prefer the Google-style docstrings, but ReST docstrings are an option.
Both Google-style and ReST docstrings can be processed by Sphinx to integrate API documentation with prose documentation.
7. Prose documentation
Use Sphinx. (Read our article on it.) A tutorial is useful, but it is also important to specify what this thing is, what it is good for, what it is bad for, and any special considerations.
8. Building
Use tox or nox to automatically run your tests and linter and build the documentation. These tools support a "dependency matrix." These matrices tend to explode fast, but try to test against a reasonable sample, such as Python versions, versions of dependencies, and possibly optional dependencies you install.
9. Packaging
Use setuptools. Write a setup.py and a setup.cfg. If you support both Python 2 and 3, specify universal wheels in the setup.cfg.
One thing tox or nox should do is build a wheel and run tests against the installed wheel.
Avoid C extensions. If you absolutely need them for performance or binding reasons, put them in a separate package. Properly packaging C extensions deserves its own post. There are a lot of gotchas!
10. Continuous integration
Use a public continuous integration runner. TravisCI and CircleCI offer free tiers for open source projects. Configure GitHub or other repo to require passing checks before merging pull requests, and you'll never have to worry about telling people to fix their tests or their style in code reviews.
11. Versions
Use either SemVer or CalVer. There are many tools to help manage versions: incremental, bumpversion, and setuptools_scm are all packages on PyPI that help manage versions for you.
12. Release
Release by running tox or nox and using twine to upload the artifacts to PyPI. You can do a "test upload" by running DevPI.
1 Comment