01 — Python

217,266 lines across 3,999 files. The most distinctive style in the estate, and the one with a written rule set behind it.

1. The complete example — everything in eleven lines

sg_compute/catalog/schemas/Schema__Caller__IP.py, verbatim and entire:

# ═══════════════════════════════════════════════════════════════════════════════
# SG/Compute — Schema__Caller__IP
# Response schema for GET /catalog/caller-ip.
# ═══════════════════════════════════════════════════════════════════════════════

from osbot_utils.type_safe.Type_Safe                                          import Type_Safe

from sg_compute.primitives.Safe_Str__IP__Address                             import Safe_Str__IP__Address


class Schema__Caller__IP(Type_Safe):
    ip : Safe_Str__IP__Address = Safe_Str__IP__Address()

Nine conventions are visible in that file, and the whole style follows from them:

1. A ═══ banner header — product name, class name, one line of purpose
2. The filename is the class name. Schema__Caller__IP.py → class Schema__Caller__IP
3. One class per file
4. Fully-qualified imports from the per-class path — never a package re-export
5. import keywords aligned to a column
6. Type_Safe as the base class
7. A constrained primitive (Safe_Str__IP__Address) rather than str
8. The annotation colon aligned, with an instance as the default
9. No docstring. The banner does that job

2. Naming

Prefix families — what the class is

Suffix families — what the class does

__Builder 97 · __Helper 86 · __Client 77 · __Service 46 · __Mapper 39 · __Detector 23 · __Loader 17 · __Registry 14 · __Writer 14 · __Parser 10 · __Runner 9 · __Manager 7 · __Factory 4 · __Watchdog 2 · __Poller 1

The double-underscore rule

__ is the word separator inside a compound name; _ separates words within one term. Schema__Image__Build__Request reads as Schema · Image · Build · Request. Safe_Str__IP__Address keeps Safe_Str as one term. 3,871 of 3,999 filenames contain __.

The documented normalisation (rule 20) handles the one hard case: the spec uses names like SGraph-AI with a hyphen, which is not a legal Python identifier. Class and module names use SGraph_AI; repo roots and test filenames may keep SGraph-AI.

__init__.py stays empty

Rule 22, and it holds at 299 of 302 (99%). Callers import from the fully-qualified per-class path; nothing is ever re-exported. The rule carries its own warning, learned the hard way: "Never commit an empty __init__.py in a folder that shares a name with a sibling .py module: Python's import system prefers the package and every import under the module breaks."

3. Type_Safe — runtime validation instead of static typing

From osbot-utils. Rule 1: all classes extend it — no plain Python classes. Rule 82 of the tooling table is blunter: "Never use Pydantic. No Literals."

Of 1,034 classes in the new tree:

Excluding tests and enums, essentially every class is in the Type_Safe lineage. Do not publish "48% extend Type_Safe" — it is true and it is misleading.

What it buys: attributes are validated at construction, so a value that exists is a value that is valid. There is no separate validation layer, no schema-parse step at the boundary, and no if not isinstance(...) scattered through the code. It is also why the absence of a type-checker matters less here than it would elsewhere — though see 08__ §1.

4. Constrained primitives — the type is the validation

Rule 2: "zero raw primitives — no str, int, float, list, dict as attributes."

sg_compute/primitives/ alone holds 27, and the pattern is uniform:

# ═══════════════════════════════════════════════════════════════════════════════
# SG/Compute — Safe_Str__IP__Address
# IPv4 address string, e.g. "1.2.3.4". Empty = not yet assigned.
# ═══════════════════════════════════════════════════════════════════════════════

import re

from osbot_utils.type_safe.primitives.core.Safe_Str                         import Safe_Str
from osbot_utils.type_safe.primitives.core.enums.Enum__Safe_Str__Regex_Mode import Enum__Safe_Str__Regex_Mode


class Safe_Str__IP__Address(Safe_Str):
    max_length        = 45                                                   # covers IPv4 + IPv6
    regex             = re.compile(r'^[0-9a-fA-F.:]*$')
    regex_mode        = Enum__Safe_Str__Regex_Mode.MATCH
    strict_validation = True
    allow_empty       = True

Five class attributes, all aligned, and a trailing comment carrying the reasoning (# covers IPv4 + IPv6) — which is the estate's substitute for a docstring.

The domain vocabulary is visible in the file list: Safe_Str__AWS__Region, Safe_Str__Docker__Image, Safe_Str__Instance__Type, Safe_Str__Node__Name, Safe_Str__Pod__Name, Safe_Str__SSM__Path, Safe_Str__Spec__Id, Safe_Int__Port, Safe_Int__Max__Hours, Safe_Int__Exit__Code.

Naming a type is how a domain concept gets recorded. That is the argument for the page.

5. Layout and formatting

Banners. # ═ × 79, three content lines (product — class name — purpose), # ═ × 79. Present on 3,120 of 3,999 files, and 100% of the 992 class-defining files in the new tree. Rule 7 adds a caveat learned from GitHub: "Python files only. In Markdown, # is heading syntax — a # ═══ header block renders as a stack of H1s."

Alignment. Measured:

• Schema attribute colons: 100% aligned — 46 of 46 files with two or more annotated attributes
• Class attribute values: aligned — see the Safe_Str example
• Import keywords: 39% aligned — 321 of 817 files with two or more from X import Y lines have every import at a single column. This is the estate's least consistent formatting rule and the easiest to automate.

Comments. Rule 8: "inline comments only — no docstrings, ever." Compliance is 99.7% — 3 violations in 992 files. Trailing comments carry the reasoning; the banner carries the purpose.

Private methods. Rule 9: "no underscore prefix for private methods." Compliance is 91% — 97 files in the new tree use def _method. Either the rule is Python-only-and-widely-ignored, or it needs revisiting. The document does not say. 08__ Q2.

6. Testing

Rule set, verbatim, from Testing — Non-Negotiable:

1. No mocks. No patches. Use register_playwright_service__in_memory() and in_memory_stack-style composition.
2. Assert on contracts — schemas, status codes, persisted artefacts — not implementation details.
3. Real Chromium for integration tests. Gate on SG_PLAYWRIGHT__CHROMIUM_EXECUTABLE; skip cleanly when absent.
4. Deploy-via-pytest. Deploy tests are numbered (test_1__create_lambda, test_2__invoke__health_info, …) and run top-down.

"No mocks, no patches" is the strongest opinion in the whole rule set and it deserves its own page. The alternative is real in-memory composition, which is only affordable because Type_Safe objects are cheap to build — the type system and the testing philosophy are the same decision.

169 classes extend TestCase, so tests are class-based. And 4,785 tests run in 81 seconds, which is the evidence that the no-mocks position is affordable rather than aspirational.

7. Responsibility boundaries — rules that name a single owner

Rules 16–19 are unusual and worth publishing as a pattern:

1. Step__Executor is the ONLY class that calls page.* Playwright methods (with a Browser__Launcher carve-out for process lifecycle)
2. Artefact__Writer is the ONLY class that writes to sinks
3. Request__Validator contains ALL cross-schema validation
4. Routes have no logic — pure delegation to Playwright__Service

Each names exactly one owner for a capability, and rule 16 is enforced by a CI guard that fails the build if any raw browser.new_context( appears outside Page__Factory. That is the model: a boundary rule with a test behind it. Three of the four have no such test.

8. What a linter config would encode

Ordered by value, for /enforce/:

1. Import alignment — the 61% gap, and the only formatting rule that is measurably inconsistent
2. No docstrings — trivial (ruff D-rules inverted), currently 3 violations
3. Banner present and well-formed — a custom check, ~20 lines
4. Filename equals class name, one class per file — a custom check
5. No raw primitives as class attributes — the highest-value rule and the hardest to express; probably a custom AST check
6. Ban Pydantic, Literal, direct boto3 — three import bans, one line each
7. __init__.py empty — trivial
8. No _ prefixed methods — trivial, but decide the rule first (§5)

Items 2, 6 and 7 are a single ruff config block. Items 1, 3, 4, 5 and 8 are a small tests/ci/ module in the style of the four that already exist.

9. Dependencies — the osbot-* family

osbot-utils (the source of Type_Safe and Safe_Str, 885 mentions across the corpus), osbot-aws, osbot-fast-api, osbot-fast-api-serverless, memory_fs, mgraph-db, mgraph-ai-service-cache. All Apache-2.0, all under the owasp-sbot GitHub organisation.

Two hard rules govern their use:

Type system — Type_Safe from osbot-utils. Never use Pydantic. No Literals. AWS operations — osbot-aws. Never use boto3 directly (narrow documented exception for the Lambda Function URL two-statement permission fix).

Note the exception is documented rather than silent. That is a convention in itself and worth naming on the site: a banned thing with one written carve-out, rather than a banned thing with quiet violations.

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).

source: /briefs/02__javascript.md