Skip to content

Add exemption to Python styleguide import for exposing classes in __init__.py and unify formatting of the Table of Contents #918

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

Add exemption to Python styleguide import for exposing classes in __init__.py and unify formatting of the Table of Contents #918

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 156 additions & 73 deletions pyguide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,79 +11,157 @@ See README.md for details.
<details markdown="1">
<summary>Table of Contents</summary>

- [1 Background](#s1-background)
- [2 Python Language Rules](#s2-python-language-rules)
* [2.1 Lint](#s2.1-lint)
* [2.2 Imports](#s2.2-imports)
* [2.3 Packages](#s2.3-packages)
* [2.4 Exceptions](#s2.4-exceptions)
* [2.5 Mutable Global State](#s2.5-global-variables)
* [2.6 Nested/Local/Inner Classes and Functions](#s2.6-nested)
* [2.7 Comprehensions & Generator Expressions](#s2.7-comprehensions)
* [2.8 Default Iterators and Operators](#s2.8-default-iterators-and-operators)
* [2.9 Generators](#s2.9-generators)
* [2.10 Lambda Functions](#s2.10-lambda-functions)
* [2.11 Conditional Expressions](#s2.11-conditional-expressions)
* [2.12 Default Argument Values](#s2.12-default-argument-values)
* [2.13 Properties](#s2.13-properties)
* [2.14 True/False Evaluations](#s2.14-truefalse-evaluations)
* [2.16 Lexical Scoping](#s2.16-lexical-scoping)
* [2.17 Function and Method Decorators](#s2.17-function-and-method-decorators)
* [2.18 Threading](#s2.18-threading)
* [2.19 Power Features](#s2.19-power-features)
* [2.20 Modern Python: from \_\_future\_\_ imports](#s2.20-modern-python)
* [2.21 Type Annotated Code](#s2.21-type-annotated-code)
- [3 Python Style Rules](#s3-python-style-rules)
* [3.1 Semicolons](#s3.1-semicolons)
* [3.2 Line length](#s3.2-line-length)
* [3.3 Parentheses](#s3.3-parentheses)
* [3.4 Indentation](#s3.4-indentation)
+ [3.4.1 Trailing commas in sequences of items?](#s3.4.1-trailing-commas)
* [3.5 Blank Lines](#s3.5-blank-lines)
* [3.6 Whitespace](#s3.6-whitespace)
* [3.7 Shebang Line](#s3.7-shebang-line)
* [3.8 Comments and Docstrings](#s3.8-comments-and-docstrings)
+ [3.8.1 Docstrings](#s3.8.1-comments-in-doc-strings)
+ [3.8.2 Modules](#s3.8.2-comments-in-modules)
+ [3.8.2.1 Test modules](#s3.8.2.1-test-modules)
+ [3.8.3 Functions and Methods](#s3.8.3-functions-and-methods)
+ [3.8.3.1 Overridden Methods](#s3.8.3.1-overridden-methods)
+ [3.8.4 Classes](#s3.8.4-comments-in-classes)
+ [3.8.5 Block and Inline Comments](#s3.8.5-block-and-inline-comments)
+ [3.8.6 Punctuation, Spelling, and Grammar](#s3.8.6-punctuation-spelling-and-grammar)
* [3.10 Strings](#s3.10-strings)
+ [3.10.1 Logging](#s3.10.1-logging)
+ [3.10.2 Error Messages](#s3.10.2-error-messages)
* [3.11 Files, Sockets, and similar Stateful Resources](#s3.11-files-sockets-closeables)
* [3.12 TODO Comments](#s3.12-todo-comments)
* [3.13 Imports formatting](#s3.13-imports-formatting)
* [3.14 Statements](#s3.14-statements)
* [3.15 Accessors](#s3.15-accessors)
* [3.16 Naming](#s3.16-naming)
+ [3.16.1 Names to Avoid](#s3.16.1-names-to-avoid)
+ [3.16.2 Naming Conventions](#s3.16.2-naming-conventions)
+ [3.16.3 File Naming](#s3.16.3-file-naming)
+ [3.16.4 Guidelines derived from Guido's Recommendations](#s3.16.4-guidelines-derived-from-guidos-recommendations)
* [3.17 Main](#s3.17-main)
* [3.18 Function length](#s3.18-function-length)
* [3.19 Type Annotations](#s3.19-type-annotations)
+ [3.19.1 General Rules](#s3.19.1-general-rules)
+ [3.19.2 Line Breaking](#s3.19.2-line-breaking)
+ [3.19.3 Forward Declarations](#s3.19.3-forward-declarations)
+ [3.19.4 Default Values](#s3.19.4-default-values)
+ [3.19.5 NoneType](#s3.19.5-nonetype)
+ [3.19.6 Type Aliases](#s3.19.6-type-aliases)
+ [3.19.7 Ignoring Types](#s3.19.7-ignoring-types)
+ [3.19.8 Typing Variables](#s3.19.8-typing-variables)
+ [3.19.9 Tuples vs Lists](#s3.19.9-tuples-vs-lists)
+ [3.19.10 Type variables](#s3.19.10-typevars)
+ [3.19.11 String types](#s3.19.11-string-types)
+ [3.19.12 Imports For Typing](#s3.19.12-imports-for-typing)
+ [3.19.13 Conditional Imports](#s3.19.13-conditional-imports)
+ [3.19.14 Circular Dependencies](#s3.19.14-circular-dependencies)
+ [3.19.15 Generics](#s3.19.15-generics)
+ [3.19.16 Build Dependencies](#s3.19.16-build-dependencies)
- [4 Parting Words](#4-parting-words)
- [Google Python Style Guide](#google-python-style-guide)
- [1 Background](#1-background)
- [2 Python Language Rules](#2-python-language-rules)
- [2.1 Lint](#21-lint)
- [2.1.1 Definition](#211-definition)
- [2.1.2 Pros](#212-pros)
- [2.1.3 Cons](#213-cons)
- [2.1.4 Decision](#214-decision)
- [2.2 Imports](#22-imports)
- [2.2.1 Definition](#221-definition)
- [2.2.2 Pros](#222-pros)
- [2.2.3 Cons](#223-cons)
- [2.2.4 Decision](#224-decision)
- [2.2.4.1 Exemptions](#2241-exemptions)
- [2.3 Packages](#23-packages)
- [2.3.1 Pros](#231-pros)
- [2.3.2 Cons](#232-cons)
- [2.3.3 Decision](#233-decision)
- [2.4 Exceptions](#24-exceptions)
- [2.4.1 Definition](#241-definition)
- [2.4.2 Pros](#242-pros)
- [2.4.3 Cons](#243-cons)
- [2.4.4 Decision](#244-decision)
- [2.5 Mutable Global State](#25-mutable-global-state)
- [2.5.1 Definition](#251-definition)
- [2.5.2 Pros](#252-pros)
- [2.5.3 Cons](#253-cons)
- [2.5.4 Decision](#254-decision)
- [2.6 Nested/Local/Inner Classes and Functions](#26-nestedlocalinner-classes-and-functions)
- [2.6.1 Definition](#261-definition)
- [2.6.2 Pros](#262-pros)
- [2.6.3 Cons](#263-cons)
- [2.6.4 Decision](#264-decision)
- [2.7 Comprehensions \& Generator Expressions](#27-comprehensions--generator-expressions)
- [2.7.1 Definition](#271-definition)
- [2.7.2 Pros](#272-pros)
- [2.7.3 Cons](#273-cons)
- [2.7.4 Decision](#274-decision)
- [2.8 Default Iterators and Operators](#28-default-iterators-and-operators)
- [2.8.1 Definition](#281-definition)
- [2.8.2 Pros](#282-pros)
- [2.8.3 Cons](#283-cons)
- [2.8.4 Decision](#284-decision)
- [2.9 Generators](#29-generators)
- [2.9.1 Definition](#291-definition)
- [2.9.2 Pros](#292-pros)
- [2.9.3 Cons](#293-cons)
- [2.9.4 Decision](#294-decision)
- [2.10 Lambda Functions](#210-lambda-functions)
- [2.10.1 Definition](#2101-definition)
- [2.10.2 Pros](#2102-pros)
- [2.10.3 Cons](#2103-cons)
- [2.10.4 Decision](#2104-decision)
- [2.11 Conditional Expressions](#211-conditional-expressions)
- [2.11.1 Definition](#2111-definition)
- [2.11.2 Pros](#2112-pros)
- [2.11.3 Cons](#2113-cons)
- [2.11.4 Decision](#2114-decision)
- [2.12 Default Argument Values](#212-default-argument-values)
- [2.12.1 Definition](#2121-definition)
- [2.12.2 Pros](#2122-pros)
- [2.12.3 Cons](#2123-cons)
- [2.12.4 Decision](#2124-decision)
- [2.13 Properties](#213-properties)
- [2.13.1 Definition](#2131-definition)
- [2.13.2 Pros](#2132-pros)
- [2.13.3 Cons](#2133-cons)
- [2.13.4 Decision](#2134-decision)
- [2.14 True/False Evaluations](#214-truefalse-evaluations)
- [2.14.1 Definition](#2141-definition)
- [2.14.2 Pros](#2142-pros)
- [2.14.3 Cons](#2143-cons)
- [2.14.4 Decision](#2144-decision)
- [2.16 Lexical Scoping](#216-lexical-scoping)
- [2.16.1 Definition](#2161-definition)
- [2.16.2 Pros](#2162-pros)
- [2.16.3 Cons](#2163-cons)
- [2.16.4 Decision](#2164-decision)
- [2.17 Function and Method Decorators](#217-function-and-method-decorators)
- [2.17.1 Definition](#2171-definition)
- [2.17.2 Pros](#2172-pros)
- [2.17.3 Cons](#2173-cons)
- [2.17.4 Decision](#2174-decision)
- [2.18 Threading](#218-threading)
- [2.19 Power Features](#219-power-features)
- [2.19.1 Definition](#2191-definition)
- [2.19.2 Pros](#2192-pros)
- [2.19.3 Cons](#2193-cons)
- [2.19.4 Decision](#2194-decision)
- [2.20 Modern Python: from \_\_future\_\_ imports](#220-modern-python-from-__future__-imports)
- [2.20.1 Definition](#2201-definition)
- [2.20.2 Pros](#2202-pros)
- [2.20.3 Cons](#2203-cons)
- [2.20.4 Decision](#2204-decision)
- [from \_\_future\_\_ imports](#from-__future__-imports)
- [2.21 Type Annotated Code](#221-type-annotated-code)
- [2.21.1 Definition](#2211-definition)
- [2.21.2 Pros](#2212-pros)
- [2.21.3 Cons](#2213-cons)
- [2.21.4 Decision](#2214-decision)
- [3 Python Style Rules](#3-python-style-rules)
- [3.1 Semicolons](#31-semicolons)
- [3.2 Line length](#32-line-length)
- [3.3 Parentheses](#33-parentheses)
- [3.4 Indentation](#34-indentation)
- [3.4.1 Trailing commas in sequences of items?](#341-trailing-commas-in-sequences-of-items)
- [3.5 Blank Lines](#35-blank-lines)
- [3.6 Whitespace](#36-whitespace)
- [3.7 Shebang Line](#37-shebang-line)
- [3.8 Comments and Docstrings](#38-comments-and-docstrings)
- [3.8.1 Docstrings](#381-docstrings)
- [3.8.2 Modules](#382-modules)
- [3.8.2.1 Test modules](#3821-test-modules)
- [3.8.3 Functions and Methods](#383-functions-and-methods)
- [3.8.3.1 Overridden Methods](#3831-overridden-methods)
- [3.8.4 Classes](#384-classes)
- [3.8.5 Block and Inline Comments](#385-block-and-inline-comments)
- [3.8.6 Punctuation, Spelling, and Grammar](#386-punctuation-spelling-and-grammar)
- [3.10 Strings](#310-strings)
- [3.10.1 Logging](#3101-logging)
- [3.10.2 Error Messages](#3102-error-messages)
- [3.11 Files, Sockets, and similar Stateful Resources](#311-files-sockets-and-similar-stateful-resources)
- [3.12 TODO Comments](#312-todo-comments)
- [3.13 Imports formatting](#313-imports-formatting)
- [3.14 Statements](#314-statements)
- [3.15 Getters and Setters](#315-getters-and-setters)
- [3.16 Naming](#316-naming)
- [3.16.1 Names to Avoid](#3161-names-to-avoid)
- [3.16.2 Naming Conventions](#3162-naming-conventions)
- [3.16.3 File Naming](#3163-file-naming)
- [3.16.4 Guidelines derived from Guido's Recommendations](#3164-guidelines-derived-from-guidos-recommendations)
- [3.16.5 Mathematical Notation](#3165-mathematical-notation)
- [3.17 Main](#317-main)
- [3.18 Function length](#318-function-length)
- [3.19 Type Annotations](#319-type-annotations)
- [3.19.1 General Rules](#3191-general-rules)
- [3.19.2 Line Breaking](#3192-line-breaking)
- [3.19.3 Forward Declarations](#3193-forward-declarations)
- [3.19.4 Default Values](#3194-default-values)
- [3.19.5 NoneType](#3195-nonetype)
- [3.19.6 Type Aliases](#3196-type-aliases)
- [3.19.7 Ignoring Types](#3197-ignoring-types)
- [3.19.8 Typing Variables](#3198-typing-variables)
- [3.19.9 Tuples vs Lists](#3199-tuples-vs-lists)
- [3.19.10 Type variables](#31910-type-variables)
- [3.19.11 String types](#31911-string-types)
- [3.19.12 Imports For Typing](#31912-imports-for-typing)
- [3.19.13 Conditional Imports](#31913-conditional-imports)
- [3.19.14 Circular Dependencies](#31914-circular-dependencies)
- [3.19.15 Generics](#31915-generics)
- [4 Parting Words](#4-parting-words)

</details>

Expand Down Expand Up @@ -287,6 +365,11 @@ Exemptions from this rule:
* [`typing_extensions` module](https://github.com/python/typing_extensions/blob/main/README.md)
* Redirects from the
[six.moves module](https://six.readthedocs.io/#module-six.moves).
* Exposing classes in `__init__.py`

```python
from package.module import Class
```

<a id="s2.3-packages"></a>
<a id="23-packages"></a>
Expand Down