This document gives coding conventions for the Python code comprisingthe standard library in the main Python distribution. Please see thecompanion informational PEP describingstyle guidelines for the C codein the C implementation of Python.
This document andPEP 257 (Docstring Conventions) were adapted fromGuido’s original Python Style Guide essay, with some additions fromBarry’s style guide[2].
This style guide evolves over time as additional conventions areidentified and past conventions are rendered obsolete by changes inthe language itself.
Many projects have their own coding style guidelines. In the event of anyconflicts, such project-specific guides take precedence for that project.
One of Guido’s key insights is that code is read much more often thanit is written. The guidelines provided here are intended to improvethe readability of code and make it consistent across the widespectrum of Python code. AsPEP 20 says, “Readability counts”.
A style guide is about consistency. Consistency with this style guideis important. Consistency within a project is more important.Consistency within one module or function is the most important.
However, know when to be inconsistent – sometimes style guiderecommendations just aren’t applicable. When in doubt, use your bestjudgment. Look at other examples and decide what looks best. Anddon’t hesitate to ask!
In particular: do not break backwards compatibility just to comply withthis PEP!
Some other good reasons to ignore a particular guideline:
Use 4 spaces per indentation level.
Continuation lines should align wrapped elements either verticallyusing Python’s implicit line joining inside parentheses, brackets andbraces, or using ahanging indent[1]. When using a hangingindent the following should be considered; there should be noarguments on the first line and further indentation should be used toclearly distinguish itself as a continuation line:
# Correct:# Aligned with opening delimiter.foo=long_function_name(var_one,var_two,var_three,var_four)# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.deflong_function_name(var_one,var_two,var_three,var_four):print(var_one)# Hanging indents should add a level.foo=long_function_name(var_one,var_two,var_three,var_four)
# Wrong:# Arguments on first line forbidden when not using vertical alignment.foo=long_function_name(var_one,var_two,var_three,var_four)# Further indentation required as indentation is not distinguishable.deflong_function_name(var_one,var_two,var_three,var_four):print(var_one)
The 4-space rule is optional for continuation lines.
Optional:
# Hanging indents *may* be indented to other than 4 spaces.foo=long_function_name(var_one,var_two,var_three,var_four)
When the conditional part of anif-statement is long enough to requirethat it be written across multiple lines, it’s worth noting that thecombination of a two character keyword (i.e.if), plus a single space,plus an opening parenthesis creates a natural 4-space indent for thesubsequent lines of the multiline conditional. This can produce a visualconflict with the indented suite of code nested inside theif-statement,which would also naturally be indented to 4 spaces. This PEP takes noexplicit position on how (or whether) to further visually distinguish suchconditional lines from the nested suite inside theif-statement.Acceptable options in this situation include, but are not limited to:
# No extra indentation.if(this_is_one_thingandthat_is_another_thing):do_something()# Add a comment, which will provide some distinction in editors# supporting syntax highlighting.if(this_is_one_thingandthat_is_another_thing):# Since both conditions are true, we can frobnicate.do_something()# Add some extra indentation on the conditional continuation line.if(this_is_one_thingandthat_is_another_thing):do_something()
(Also see the discussion of whether to break before or after binaryoperators below.)
The closing brace/bracket/parenthesis on multiline constructs mayeither line up under the first non-whitespace character of the lastline of list, as in:
my_list=[1,2,3,4,5,6,]result=some_function_that_takes_arguments('a','b','c','d','e','f',)
or it may be lined up under the first character of the line thatstarts the multiline construct, as in:
my_list=[1,2,3,4,5,6,]result=some_function_that_takes_arguments('a','b','c','d','e','f',)
Spaces are the preferred indentation method.
Tabs should be used solely to remain consistent with code that isalready indented with tabs.
Python disallows mixing tabs and spaces for indentation.
Limit all lines to a maximum of 79 characters.
For flowing long blocks of text with fewer structural restrictions(docstrings or comments), the line length should be limited to 72characters.
Limiting the required editor window width makes it possible to haveseveral files open side by side, and works well when using codereview tools that present the two versions in adjacent columns.
The default wrapping in most tools disrupts the visual structure of thecode, making it more difficult to understand. The limits are chosen toavoid wrapping in editors with the window width set to 80, evenif the tool places a marker glyph in the final column when wrappinglines. Some web based tools may not offer dynamic line wrapping at all.
Some teams strongly prefer a longer line length. For code maintainedexclusively or primarily by a team that can reach agreement on thisissue, it is okay to increase the line length limit up to 99 characters,provided that comments and docstrings are still wrapped at 72characters.
The Python standard library is conservative and requires limitinglines to 79 characters (and docstrings/comments to 72).
The preferred way of wrapping long lines is by using Python’s impliedline continuation inside parentheses, brackets and braces. Long linescan be broken over multiple lines by wrapping expressions inparentheses. These should be used in preference to using a backslashfor line continuation.
Backslashes may still be appropriate at times. For example, long,multiplewith-statements could not use implicit continuationbefore Python 3.10, so backslashes were acceptable for that case:
withopen('/path/to/some/file/you/want/to/read')asfile_1, \open('/path/to/some/file/being/written','w')asfile_2:file_2.write(file_1.read())
(See the previous discussion onmultiline if-statements for furtherthoughts on the indentation of such multilinewith-statements.)
Another such case is withassert statements.
Make sure to indent the continued line appropriately.
For decades the recommended style was to break after binary operators.But this can hurt readability in two ways: the operators tend to getscattered across different columns on the screen, and each operator ismoved away from its operand and onto the previous line. Here, the eyehas to do extra work to tell which items are added and which aresubtracted:
# Wrong:# operators sit far away from their operandsincome=(gross_wages+taxable_interest+(dividends-qualified_dividends)-ira_deduction-student_loan_interest)
To solve this readability problem, mathematicians and their publishersfollow the opposite convention. Donald Knuth explains the traditionalrule in hisComputers and Typesetting series: “Although formulaswithin a paragraph always break after binary operations and relations,displayed formulas always break before binary operations”[3].
Following the tradition from mathematics usually results in morereadable code:
# Correct:# easy to match operators with operandsincome=(gross_wages+taxable_interest+(dividends-qualified_dividends)-ira_deduction-student_loan_interest)
In Python code, it is permissible to break before or after a binaryoperator, as long as the convention is consistent locally. For newcode Knuth’s style is suggested.
Surround top-level function and class definitions with two blanklines.
Method definitions inside a class are surrounded by a single blankline.
Extra blank lines may be used (sparingly) to separate groups ofrelated functions. Blank lines may be omitted between a bunch ofrelated one-liners (e.g. a set of dummy implementations).
Use blank lines in functions, sparingly, to indicate logical sections.
Python accepts the control-L (i.e. ^L) form feed character aswhitespace; many tools treat these characters as page separators, soyou may use them to separate pages of related sections of your file.Note, some editors and web-based code viewers may not recognizecontrol-L as a form feed and will show another glyph in its place.
Code in the core Python distribution should always use UTF-8, and should nothave an encoding declaration.
In the standard library, non-UTF-8 encodings should be used only fortest purposes. Use non-ASCII characters sparingly, preferably only todenote places and human names. If using non-ASCII characters as data,avoid noisy Unicode characters like z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ and byte ordermarks.
All identifiers in the Python standard library MUST use ASCII-onlyidentifiers, and SHOULD use English words wherever feasible (in manycases, abbreviations and technical terms are used which aren’tEnglish).
Open source projects with a global audience are encouraged to adopt asimilar policy.
# Correct:importosimportsys
# Wrong:importsys,os
It’s okay to say this though:
# Correct:fromsubprocessimportPopen,PIPE
Imports should be grouped in the following order:
You should put a blank line between each group of imports.
sys.path):importmypkg.siblingfrommypkgimportsiblingfrommypkg.siblingimportexample
However, explicit relative imports are an acceptable alternative toabsolute imports, especially when dealing with complex package layoutswhere using absolute imports would be unnecessarily verbose:
from.importsiblingfrom.siblingimportexample
Standard library code should avoid complex package layouts and alwaysuse absolute imports.
frommyclassimportMyClassfromfoo.bar.yourclassimportYourClass
If this spelling causes local name clashes, then spell them explicitly:
importmyclassimportfoo.bar.yourclass
and usemyclass.MyClass andfoo.bar.yourclass.YourClass.
from<module>import*) should be avoided, asthey make it unclear which names are present in the namespace,confusing both readers and many automated tools. There is onedefensible use case for a wildcard import, which is to republish aninternal interface as part of a public API (for example, overwritinga pure Python implementation of an interface with the definitionsfrom an optional accelerator module and exactly which definitionswill be overwritten isn’t known in advance).When republishing names this way, the guidelines below regardingpublic and internal interfaces still apply.
Module level “dunders” (i.e. names with two leading and two trailingunderscores) such as__all__,__author__,__version__,etc. should be placed after the module docstring but before any importstatementsexceptfrom__future__ imports. Python mandates thatfuture-imports must appear in the module before any other code exceptdocstrings:
"""This is the example module.This module does stuff."""from__future__importbarry_as_FLUFL__all__=['a','b','c']__version__='0.1'__author__='Cardinal Biggles'importosimportsys
In Python, single-quoted strings and double-quoted strings are thesame. This PEP does not make a recommendation for this. Pick a ruleand stick to it. When a string contains single or double quotecharacters, however, use the other one to avoid backslashes in thestring. It improves readability.
For triple-quoted strings, always use double quote characters to beconsistent with the docstring convention inPEP 257.
Avoid extraneous whitespace in the following situations:
# Correct:spam(ham[1],{eggs:2})
# Wrong:spam(ham[1],{eggs:2})
# Correct:foo=(0,)
# Wrong:bar=(0,)
# Correct:ifx==4:print(x,y);x,y=y,x
# Wrong:ifx==4:print(x,y);x,y=y,x
# Correct:ham[1:9],ham[1:9:3],ham[:9:3],ham[1::3],ham[1:9:]ham[lower:upper],ham[lower:upper:],ham[lower::step]ham[lower+offset:upper+offset]ham[:upper_fn(x):step_fn(x)],ham[::step_fn(x)]ham[lower+offset:upper+offset]
# Wrong:ham[lower+offset:upper+offset]ham[1:9],ham[1:9],ham[1:9:3]ham[lower::step]ham[:upper]
# Correct:spam(1)
# Wrong:spam(1)
# Correct:dct['key']=lst[index]
# Wrong:dct['key']=lst[index]
# Correct:x=1y=2long_variable=3
# Wrong:x=1y=2long_variable=3
=), augmented assignment (+=,-=etc.), comparisons (==,<,>,!=,<>,<=,>=,in,notin,is,isnot), Booleans (and,or,not).# Correct:i=i+1submitted+=1x=x*2-1hypot2=x*x+y*yc=(a+b)*(a-b)
# Wrong:i=i+1submitted+=1x=x*2-1hypot2=x*x+y*yc=(a+b)*(a-b)
-> arrow if present. (SeeFunction Annotations below for more about function annotations.):# Correct:defmunge(input:AnyStr):...defmunge()->PosInt:...
# Wrong:defmunge(input:AnyStr):...defmunge()->PosInt:...
= sign when used to indicate akeyword argument, or when used to indicate a default value for anunannotated function parameter:# Correct:defcomplex(real,imag=0.0):returnmagic(r=real,i=imag)
# Wrong:defcomplex(real,imag=0.0):returnmagic(r=real,i=imag)
When combining an argument annotation with a default value, however, do usespaces around the= sign:
# Correct:defmunge(sep:AnyStr=None):...defmunge(input:AnyStr,sep:AnyStr=None,limit=1000):...
# Wrong:defmunge(input:AnyStr=None):...defmunge(input:AnyStr,limit=1000):...
# Correct:iffoo=='blah':do_blah_thing()do_one()do_two()do_three()
Rather not:
# Wrong:iffoo=='blah':do_blah_thing()do_one();do_two();do_three()
Rather not:
# Wrong:iffoo=='blah':do_blah_thing()forxinlst:total+=xwhilet<10:t=delay()
Definitely not:
# Wrong:iffoo=='blah':do_blah_thing()else:do_non_blah_thing()try:something()finally:cleanup()do_one();do_two();do_three(long,argument,list,like,this)iffoo=='blah':one();two();three()
Trailing commas are usually optional, except they are mandatory whenmaking a tuple of one element. For clarity, it is recommended tosurround the latter in (technically redundant) parentheses:
# Correct:FILES=('setup.cfg',)
# Wrong:FILES='setup.cfg',
When trailing commas are redundant, they are often helpful when aversion control system is used, when a list of values, arguments orimported items is expected to be extended over time. The pattern isto put each value (etc.) on a line by itself, always adding a trailingcomma, and add the close parenthesis/bracket/brace on the next line.However it does not make sense to have a trailing comma on the sameline as the closing delimiter (except in the above case of singletontuples):
# Correct:FILES=['setup.cfg','tox.ini',]initialize(FILES,error=True,)
# Wrong:FILES=['setup.cfg','tox.ini',]initialize(FILES,error=True,)
Comments that contradict the code are worse than no comments. Alwaysmake a priority of keeping the comments up-to-date when the codechanges!
Comments should be complete sentences. The first word should becapitalized, unless it is an identifier that begins with a lower caseletter (never alter the case of identifiers!).
Block comments generally consist of one or more paragraphs built out ofcomplete sentences, with each sentence ending in a period.
You should use one or two spaces after a sentence-ending period inmulti-sentence comments, except after the final sentence.
Ensure that your comments are clear and easily understandable to otherspeakers of the language you are writing in.
Python coders from non-English speaking countries: please write yourcomments in English, unless you are 120% sure that the code will neverbe read by people who don’t speak your language.
Block comments generally apply to some (or all) code that followsthem, and are indented to the same level as that code. Each line of ablock comment starts with a# and a single space (unless it isindented text inside the comment).
Paragraphs inside a block comment are separated by a line containing asingle#.
Use inline comments sparingly.
An inline comment is a comment on the same line as a statement.Inline comments should be separated by at least two spaces from thestatement. They should start with a # and a single space.
Inline comments are unnecessary and in fact distracting if they statethe obvious. Don’t do this:
x=x+1# Increment x
But sometimes, this is useful:
x=x+1# Compensate for border
Conventions for writing good documentation strings(a.k.a. “docstrings”) are immortalized inPEP 257.
def line.""" that ends a multiline docstring should beon a line by itself:"""Return a foobangOptional plotz says to frobnicate the bizbaz first."""
""" onthe same line:"""Return an ex-parrot."""The naming conventions of Python’s library are a bit of a mess, sowe’ll never get this completely consistent – nevertheless, here arethe currently recommended naming standards. New modules and packages(including third party frameworks) should be written to thesestandards, but where an existing library has a different style,internal consistency is preferred.
Names that are visible to the user as public parts of the API shouldfollow conventions that reflect usage rather than implementation.
There are a lot of different naming styles. It helps to be able torecognize what naming style is being used, independently from whatthey are used for.
The following naming styles are commonly distinguished:
b (single lowercase letter)B (single uppercase letter)lowercaselower_case_with_underscoresUPPERCASEUPPER_CASE_WITH_UNDERSCORESCapitalizedWords (or CapWords, or CamelCase – so named becauseof the bumpy look of its letters[4]). This is also sometimes knownas StudlyCaps.Note: When using acronyms in CapWords, capitalize all theletters of the acronym. Thus HTTPServerError is better thanHttpServerError.
mixedCase (differs from CapitalizedWords by initial lowercasecharacter!)Capitalized_Words_With_Underscores (ugly!)There’s also the style of using a short unique prefix to group relatednames together. This is not used much in Python, but it is mentionedfor completeness. For example, theos.stat() function returns atuple whose items traditionally have names likest_mode,st_size,st_mtime and so on. (This is done to emphasize thecorrespondence with the fields of the POSIX system call struct, whichhelps programmers familiar with that.)
The X11 library uses a leading X for all its public functions. InPython, this style is generally deemed unnecessary because attributeand method names are prefixed with an object, and function names areprefixed with a module name.
In addition, the following special forms using leading or trailingunderscores are recognized (these can generally be combined with anycase convention):
_single_leading_underscore: weak “internal use” indicator.E.g.fromMimport* does not import objects whose names startwith an underscore.single_trailing_underscore_: used by convention to avoidconflicts with Python keyword, e.g. :tkinter.Toplevel(master,class_='ClassName')
__double_leading_underscore: when naming a class attribute,invokes name mangling (inside class FooBar,__boo becomes_FooBar__boo; see below).__double_leading_and_trailing_underscore__: “magic” objects orattributes that live in user-controlled namespaces.E.g.__init__,__import__ or__file__. Never inventsuch names; only use them as documented.Never use the characters ‘l’ (lowercase letter el), ‘O’ (uppercaseletter oh), or ‘I’ (uppercase letter eye) as single character variablenames.
In some fonts, these characters are indistinguishable from thenumerals one and zero. When tempted to use ‘l’, use ‘L’ instead.
Identifiers used in the standard library must be ASCII compatibleas described in thepolicy sectionofPEP 3131.
Modules should have short, all-lowercase names. Underscores can beused in the module name if it improves readability. Python packagesshould also have short, all-lowercase names, although the use ofunderscores is discouraged.
When an extension module written in C or C++ has an accompanyingPython module that provides a higher level (e.g. more object oriented)interface, the C/C++ module has a leading underscore(e.g._socket).
Class names should normally use the CapWords convention.
The naming convention for functions may be used instead in cases wherethe interface is documented and used primarily as a callable.
Note that there is a separate convention for builtin names: most builtinnames are single words (or two words run together), with the CapWordsconvention used only for exception names and builtin constants.
Names of type variables introduced inPEP 484 should normally use CapWordspreferring short names:T,AnyStr,Num. It is recommended to addsuffixes_co or_contra to the variables used to declare covariantor contravariant behavior correspondingly:
fromtypingimportTypeVarVT_co=TypeVar('VT_co',covariant=True)KT_contra=TypeVar('KT_contra',contravariant=True)
Because exceptions should be classes, the class naming conventionapplies here. However, you should use the suffix “Error” on yourexception names (if the exception actually is an error).
(Let’s hope that these variables are meant for use inside one moduleonly.) The conventions are about the same as those for functions.
Modules that are designed for use viafromMimport* should usethe__all__ mechanism to prevent exporting globals, or use theolder convention of prefixing such globals with an underscore (whichyou might want to do to indicate these globals are “modulenon-public”).
Function names should be lowercase, with words separated byunderscores as necessary to improve readability.
Variable names follow the same convention as function names.
mixedCase is allowed only in contexts where that’s already theprevailing style (e.g. threading.py), to retain backwardscompatibility.
Always useself for the first argument to instance methods.
Always usecls for the first argument to class methods.
If a function argument’s name clashes with a reserved keyword, it isgenerally better to append a single trailing underscore rather thanuse an abbreviation or spelling corruption. Thusclass_ is betterthanclss. (Perhaps better is to avoid such clashes by using asynonym.)
Use the function naming rules: lowercase with words separated byunderscores as necessary to improve readability.
Use one leading underscore only for non-public methods and instancevariables.
To avoid name clashes with subclasses, use two leading underscores toinvoke Python’s name mangling rules.
Python mangles these names with the class name: if class Foo has anattribute named__a, it cannot be accessed byFoo.__a. (Aninsistent user could still gain access by callingFoo._Foo__a.)Generally, double leading underscores should be used only to avoidname conflicts with attributes in classes designed to be subclassed.
Note: there is some controversy about the use of __names (see below).
Constants are usually defined on a module level and written in allcapital letters with underscores separating words. Examples includeMAX_OVERFLOW andTOTAL.
Always decide whether a class’s methods and instance variables(collectively: “attributes”) should be public or non-public. If indoubt, choose non-public; it’s easier to make it public later than tomake a public attribute non-public.
Public attributes are those that you expect unrelated clients of yourclass to use, with your commitment to avoid backwards incompatiblechanges. Non-public attributes are those that are not intended to beused by third parties; you make no guarantees that non-publicattributes won’t change or even be removed.
We don’t use the term “private” here, since no attribute is reallyprivate in Python (without a generally unnecessary amount of work).
Another category of attributes are those that are part of the“subclass API” (often called “protected” in other languages). Someclasses are designed to be inherited from, either to extend or modifyaspects of the class’s behavior. When designing such a class, takecare to make explicit decisions about which attributes are public,which are part of the subclass API, and which are truly only to beused by your base class.
With this in mind, here are the Pythonic guidelines:
Note 1: See the argument name recommendation above for class methods.
Note 1: Try to keep the functional behavior side-effect free,although side-effects such as caching are generally fine.
Note 2: Avoid using properties for computationally expensiveoperations; the attribute notation makes the caller believe thataccess is (relatively) cheap.
Note 1: Note that only the simple class name is used in the mangledname, so if a subclass chooses both the same class name and attributename, you can still get name collisions.
Note 2: Name mangling can make certain uses, such as debugging and__getattr__(), less convenient. However the name manglingalgorithm is well documented and easy to perform manually.
Note 3: Not everyone likes name mangling. Try to balance theneed to avoid accidental name clashes with potential use byadvanced callers.
Any backwards compatibility guarantees apply only to public interfaces.Accordingly, it is important that users be able to clearly distinguishbetween public and internal interfaces.
Documented interfaces are considered public, unless the documentationexplicitly declares them to be provisional or internal interfaces exemptfrom the usual backwards compatibility guarantees. All undocumentedinterfaces should be assumed to be internal.
To better support introspection, modules should explicitly declare thenames in their public API using the__all__ attribute. Setting__all__ to an empty list indicates that the module has no public API.
Even with__all__ set appropriately, internal interfaces (packages,modules, classes, functions, attributes or other names) should still beprefixed with a single leading underscore.
An interface is also considered internal if any containing namespace(package, module or class) is considered internal.
Imported names should always be considered an implementation detail.Other modules must not rely on indirect access to such imported namesunless they are an explicitly documented part of the containing module’sAPI, such asos.path or a package’s__init__ module that exposesfunctionality from submodules.
For example, do not rely on CPython’s efficient implementation ofin-place string concatenation for statements in the forma+=bora=a+b. This optimization is fragile even in CPython (itonly works for some types) and isn’t present at all in implementationsthat don’t use refcounting. In performance sensitive parts of thelibrary, the''.join() form should be used instead. This willensure that concatenation occurs in linear time across variousimplementations.
is orisnot, never the equality operators.Also, beware of writingifx when you really meanifxisnotNone – e.g. when testing whether a variable or argument thatdefaults to None was set to some other value. The other value mighthave a type (such as a container) that could be false in a booleancontext!
isnot operator rather thannot...is. While bothexpressions are functionally identical, the former is more readableand preferred:# Correct:iffooisnotNone:
# Wrong:ifnotfooisNone:
__eq__,__ne__,__lt__,__le__,__gt__,__ge__) rather than relyingon other code to only exercise a particular comparison.To minimize the effort involved, thefunctools.total_ordering()decorator provides a tool to generate missing comparison methods.
PEP 207 indicates that reflexivity rulesare assumed by Python.Thus, the interpreter may swapy>x withx<y,y>=xwithx<=y, and may swap the arguments ofx==y andx!=y. Thesort() andmin() operations are guaranteed to usethe< operator and themax() function uses the>operator. However, it is best to implement all six operations sothat confusion doesn’t arise in other contexts.
# Correct:deff(x):return2*x
# Wrong:f=lambdax:2*x
The first form means that the name of the resulting function object isspecifically ‘f’ instead of the generic ‘<lambda>’. This is moreuseful for tracebacks and string representations in general. The useof the assignment statement eliminates the sole benefit a lambdaexpression can offer over an explicit def statement (i.e. that it canbe embedded inside a larger expression)
Exception rather thanBaseException.Direct inheritance fromBaseException is reserved for exceptionswhere catching them is almost always the wrong thing to do.Design exception hierarchies based on the distinctions that codecatching the exceptions is likely to need, rather than the locationswhere the exceptions are raised. Aim to answer the question“What went wrong?” programmatically, rather than only stating that“A problem occurred” (seePEP 3151 for an example of this lesson beinglearned for the builtin exception hierarchy)
Class naming conventions apply here, although you should add thesuffix “Error” to your exception classes if the exception is anerror. Non-error exceptions that are used for non-local flow controlor other forms of signaling need no special suffix.
raiseXfromYshould be used to indicate explicit replacement without losing theoriginal traceback.When deliberately replacing an inner exception (usingraiseXfromNone), ensure that relevant details are transferred to the newexception (such as preserving the attribute name when convertingKeyError to AttributeError, or embedding the text of the originalexception in the new exception message).
except: clause:try:importplatform_specific_moduleexceptImportError:platform_specific_module=None
A bareexcept: clause will catch SystemExit andKeyboardInterrupt exceptions, making it harder to interrupt aprogram with Control-C, and can disguise other problems. If youwant to catch all exceptions that signal program errors, useexceptException: (bare except is equivalent toexceptBaseException:).
A good rule of thumb is to limit use of bare ‘except’ clauses to twocases:
raise.try...finallycan be a better way to handle this case.errnovalues.try clauseto the absolute minimum amount of code necessary. Again, thisavoids masking bugs:# Correct:try:value=collection[key]exceptKeyError:returnkey_not_found(key)else:returnhandle_value(value)
# Wrong:try:# Too broad!returnhandle_value(collection[key])exceptKeyError:# Will also catch KeyError raised by handle_value()returnkey_not_found(key)
with statement to ensure it is cleaned up promptly and reliablyafter use. A try/finally statement is also acceptable.# Correct:withconn.begin_transaction():do_stuff_in_transaction(conn)
# Wrong:withconn:do_stuff_in_transaction(conn)
The latter example doesn’t provide any information to indicate thatthe__enter__ and__exit__ methods are doing something otherthan closing the connection after a transaction. Being explicit isimportant in this case.
returnNone, and an explicit return statement should be present at theend of the function (if reachable):# Correct:deffoo(x):ifx>=0:returnmath.sqrt(x)else:returnNonedefbar(x):ifx<0:returnNonereturnmath.sqrt(x)
# Wrong:deffoo(x):ifx>=0:returnmath.sqrt(x)defbar(x):ifx<0:returnreturnmath.sqrt(x)
''.startswith() and''.endswith() instead of stringslicing to check for prefixes or suffixes.startswith() and endswith() are cleaner and less error prone:
# Correct:iffoo.startswith('bar'):
# Wrong:iffoo[:3]=='bar':
# Correct:ifisinstance(obj,int):
# Wrong:iftype(obj)istype(1):
# Correct:ifnotseq:ifseq:
# Wrong:iflen(seq):ifnotlen(seq):
==:# Correct:ifgreeting:
# Wrong:ifgreeting==True:
Worse:
# Wrong:ifgreetingisTrue:
return/break/continuewithin the finally suite of atry...finally, where the flow controlstatement would jump outside the finally suite, is discouraged. Thisis because such statements will implicitly cancel any active exceptionthat is propagating through the finally suite:# Wrong:deffoo():try:1/0finally:return42
With the acceptance ofPEP 484, the style rules for functionannotations have changed.
# type: ignorenear the top of the file; this tells type checkers to ignore allannotations. (More fine-grained ways of disabling complaints fromtype checkers can be found inPEP 484.)
PEP 526 introduced variable annotations. The style recommendations for them aresimilar to those on function annotations described above:
# Correct:code:intclassPoint:coords:Tuple[int,int]label:str='<unknown>'
# Wrong:code:int# No space after coloncode:int# Space before colonclassTest:result:int=0# No spaces around equality sign
Footnotes
This document has been placed in the public domain.
Source:https://github.com/python/peps/blob/main/peps/pep-0008.rst
Last modified:2025-02-01 07:28:42 GMT