# Python Style Guide

## Table of Contents

1. [Code Layout](#code-layout)
2. [Naming Conventions](#naming-conventions)
3. [Comments](#comments)
4. [Docstrings](#docstrings)
5. [Imports](#imports)
6. [Whitespace in Expressions and Statements](#whitespace-in-expressions-and-statements)
7. [Programming Recommendations](#programming-recommendations)
8. [Testing](#testing)

## Code Layout

- **Indentation**: Use 4 spaces per indentation level.
- **Line Length**: Limit all lines to a maximum of 79 characters.
- **Blank Lines**: Use blank lines to separate functions and classes, and larger blocks of code inside functions.
- **Encoding**: Use UTF-8 encoding for Python 3.

## Naming Conventions

- **Modules**: Short, lowercase names, preferably without underscores.
- **Classes**: Use the CapWords convention.
- **Functions**: Lowercase, with words separated by underscores.
- **Variables**: Lowercase, with words separated by underscores.
- **Constants**: Uppercase, with words separated by underscores.

## Comments

- **Inline Comments**: Use sparingly and focus on why, not what.
- **Block Comments**: Indent to the same level as the code it describes.

## Docstrings

- **Public Modules**: Describe what the module contains and its purpose.
- **Functions**: Describe what the function does and its arguments.
- **Classes**: Describe what the class does.

## Imports

- **Import Order**: Within each import group (standard library, third-party, local), sort the imports alphabetically.
- **Standard Library Imports**: First, separate from third-party libraries.
- **Related Third-Party Imports**: Second.
- **Local Application/Library Specific Imports**: Third.
- **Absolute Imports**: Prefer absolute imports over relative imports to improve readability and avoid issues with module naming conflicts.
- **Wildcards**: Avoid using wildcard imports (`from module import *`) as they can pollute the namespace and make it unclear which names are present.

## Whitespace in Expressions and Statements

- Avoid extraneous whitespace in the following situations:
  - Immediately inside parentheses, brackets, or braces.
  - Between a trailing comma and a following close parenthesis.
  - Immediately before a comma, semicolon, or colon.
- **Binary Operators**: Surround binary operators with a single space on either side for readability, except when assigning default parameter values in function definitions.
- **Compound Statements**: Avoid using backslash line continuation. Instead, use implicit line joining within parentheses, brackets, and braces.

## Programming Recommendations

- **`is not` over `not ... is`**: Use `is not` operator rather than `not ... is`.
- **List Comprehensions**: Preferable over multiple `for` and `if` statements.
- **String Quotes**: Prefer single quotes for string literals, unless the string contains a single quote character. Use double quotes for triple-quoted strings and docstrings.
- **Exception Handling**: Use specific exception classes when catching exceptions, rather than using a bare `except:` clause. Avoid catching `Exception` or `StandardError` unless you are re-raising the exception or in the outermost block in a thread.
- **Context Managers**: Use context managers (`with` statement) when working with file objects and other resources that need to be properly closed or released.
- **Generator Expressions**: Consider using generator expressions instead of list comprehensions for large datasets or when you don't need to store the entire result in memory.

## Testing

- **Test Framework**: Use a standard testing framework like `unittest` or `pytest` to write and run tests for your code.
- **Test Coverage**: Strive for high test coverage to ensure your code is well-tested and to catch potential bugs early in the development process.

Remember, this is a starting guide. Feel free to adapt and expand it based on the needs of your projects and your personal preferences.