Imports should always be written at the top of the file, after any module comments and docstrings.
Imports should be divided according to what is being imported. There are generally three groups:
- Standard library imports (Python’s built-in modules)
- Related third party imports (modules that are installed and do not belong to the current application)
- Local application imports (modules that belong to the current application)
Each group of imports should be separated by a blank space.
- Use import statements for packages and modules only, not for individual classes or functions
- Use import x for importing packages and modules.
- Use from x import y where x is the package prefix and y is the module name with no prefix.
- Use from x import y as z if two modules named y are to be imported or if y is an inconveniently long name.
- Use import y as z only when z is a standard abbreviation (e.g., np for numpy).
- Use paranthesis for importing multiple modules from a package
from keras.layers import (Conv2D, MaxPooling2D, Flatten, Dense)
- Use absolute imports whenever possible
A single dot means that the module or package referenced is in the same directory as the current location. Two dots mean that it is in the parent directory of the current location—that is, the directory above. Three dots mean that it is in the grandparent directory, and so on. This will probably be familiar to you if you use a Unix-like operating system!
__init__.py
subpackage1/
__init__.py
moduleX.py
moduleY.py
subpackage2/
__init__.py
moduleZ.py
moduleA.py
Assuming that the current file is moduleX.py, following are correct usages of the new syntax:
from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo
from ...package import bar
from ...sys import path
Note that while that last case is legal, it is certainly discouraged ("insane" was the word Guido used).
Type | Naming Convention | Examples |
---|---|---|
Function | Use a lowercase word or words. Separate words by underscores to improve readability. | function , my_function |
Variable | Use a lowercase single letter, word, or words. Separate words with underscores to improve readability. | x , var , my_variable |
Class | Start each word with a capital letter. Do not separate words with underscores. This style is called camel case. | Model , MyClass |
Method | Use a lowercase word or words. Separate words with underscores to improve readability. | class_method , method |
Constant | Use an uppercase single letter, word, or words. Separate words with underscores to improve readability. | CONSTANT , MY_CONSTANT , MY_LONG_CONSTANT |
Module | Use a short, lowercase word or words. Separate words with underscores to improve readability. | module.py , my_module.py |
Package | Use a short, lowercase word or words. Do not separate words with underscores. | package , mypackage |
- Use 4 consecutive spaces to indicate indentation
- Prefer spaces over tabs
-
- Indent block comments to the same level as the code they describe.
- Start each line with a # followed by a single space.
- Separate paragraphs by a line containing a single #.
-
- Use them sparingly
The most important rules applying to docstrings are the following:
-
Surround docstrings with three double quotes on either side, as in
""" This is a docstring """
-
Write them for all public modules, functions, classes, and methods.
-
Put the """ that ends a multiline docstring on a line by itself
Their purpose is to provide your users with a brief overview of the object. At a bare minimum, a docstring should be a quick summary of whatever is it you’re describing and should be contained within a single line.
Multi-lined docstrings are used to further elaborate on the object beyond the summary. All multi-lined docstrings have the following parts:
- A one-line summary line
- A blank line proceeding the summary
- Any further elaboration for the docstring
- Another blank line
- Class Docstrings: Class and class methods
- Package and Module Docstrings: Package, modules, and functions
- Script Docstrings: Script and functions
-
Class docstrings should contain the following information:
- A brief summary of its purpose and behavior
- Any public methods, along with a brief description
- Any class properties (attributes)
- Anything related to the interface for subclassers, if the class is intended to be subclassed
The class constructor parameters should be documented within the __ init __ class method docstring. Individual methods should be documented using their individual docstrings. Class method docstrings should contain the following:
- A brief description of what the method is and what it’s used for
- Any arguments (both required and optional) that are passed including keyword arguments
- Label any arguments that are considered optional or have a default value
- Any side effects that occur when executing the method
- Any exceptions that are raised
- Any restrictions on when the method can be called
-
Package docstrings should be placed at the top of the package’s __ init__.py file. This docstring should list the modules and sub-packages that are exported by the package.
Module docstrings are similar to class docstrings. Instead of classes and class methods being documented, it’s now the module and any functions found within. Module docstrings are placed at the top of the file even before any imports. Module docstrings should include the following:
- A brief description of the module and its purpose
- A list of any classes, exception, functions, and any other objects exported by the module
The docstring for a module function should include the same items as a class method:
- A brief description of what the function is and what it’s used for
- Any arguments (both required and optional) that are passed including keyword arguments
- Label any arguments that are considered optional
- Any side effects that occur when executing the function
- Any exceptions that are raised
- Any restrictions on when the function can be called
I prefer Google's docstrings format
Ex:
"""
Gets and prints the spreadsheet's header columns
Parameters:
file_loc (str): The file location of the spreadsheet
print_cols (bool): A flag used to print the columns to the console
(default is False)
Returns:
list: a list of strings representing the header columns
"""