structure updates

tech_docs/python/python_rules.md

@@ -0,0 +1,72 @@
+# 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.