Python Gold Standards

Section 9.1 Python Gold Standards

Note ID: 202605080001 | Tags: python

🔗

Subsection 9.1.1 Python Rule of Thumb

The primary goal is to routinely write scripts that read like math and code.

🔗

If someone scrolls your script top-to-bottom, the conceptual story should flow:

What exists?
🔗

🔗
What are you allowed to call?
🔗

🔗
How does it work?
🔗

🔗
Proof it works.
🔗

🔗

🔗

Subsection 9.1.2 Gold Standard Python Template

# src/example.py
"""
Script descriptiion

Author:
Date:
"""
# imports and typing

__future__ import annotations           # Type hinting

__all__ = ["public_function"]            # Explicitly declare public API

# -----------------------------------------------------------------------------------------------------------
# 0️⃣ Typing helpers / protocols / constants (if needed)
# -----------------------------------------------------------------------------------------------------------

# -----------------------------------------------------------------------------------------------------------
# 1️⃣ Core definitions
# -----------------------------------------------------------------------------------------------------------

# -----------------------------------------------------------------------------------------------------------
# 2️⃣ Public API (functions users are meant to call)
# -----------------------------------------------------------------------------------------------------------

# -----------------------------------------------------------------------------------------------------------
# 3️⃣ Private helpers
# -----------------------------------------------------------------------------------------------------------

# -----------------------------------------------------------------------------------------------------------
# 4️⃣ Smoke tests / example usage
# -----------------------------------------------------------------------------------------------------------

# -----------------------------------------------------------------------------------------------------------
# 5️⃣ Entry point
# -----------------------------------------------------------------------------------------------------------

🔗

Subsection 9.1.3 Fundamental Features

Note 9.1.1. Numbered Emoji Sectioning.

Helps to make long scripts scannable.
🔗

🔗
Meant to be used as semantic anchor points, not decoration.
🔗

🔗

🔗

Note 9.1.2. `if name == "main"`.

Placed at the bottom of the script.
🔗

🔗
✔️ Only use for:
- Running smoke tests.
  🔗
  
  🔗
- Minimal demonstrations.
  🔗
  
  🔗
- Sanity checks.
  🔗
  
  🔗
🔗
🔗
❌ Never use for:
- Running large-scale experiments.
  🔗
  
  🔗
- Running training loops.
  🔗
  
  🔗
- Running inference pipelines.
  🔗
  
  🔗
🔗
🔗

🔗

Note 9.1.3. `def main() -> None:`.

Always exists.
🔗

🔗
Orchestrates calls to public API for smoke tests, demos, sanity checks.
🔗

🔗
Never contains math or logic explicitly.
🔗

🔗

🔗

def main() -> None:
    _smoke_test()

🔗

Note 9.1.4. "Big functions" to bundle logic..

Use large functions to bundle related logic together.

🔗

Note 9.1.5. Type Annotations Everywhere (within reason).

🔑 Key Habits to Remember:

Use Tensor, not torch.Tensor, in type annotations.
🔗

🔗
Annotate scalars (float | Tensor) when physically meaningul.
🔗

🔗
Use Final for constants:
🔗
```
omega: float | Final[Tensor] = 1.0
```
🔗

🔗

Note 9.1.6. NumPy-Style Docstrings.

These should always be present on:

public functions.
🔗

🔗
public classes.
🔗

🔗
nontrivial private helpers.
🔗

🔗

🔗

Minimal viable structure:

🔗

def public_function(x: Tensor) -> Tensor:
    """
    Short description.

    Parameters
    ----------
    x : Tensor
        Description of x.

    Returns
    -------
    Tensor
        Description of return value.
    """
    pass

🔗

Prev Top Next