What is the common header format of Python files?

Also see PEP 263 if you are using a non-ascii characterset

Abstract

This PEP proposes to introduce a syntax to declare the encoding of
a Python source file. The encoding information is then used by the
Python parser to interpret the file using the given encoding. Most
notably this enhances the interpretation of Unicode literals in
the source code and makes it possible to write Unicode literals
using e.g. UTF-8 directly in an Unicode aware editor.

Problem

In Python 2.1, Unicode literals can only be written using the
Latin-1 based encoding “unicode-escape”. This makes the
programming environment rather unfriendly to Python users who live
and work in non-Latin-1 locales such as many of the Asian
countries. Programmers can write their 8-bit strings using the
favorite encoding, but are bound to the “unicode-escape” encoding
for Unicode literals.

Proposed Solution

I propose to make the Python source code encoding both visible and
changeable on a per-source file basis by using a special comment
at the top of the file to declare the encoding.

To make Python aware of this encoding declaration a number of
concept changes are necessary with respect to the handling of
Python source code data.

Defining the Encoding

Python will default to ASCII as standard encoding if no other
encoding hints are given.

To define a source code encoding, a magic comment must
be placed into the source files either as first or second
line in the file, such as:

      # coding=<encoding name>

or (using formats recognized by popular editors)

      #!/usr/bin/python
      # -*- coding: <encoding name> -*-

or

      #!/usr/bin/python
      # vim: set fileencoding=<encoding name> :

…

I strongly favour minimal file headers, by which I mean just:

#!/usr/bin/env python # [1]
"""
This script foos the given bars [2]

Usage: myscript.py BAR1 BAR2
"""
import os   # standard library, [3]
import sys

import requests  # 3rd party packages

import mypackage  # local source

• [1] The hashbang if, and only if, this file should be able to be directly executed, i.e. run as myscript.py or myscript or maybe even python myscript.py. (The hashbang isn’t used in the last case, but providing it gives users the choice of executing it either way.) The hashbang should not be included if the file is a module, intended just to be imported by other Python files.
• [2] Module docstring
• [3] Imports, grouped in the standard way, ie. three groups of imports, with a single blank line between them. Within each group, imports are sorted. The final group, imports from local source, can either be absolute imports as shown, or explicit relative imports.

Everything else is a waste of time – both for the author and for subsequent maintainers. It wastes the precious visual space at the top of the file with information that is better tracked elsewhere, and is easy to get out of date and become actively misleading.

If you have legal disclaimers or licensing info, it goes into a separate file. It does not need to infect every source code file. Your copyright should be part of this. People should be able to find it in your LICENSE file, not random source code.

Metadata such as authorship and dates is already maintained by your source control. There is no need to add a less-detailed, erroneous, and out-of-date version of the same info in the file itself.

I don’t believe there is any other data that everyone needs to put into all their source files. You may have some particular requirement to do so, but such things apply, by definition, only to you. They have no place in “general headers recommended for everyone”.

The answers above are really complete, but if you want a quick and dirty header to copy’n paste, use this:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Module documentation goes here
   and here
   and ...
"""

Why this is a good one:

• The first line is for *nix users. It will choose the Python interpreter in the user path, so will automatically choose the user preferred interpreter.
• The second one is the file encoding. Nowadays every file must have a encoding associated. UTF-8 will work everywhere. Just legacy projects would use other encoding.
• And a very simple documentation. It can fill multiple lines.

See also: https://www.python.org/dev/peps/pep-0263/

If you just write a class in each file, you don’t even need the documentation (it would go inside the class doc).

What I use in some project is this line in the first line for Linux machines:

# -*- coding: utf-8 -*-

As a DOC & Author credit, I like simple string in multiline. Here an example from Example Google Style Python Docstrings

# -*- coding: utf-8 -*-
"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:
   http://google.github.io/styleguide/pyguide.html

"""

Also can be nice to add:

        """
        @Author: ...
        @Date: ....
        @Credit: ...
        @Links: ...
        """

Additional Formats

• Meta-information markup | devguide

  """

        :mod:`parrot` -- Dead parrot access
        ===================================
  
        .. module:: parrot
           :platform: Unix, Windows
           :synopsis: Analyze and reanimate dead parrots.
        .. moduleauthor:: Eric Cleese <[email protected]>
        .. moduleauthor:: John Idle <[email protected]>
    """
  

• /common-header-python

        #!/usr/bin/env python3  Line 1
        # -*- coding: utf-8 -*- Line 2
        #----------------------------------------------------------------------------
        # Created By  : name_of_the_creator   Line 3
        # Created Date: date/month/time ..etc
        # version ='1.0'
        # ---------------------------------------------------------------------------
  

Also I report similarly to other answers

__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
__copyright__ = "Copyright 2007, The Cogent Project"
__credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
                    "Matthew Wakefield"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Rob Knight"
__email__ = "[email protected]"
__status__ = "Production"