Python File Headers
There are many resources that teach you how to write code, but when it comes to writing clean and readable code, many beginners are unaware of the principles and techniques. In this article, we’ll explore how to write Python headers, one of many things that can level up the readability of your code.
What are Python Headers?
In general, file headers are blocks of information — often positioned at the top of the file — that contain metadata about the file and its content.
Similar to this, a Python Header consists of a shebang and a docstring present at the top of the file that provides more information about the file and the code present inside it.
Why use Headers?
As mentioned, headers provide metadata about the file that can help understand the context as well as track the changes in the file. It not only helps the readers, but the developers to get up to speed quickly with the context.
What’s a shebang?
You might see something like #! /user/bin/env python in Python scripts. The #! is referred to as the shebang. It is Unix feature of executable scripts and specifies the path of a valid executable.
You can specify the pathname to define a certain version of Python on the machine. Following are some examples
#! /usr/bin/env python
executes any python executable present on the machine.
#! /usr/bin/python
used in cases when python is installed in the /usr/bin directory.
#! /usr/bin/python2.7
used in cases to execute a specified version of the python executable.
#!python
works only if the python executable is present in the current directory.
What other metadata should I add?
Other than the shebang, there are a few more things you should add in your header.
Encoding
You can specify the encoding for the scripts. UTF-8 is the most commonly used encoding. Here’s how you do it-*-coding: utf-8 -*-
Docstrings
Docstrings are usually used to provide documentation or explanation on important pieces of code. Explain the type of expected input values and what the piece of code does (usually functions).
You start with a short description of the file followed by the descriptions for the functions.
NOTE: Your code must only start after the docstring, else it won’t be recognized.
Dunders
You can then add information about the author and other relevant information for the file using the following
__author__ = "Author Name"
__copyright__ = "Copyright Info"
__credits__ = ["Author", "Author"]
__license__ = "License Name and Info"
__version__ = "0.0.0"
__maintainer__ = "Author"
__email__ = "contact@email.com"
__status__ = "status of the file"Now, you are not limited to these, you can use some of them or add more information. The reason we write the info this way is to access it.
What is a proper format?
Although there is no hard-defined format you should use, here’s a frequently used format. You don’t have to use all the prompts mentioned here strictly, feel free to add and remove metadata according to your use case, but keep the format similar and information relevant.
You can follow this format
Code Snippet: code
Python Things Repository: repo
Footnote
Hope you liked this small article and that it helps you write better Python code. I plan to fill this series with small articles about python concepts, tips, tricks, and tutorials.
You can find me here:
Originally published at https://dev.to on January 18, 2023.
