Coding standards
YggdraSIM enforces a small, specific set of conventions. They exist to keep the codebase readable across very different subsystems (APDU builders, shell dispatchers, TUIs, ASN.1 codecs) and to make review and maintenance predictable.
On this page
Structural rules
- Never combine a control statement with its block on the same line.
if,try,except,with, andforalways open a block on the next line. - Prefer full class and function definitions in reviewable code blocks. Single-line one-off definitions are only acceptable in the vendored tree.
- Keep file sizes manageable. When a file crosses the point where a new contributor cannot find things fast, split it along functional seams.
Comments
- Do not narrate code. No "// Import the module", "// Define the function", "# Increment the counter", or similar.
- Comments explain intent, trade-offs, or constraints that the code itself cannot convey.
- No "added by" / "updated by" markers. Git history owns authorship, not inline comments.
Documentation tone
- Technical, dry, and supportive of specification language.
- Prefer precise terms.
ICCID,EID,ISD-R,PE,BPP,ADF USIMshould appear as written, not paraphrased. - When a spec governs a behavior, cite the spec. Vendored copies under
docs/are the canonical reference.
Wizard granularity
Interactive wizards must be tag-granular. Each nested TLV, ASN.1 field, or distinct conceptual step gets its own wizard stage. This keeps the operator path navigable and the wizard maintainable as the spec evolves.
Shell command lines
- Every interactive shell hands each command line, typed or from
--cmd/--stdin, toyggdrasim_common.command_log.run_with_command_logbefore it parses the line, so--log <file>works on every command. Pass adebugcontext that switches the shell's own debug output on (raw APDU logging, a debug mode) and back; the helper turns the global debug flag on itself. - A path that reaches the same handlers without a terminal, such as a GUI
action, refuses
--log(command_log.log_flag_present): a file path in a web request would be written on the server host. - Swap
sys.stdout/sys.stderraround one command, never across a prompt, so every swap stays nested and readline keeps the terminal.
APDU and crypto handling
- ISO/IEC 7816-4 terminology is preferred: CLA, INS, P1, P2, Lc, Data, Le, SW1, SW2.
- GP content-management verbs follow the card-spec naming exactly:
INSTALL FOR LOAD,INSTALL FOR INSTALL,PUT KEY. - SCP11 payload shaping must respect the shared
SCP11/shared/helpers instead of re-implementing the wheel per subsystem.
Reuse before building
- Before writing a new decoder or encoder, an EF or ASN.1 definition, a protocol stack, or a card, reader or network tool, check the osmocom projects for one that exists: pySim first, then libosmocore and the other projects on gitea.osmocom.org (simtrace2, osmo-remsim, osmo-epdg, the osmo-ttcn3-hacks test suites).
- Prefer importing it, then porting it, then using it as the reference behaviour. Check its licence against GPL-3.0-or-later before copying code.
- When nothing fits, the change says what was checked and why it does not fit.
- A defect or gap found in a reused project is fixed twice: a patch with
its evidence under
upstream_patches/<name>/(see theupstream_patches/osmocom-*folders), and a compensation in this tree that verifies its own effect.
Python conventions
- Follow PEP 8 loosely; clarity over pedantry.
- Type hints are welcome; they are not strictly enforced in legacy modules.
- Avoid deep inheritance chains. Composition over inheritance wins.
- Use
f"..."for string interpolation; reserve.format()for unusual cases. Drop thefprefix when the literal has no{...}placeholders; a baref"static text"is dead syntax and pyflakes flags it. - Prefer narrow exception types at every
raisesite.RuntimeErrorcovers operator-visible runtime failures,ValueErrorcovers malformed user or card data,TypeErrorcovers contract violations, and dedicatedOSErrorsubclasses cover transport issues. Avoidraise Exception(...)entirely -- the pre-release security sweep removed every remaining occurrence from the production tree, so new occurrences show up clearly in code review. except Exception:catches are acceptable only in display / TLV-fallback paths where any failure collapses to "render the raw hex instead". New production code should catch the specific exception it cares about.- Mutable default arguments are prohibited. Use the
Nonesentinel plus in-body initialization.
Security and boundary
- Contributors work inside the repository checkout. Do not add code paths
that reach outside the workspace root (absolute paths into
/etc/,/root/, or foreign user homes) unless the feature explicitly requires it and the escape hatch is documented. - Assume low-level interfacing via PC/SC or serial is in the threat model for every card-facing subsystem.
- Never commit keys, certificates, or credentials. Runtime material lives under the runtime root, not in the tree.
Decode boundaries
Every subsystem decodes bytes it did not produce: a card response, an ES9+ payload, a workbook, a profile package. Those bytes can be truncated, over-long, or hostile.
- Contain upstream exception types at the module boundary. Code that
delegates to pySim,
asn1tools, orcryptographycan raiseOutOfByteDataError,MissingDataError, or a bareIndexError. A caller catchingValueErrornever sees those, so a malformed remote payload unwinds the whole flow instead of failing the one step. - If the surrounding code already degrades gracefully for one malformed field, a sibling field must take the same route. Two fields of the same response behaving differently is a defect, not a policy choice.
- Guard the call, not one field. Validating a single field leaves its siblings in the same call unguarded.
- A rejection should raise a type the module owns --
ValueError, or a domain error such asScp03ResponseProtectionError. Those read as rejections; anIndexErrorreads as a crash. - A private helper may assume its caller's precondition. Keep the bounds check next to the caller that enforces it, and do not treat a scanner calling the helper directly as a finding.
When you change a decoder, call it with b"", a single byte, a truncated
TLV header, a length that over-claims its body (b"\x62\xc8"), a
long-form length with no body, and an odd-nibble BCD run. Anything other
than a clean rejection is a defect.
GUI frontend
gui_frontend/src/is the source;yggdrasim_common/gui_server/static/is build output. Rebuild with./scripts/build_gui_frontend.shafter every source change;tests/test_gui_source_manifests.pyrequires the served bundle to be byte-identical to a fresh build.- One design system, 20 themes. Colour reaches a rule through a theme
token or not at all; the per-file literal budget in
tests/test_gui_design_system_consistency.pyonly shrinks. New floating surfaces (position: fixed) are app chrome or transient overlays; action output renders inline. - The page CSP forbids inline scripts, inline styles, inline handlers and
eval. Build DOM withcreateElement/textContent. - Every operator-visible label is anchored in a specification or marked
YggdraSIM-coined in
guides/NAMING_CONVENTIONS.md. - The full contract, the CSS layer map and the theme registration steps
are in
gui_frontend/README.md.
Git and commits
- Do not update the git config in checked-in scripts or CI.
- Do not amend commits that are already pushed. Fix-forward with a new commit instead.
- Never force-push to
mainwithout explicit maintainer approval. - Commit messages are technical and dry. Do not embed editor, IDE, or authoring-tool identifiers in commit messages or source comments.
Pull requests
- Keep PRs scoped. Cross-cutting refactors belong in their own branch.
- Run the narrowly-targeted tests that match the touched surface.
- Update the relevant docs under
site-docs/when the operator-facing behavior changes.