TsukiNi22/ai-utils / skills/python/python-style
python-style
UnverifiedTsukini's Python style (from his real scripts - libutils cmake/scripts const.py / generate_exception_header.py, MAGIC - and the xstyle PY rules) - Xartania header,
Tsukini Python style
<name> (a skill) = the folder of that skill: ~/.claude/skills/<name> (setup.sh) or ${CLAUDE_SKILL_DIR}/../../*/<name> (plugin of the marketplace).
Measured on the user's own scripts (libutils cmake/scripts/const.py, generate_exception_header.py, 2026) and on
MAGIC (2025, older form: """ Import """ banners, plain classes for the constants, print errors): the 2026 form
wins, the older one is only kept when editing a file already written that way (the local style of a file wins).
Common rules of every language: coding-style; comments: python-comments; new files / classes: python-class. Everything in English.
Checked by xstyle (PY-* + the generic rules): run xstyle --rtk <files> after writing, xstyle --rtk --fix for the fixable ones.
File layout
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" # header: <cpp-class>/scripts/header.py --file x.py
██╗ ██╗ ... # (banner, optional: --banner none)
Edition:
## 06/10/2026 by Tsukini
File Name:
## generate.py
File Description:
## Generate the exception header from the config file
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
##### Import #####
# Import that can't be in the try
from const import RETURN, ERROR, FILES
from sys import exit, stderr
# Import that can be checked
try:
from pathlib import Path # Used to create & edit files
import json # Used to get the json data
import re # Used for pattern matching
except ImportError as e:
stderr.write(f"Import Error ({__file__}): {e}\n")
exit(ERROR.FATAL)
# Check if the program is call and not imported
if __name__ != "__main__":
stderr.write(f"The {__file__} can only be executed and not imported!\n")
exit(ERROR.FATAL)
##### Tools #####
def uint64_hash(s: str) -> int:
digest = sha256(s.encode()).digest()
value = int.from_bytes(digest[:8], "big") # 8 octets = 64 bits
return 1 + (value % VALUES.SIZE_MAX) # limit values
##### Program #####
...
exit(RETURN.OK)
- Header:
python3 <cpp-class>/scripts/header.py --file <name>.py [--desc "..."] [--banner none](63", no@date/@filetags in Python), never written by hand. - Sections, in this order, only the ones used:
##### Import #####,##### Const #####,##### Tools #####(free functions),##### Class #####,##### Program #####(scripts),##### Declaration #####(const.py: the instances). One empty line between blocks, never two (the user's rule, stricter than PEP 8;G-EMPTY-LINES). - Imports: first
# Import that can't be in the try(the project constants,sys), then# Import that can be checkedin atrywith one trailing# Used for ...per import,except ImportError as e:-> message with__file__on stderr +exit(ERROR.FATAL)(orexit(255)without const).from module import nameexplicit, neverimport *(PY-WILDCARD-IMPORT). Order ofcoding-style(personal libs, project, external; longest first). - Optional dependency install of a build script (libutils pattern, never in a library): a
trythat runspip install -r requirements.txtonly when not root (geteuid() != 0),except Exception: pass(failsafe, the only accepted silentexcept). - Guards right after the imports: a script exits when imported (
if __name__ != "__main__"), a module exits when executed (if __name__ == "__main__": ... can only be imported and not executed!). An installable package uses amain() -> intfunction instead (python-project).
const.py
##### Const #####
@dataclass(frozen=True)
class Return():
"""
Return values
"""
OK: int = 0 # Return value upon success on a call function
KO: int = 1 # Return value upon fail on a call function
@dataclass(frozen=True)
class Error():
"""
Error values
"""
FATAL: int = 0b1000 # Global error, the whole execution stops (100% execution stop)
LOCAL: int = 0b100 # Local error, the local execution probably can't go on (some chance of execution stop)
ACTION: int = 0b10 # Same~~ as Return.KO, an action of the program fails (low chance of execution stop)
@dataclass(frozen=True)
class Files:
"""
Different files path
"""
REQUIREMENTS: str = "cmake/scripts/requirements.txt"
##### Declaration #####
RETURN = Return()
ERROR = Error()
FILES = Files()
- One frozen dataclass per category (
Return,Error,Values,Files,Names...), PascalCase, short indented docstring, fieldsUPPER_SNAKEtyped with a trailing comment (aligned in a group), mutable values throughClassVar[dict[...]], groups inside a class under a# Commentline; instances in UPPER at the end, aligned. - Exit codes:
RETURN.OK(0) /RETURN.KO(1), theERROR.*bit flags,255only for the import failures.
Code
- Naming:
snake_casefunctions / variables / modules,PascalCaseclasses,UPPER_SNAKEconstants,_privateattributes and methods, special mode parameterssnake_casewith a default (failsafe: bool = False). - Types: type hints on every new parameter and return (
-> Noneincluded,PY-TYPE-HINTS),str | Nonefor an optional value (Python 3.10+), builtin generics (list[str],dict[str, int]). - Errors: never silent.
stderr.write(f"Error: <what> ({path})\n")thenexit(<code>)in a script (PY-PRINT-ERROR: neverprint(..., file=stderr)), exceptions with a context message in a module / library, the expected exceptions only (PY-BARE-EXCEPT: neverexcept:), early returns. - Files:
pathlib.Path,with open(path, "r", encoding="utf-8") as f:(PY-OPEN-ENCODING), binary modes explicit. - Strings: f-strings, double quotes (single quotes inside f-strings),
str.formatnever. - Comments: a block comment
# Capitalized, no final periodabove each logical block, trailing comments for a precision; no docstring on the functions of a script (the trailing comment of thedefor the block comment is enough); a class keeps a short indented docstring ("""\n What it is\n """), methods of a class too when public (one line: what it does). Never:param/ Sphinx / Google docstrings in new code (MAGIC's older form). - Classes: attributes created in
__init__(defaults there), methodssnake_case, one class per file in aClass/folder of an application (MAGIC),@dataclassfor plain data. - 4 spaces, no tabs, no trailing space,
exit(RETURN.OK)as the last line of a script.
Review
List the deviations with the rule (this skill / xstyle code); xstyle --rtk --fix -c PY,G applies the safe ones,
--dangerous-force the guessed type hints (check them).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |