the_information_nexus/tech_docs/python/python_rules.md

Python Style Guide

Table of Contents

1. Code Layout
2. Naming Conventions
3. Comments
4. Docstrings
5. Imports
6. Whitespace in Expressions and Statements
7. Programming Recommendations
8. 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.