Like most programming languages, Python offers an extremely powerful development platform to create some of the most useful and robust applications imaginable. However, as Spider-Man and Winston Churchill have taught us, with great power comes great responsibility. Here are our thoughts on Python best practices to help you harness everything Python has to offer.
Today we'll examine a few of the critical Python best practices used to create more professional, cleaner code.
Most developers, no matter the language, will begin a new project by settings up a code repository and some form of version control.
While endless debates can (and do) take place arguing about which version control system is best or where to host your project repositories, no matter what you decide to use, it's critical to focus on structuring your project and subsequent repository in a suitable fashion.
For Python, in particular, there are a few key components that should exist within your repository, and you should take the time to generate each of these, at least in a basic skeletal form, before actual coding begins.
All told, this means a basic Python repository structure might look something like this:
docs/conf.py
docs/index.rst
module/__init__.py
module/core.py
tests/core.py
LICENSE
README.rst
requirements.txt
setup.py
Set up new projects with the above-mentioned repository to keep project set-up consistent and organized. Now, onto the next Python best practice, which also has to do with consistency.
Python has a system of community-generated proposals known as Python Enhancement Proposals (PEPs) which attempt to provide a basic set of guidelines and standards for a wide variety of topics when it comes to proper Python development.
Perhaps one of the most widely known and referenced PEPs ever created is PEP8, which is the "Python community Bible" for properly styling your code.
While there are far too many specific styling guidelines to give examples here, most Python developers make a concerted effort to follow the guidelines set forth in PEP8, so all code across the community has a similar look and feel.
Perhaps you've heard of the broken windows theory, which is a criminological theory that states that the proper maintenance and monitoring of urban environments in cities, in order to prevent lesser crimes, creates a more positive atmosphere that thereby prevents greater crimes from occurring.
While this theory, as it relates to crime prevention, is highly criticized and contested, it has some merit when it comes to the world of coding and application development.
Specifically, when creating a Python application (or any language for that matter), it is almost always more beneficial in the long-term to quickly acknowledge and repair broken windows (i.e. broken code) immediately. Putting it off to finish a new component or module can and will often lead to further, more complex problems down the line.
It has even been stated that Microsoft, after a terrible production cycle with the original version of Microsoft Word, adopted a "zero defects methodology" to their great benefit, always focusing on fixing bugs and defects before new production code. While this accounting may be apocryphal, there is a certain logic to applying this model during development.
As much as it can feel like a burden at times, proper documentation throughout the lifecycle of a project is a cornerstone to clean code. Thankfully, the Python community has made this process fairly painless, and it involves the use of three simple tools and concepts: reStructredText, Docstrings, and Sphinx.
reStructredText is a simple plain text markup syntax. It is commonly used for in-line documentation, which in the case of Python, allows for documentation to be generated on-the-fly. The Quickstart Guide provides a few simple examples of reStructuredText in action.
While using reStructuredText is the first step to proper documentation, it's critical to understand how to properly generate Docstrings. A Docstring is simply a documentation string that appears prior to every module, class, or method within your Python code.
Once every component of your code contains a properly formatted Docstring using reStructuredText markdown, you can move onto using Sphinx, which is the go-to tool to generate Python documentation from existing reStructuredText.Sphinx allows documentation to easily be exported into a variety of formats, including beautiful HTML, for near-automatic online documentation pages. With virtually no effort, your project documentation can even be added to the prominent ReadTheDocs documentation repository after every code commit.
While using proper syntax and documentation methods will always produce solid, clean code, perhaps one of the best tools to improving your use of Python is the epic module repository known as PyPI: The Python Package Index.. As a collective repository for thousands of Python projects, including nearly every open or public Python project created, PyPI is an undeniably useful resource, no matter your Python experience level or project scope.
There are two primary uses for PyPI: Using existing modules, or adding your own project to PyPI.
Most projects will initially begin by utilizing existing projects on PyPI, and with nearly 100,000 at the time of writing to choose from, there's almost certainly some code that fits your project's needs. Once you've located a module you're interested in using within your own project, the fun can begin.
Next, you'll want to utilize the Python Packaging Authority recommendations for installing a package from PyPI. Typically this entails using pip, the go-to package installation software. If you're using Python 2 >=2.7.9 or Python 3 >=3.4, pipcomes pre-installed with Python.
Once pip is installed, simply run the appropriate command, as suggested by the module documentation within PyPI. For example, to install requests, a common module to handle HTTP requests, you'd simply use the following command from the root directory of your project:
pip install requests
pip will then take care of the rest and install the package. Now you can keep adding more modules to help your code shine!
Down the road, if you've got a decent module of your own created and wish to share it with the rest of the Python community, you'll want to take a look at the Python Distribution documentation, which handles the finer details of packaging your project, as discussed earlier.
Most importantly, look over the simple steps to Upload Your Project to PyPI, which requires you to: Signup for a PyPIaccount, register your project, and then upload it to PyPI for others to view and add to their own projects!