[Avg. reading time: 8 minutes]

Code Quality & Safety

Type Hinting/Annotation

Type Hint

A type hint is a notation that suggests what type a variable, function parameter, or return value should be. It provides hints to developers and tools about the expected type but does not enforce them at runtime. Type hints can help catch type-related errors earlier through static analysis tools like mypy, and they enhance code readability and IDE support.

Type Annotation

Type annotation refers to the actual syntax used to provide these hints. It involves adding type information to variables, function parameters, and return types. Type annotations do not change how the code executes; they are purely for informational and tooling purposes.

Benefits

• Improved Readability: Code with type annotations is easier to understand.

• Tooling Support: IDEs can provide better autocompletion and error checking.

• Static Analysis: Tools like mypy can check for type consistency, catching errors before runtime.

age: int = 25
name: str = "Rachel"

Here, age is annotated as an int, and name is annotated as a str.

Function Annotation

def add(x: int, y: int) -> int:
    return x + y

Complex Annotation

from typing import List, Dict

def get_user_info(user_ids: List[int]) -> Dict[int, str]:
    return {user_id: f"User {user_id}" for user_id in user_ids}

Secret Management

Simple way is to use Environment Variables.

Either create them in Shell or .env

Shell

export SECRET_KEY='your_secret_value'

Windows Users

Goto Environment Variables via GUI and create one.

pip install python-dotenv

Create a empty file .env

.env

SECRET_KEY=your_secret_key
DATABASE_URL=your_database_url

main.py

from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

# Access the environment variables
secret_key = os.getenv("SECRET_KEY")
database_url = os.getenv("DATABASE_URL")

print(f"Secret Key: {secret_key}")
print(f"Database URL: {database_url}")

PDOC

Python Documentation

Docstring (Triple-quoted string)

def add(a: float, b: float) -> float:
    """
    Add two numbers.

    Args:
        a (float): The first number to add.
        b (float): The second number to add.

    Returns:
        float: The sum of the two numbers.

    Example:
        >>> add(2.5, 3.5)
        6.0
    """
    return a + b


def divide(a: float, b: float) -> float:
    """
    Divide one number by another.

    Args:
        a (float): The dividend.
        b (float): The divisor, must not be zero.

    Returns:
        float: The quotient of the division.

    Raises:
        ValueError: If the divisor (`b`) is zero.

    Example:
        >>> divide(10, 2)
        5.0
    """
    if b == 0:
        raise ValueError("The divisor (b) must not be zero.")
    return a / b

uv add pdoc

or

poetry add pdoc

or 

pip install pdoc

poetry run pdoc filename.py -o ./docs

or

uv run pdoc filename.py -o ./docs

#documentation #docsVer 5.5.3