SmithSamuelM
commented
3 years ago Python Style Guide
The Python PEPs on style have many options or allowed variants. The purpose of this document is to select a single preferred style in every case. In general this guide follows PEP-8 but specifies styles where PEP-8 is silent and varies from PEP-8 in a couple of places namely camelCase versus underscore_case
Indentation 4 spaces (detab ie no tabs convert tabs to spaces)
Naming conventions: alllowercase ALLUPPERCASE mixedCase lowerCamelCase CapitalCamelCase UpperCamelCase lower_case_with_underscores UPPER_CASE_WITH_UNDERSCORES Capitalized_With_Underscores lowercasenounderscores LeadingUnderscoreUpperCamelCase leadingUnderscoreLowerCamelCase
Rules:
Python Standard Library methods and attributes are small case with underscores. startswith()
Python builtins are small case no underscores setattr()
Spaces between methods and top level functions: two 2
Spaces between Class Definitions: two 2
DocStrings: Triple double quotes. """ """ """If one line doc string then may be all on one line""" """ If more than one line doc string then linefeed and start even with first string such as this string. Embedded strings use 'single quotes'. """
Format for code documentation in the the Google flavor of sphinx.ext.napolean format. See https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html and https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google
Napoleon supports two styles of docstrings: Google and NumPy. The main difference between the two styles is that Google uses indentation to separate sections, whereas NumPy uses underlines.
Google style:
def func(arg1, arg2): """Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return TrueAcronyms: When using underscores acronyms should be all uppercase if start uppercase or all lowercase if start lowercase http_send Send_HTTP
When using CapCamelCase or mixedCase the acronyms should be treated as words httpSend sendHttp
Local Variables and function parameters: lowerCamelCase
Any name that conflicts with python reserved word: add trailing underscore: Examples: id, file, Bork_
Module Names: all lower case. End name in 'ing' so when doing namespace know that first ref is module not class such as, behaving, clustering, functioning
Package Names: all lower case. Pithy and short but evocative
Class Names:
CapCamelCase
Examples: Person BigDogs
Exception Classes: CapCamelCase Example: StandardMuxError
Public Class Attributes, Class Methods, Static Methods: CapCamelCase Example: TotalInstances Storage
Private Class Attributes, Class Methods, Static Methods: leading underscore CapCamelCase, methods verbs, sequences plural nouns Example: _TotalInstances _Storage __Entries
Very Private Class Attributes, Class Methods, Static Methods (mangled with class name): leading double underscore CapCamelCase, methods verbs, sequences plural nouns Example: TotalInstances Storage __Entries
Public Instance Methods and Attributes:
lowerCamelCase, Methods should be verbs, sequences should be plural nouns
Examples: getName setStyle, display, first, last, itemCount, entities, books, data
Public Module Level Methods and Attributes: lowerCamelCase, Methods should be verbs, sequences should be plural nouns Examples: getName setStyle, display, first, last, itemCount, entities, books, data
Private Instance and Attributes (not exported with from import *):
leading underscore with lowerCamelCase, Methods should be verbs, sequences plural nouns
Examples: _getScore _setInternal _lastName _count _entries
Private Module Level Methods and Attributes (not exported by from import *): _underscoreLowerCamelCase Examples: _dirtyBit
Very Private Instance Methods or Attributes (mangled with class name): double leading underscore with lowerCamelCase, methods verbs, sequences plural nouns Examples: getMyName displayMoney creature secretData __entries
Constants Module Level:
UPPER_CASE_WITH_UNDERSCORES
not meant to be changed should be numbers or strings
Examples: MY_CONSTANT
Dynamic Global Variables (not Constants) Module Level: These are reserved for module level globals that may be changed in multiple places intentionally. Usually this is bad practice so special syntax is used to indicate such practice only when necessary. Capitalized_With_Underscores Examples: Bad_Practice REO_Lat_Lon_NE
Now that we are moving toward production, its time to clean up the python syntax and make the code docs strings compatible with the Sphinx (readthedocs) auto code documentation.
By reference hio uses the sphinx compatible docs strings. Keripy does not everywhere. some places have been updated others not. Many functions and methods have no doc string at all. There are other pythonic issues to address and some consistency issues with naming conventions.
Also part of this effort would be to use python type hints in call signatures. Eventually this would not only make the documentation cleaner but also enable us to use mypy to do hint type checking as part of unit testing.