swe-devops-standards

Geospatial SWE & DevOps Standards

Purpose: code produced as part of geospatial work should run in the user's real environment and meet peer-level engineering quality. Apply these rules only when code or repository artifacts are in scope.

1. Environment realities (the top error source)

• Script-first by default: no %matplotlib inline, !pip install, or display() unless the user is explicitly in a notebook. Every file runs from a terminal via python script.py behind an if __name__ == "__main__": block. (Cell markers like # %% are fine as an addition — the script must also work without them.)
• Cross-platform paths: always pathlib.Path; never string-concatenate or hardcode / or \\. Ask or detect the user's OS before giving shell commands; give CMD/PowerShell syntax on Windows, POSIX elsewhere — don't mix (export vs set, venv/bin/activate vs venv\Scripts\activate).
• Encodings: explicit encoding="utf-8" on every text file open — Windows still defaults to legacy code pages, and non-ASCII content corrupts silently.
• Modern Python (3.11+): X | None unions, type aliases, structural pattern matching where they clarify; state the minimum version if a feature requires it.

2. Code quality defaults

Applied to every generated function/module, even when not asked:

def compute_share(values: list[float], total: float) -> list[float]:
    """Return each value's share of the total.

    Args:
        values: Values to compute shares for.
        total: Denominator; must be non-zero.

    Returns:
        Shares in the same order as values.

    Raises:
        ValueError: If total is zero.
    """
    if total == 0:
        raise ValueError("total must be non-zero — share is undefined.")
    return [v / total for v in values]

• Type hints on every signature; dataclass/TypeAlias for complex types.
• Google-style docstrings; one-liners suffice for trivial functions.
• Never bare except:; catch specific exceptions, handle or re-raise with raise ... from e. A silent pass costs a week of debugging.
• logging over print (leveled, formatted), except user-facing CLI output.
• Note algorithmic complexity where it matters ("this is O(n log n), safe at n>10⁶") — especially around nested loops and pandas apply.
• Magic numbers → named module-level constants.