What is the common header format of Python files

Question

I came across the following header format for Python source files in a document about Python coding guidelines      usr bin env python     Foobar py  Description of what foobar does        author           Barack Obama    copyright        Copyright 2009  Planet Earth    Is this the standard format of headers in the Python world  What other fields information can I put in the header  Python gurus share your guidelines for good Python source headers  -

User · Answer

I strongly favour minimal file headers  by which I mean just   The hashbang     line  if this is an executable script Module docstring Imports  grouped in the standard way  eg     import os      standard library   import sys    import requests    3rd party packages    from mypackage import      local source       mymodule        myothermodule       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  visual space  and is actively misleading  If you have legal disclaimers or licencing 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

User · Answer

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  lt encoding name gt        or  using formats recognized by popular editors            usr bin python         - - coding   lt encoding name gt  - -       or           usr bin python         vim  set fileencoding  lt encoding name gt

User · Answer

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

User · Answer

Its all metadata for the Foobar module  The first one is the docstring of the module  that is already explained in Peter s answer   How do I organize my modules  source files    Archive  The first line of each file shoud be    usr bin env python  This makes it possible to run the file as a script invoking the interpreter implicitly  e g  in a CGI context  Next should be the docstring with a description  If the description is long  the first line should be a short summary that makes sense on its own  separated from the rest by a newline  All code  including import statements  should follow the docstring  Otherwise  the docstring will not be recognized by the interpreter  and you will not have access to it in interactive sessions  i e  through obj   doc    or when generating documentation with automated tools  Import built-in modules first  followed by third-party modules  followed by any changes to the path and your own modules  Especially  additions to the path and names of your modules are likely to change rapidly  keeping them in one place makes them easier to find  Next should be authorship information  This information should follow this format    author      quot Rob Knight  Gavin Huttley  and Peter Maxwell quot    copyright      quot Copyright 2007  The Cogent Project quot    credits       quot Rob Knight quot    quot Peter Maxwell quot    quot Gavin Huttley quot                        quot Matthew Wakefield quot     license      quot GPL quot    version      quot 1 0 1 quot    maintainer      quot Rob Knight quot    email      quot rob spot colorado edu quot    status      quot Production quot   Status should typically be one of  quot Prototype quot    quot Development quot   or  quot Production quot     maintainer   should be the person who will fix bugs and make improvements if imported    credits   differs from   author   in that   credits   includes people who reported bug fixes  made suggestions  etc  but did not actually write the code   Here you have more information  listing   author      authors      contact      copyright      license      deprecated      date   and   version   as recognized metadata

[python] What is the common header format of Python files?

Examples related to python

Examples related to header

Examples related to comments