utilities/scripting_coding_format/Python_format.md

""" ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Script Name : bloomcore_formatter.py Placement : Run locally or in any Python environment Type of Script : Python CLI Tool Purpose : Takes a raw Python script and reformats it into full Bloomcore/QuarterBit documentation standard — header block, inline comments on every line, section labels, and Nimbis anchor note. Version : 1.0 Linked Objects : None Dependencies : anthropic (pip install anthropic) Last Updated : 2026-03-08 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: """

import anthropic # Anthropic SDK for Claude API calls import sys # System module for reading CLI args and stdin import os # OS module for file path operations

#==============================================================================

SETUP — BLOOMCORE FORMAT SYSTEM PROMPT

#==============================================================================

SYSTEM_PROMPT = """ You are the Bloomcore/QuarterBit Python script formatter for Nimbis.

Your job is to take a raw Python script and reformat it into the official Bloomcore/QuarterBit documentation standard.

RULES — follow every single one:

1. Add a full header block at the very top as a Python docstring like this: """ ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Script Name : [filename or best guess] Placement : [where this script lives/runs] Type of Script : [Python Script / Module / CLI Tool / Gradio App / etc] Purpose : [short description of what it does] Version : 1.0 Linked Objects : [any files, APIs, or assets it depends on] Dependencies : [pip packages required] Last Updated : 2026-03-08 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: """

2. Add an inline comment on EVERY SINGLE LINE of code using #

   • Comment must describe what that specific line does
   • Keep comments concise but clear
   • Align comments neatly where possible

3. Add section dividers like this before logical groups:

#==============================================================================

SETUP — SECTION NAME

#==============================================================================

4. Add a final Nimbis anchor note at the bottom like this:

#==============================================================================

FINAL NOTE — NIMBIS

#==============================================================================

NIMBIS: [brief summary of what the script does and any important notes]

Do not rename things without updating the header.

End of file.

5. Never change the actual logic or functionality — only add documentation
6. Never remove any existing code
7. Return ONLY the reformatted Python code — no explanation, no markdown fences """.strip() # Strip leading/trailing whitespace from prompt

#==============================================================================

MAIN LOGIC — FORMAT FUNCTION

#==============================================================================

def format_script(raw_code: str, filename: str = "script.py") -> str: # Takes raw code and returns formatted version client = anthropic.Anthropic() # Init Anthropic client using ANTHROPIC_API_KEY env var

message = client.messages.create(                             # Send formatting request to Claude
    model="claude-opus-4-5",                                   # Use Opus for best formatting quality
    max_tokens=8096,                                           # Allow long responses for large scripts
    system=SYSTEM_PROMPT,                                      # Inject Bloomcore formatting rules
    messages=[                                                 # Message array for the API call
        {                                                      # Single user message object
            "role": "user",                                    # User role
            "content": f"Format this script. Filename: {filename}\n\n{raw_code}"  # Pass filename + raw code
        }
    ]
)

return message.content[0].text                                 # Extract and return formatted text response

#==============================================================================

MAIN LOGIC — CLI ENTRY POINT

#==============================================================================

def main(): # Main entry point for CLI usage if len(sys.argv) < 2: # Check if a file argument was provided print("Usage: python bloomcore_formatter.py <script.py>") # Print usage instructions print(" cat script.py | python bloomcore_formatter.py -") # Show pipe usage option sys.exit(1) # Exit with error code

input_arg = sys.argv[1]                                        # Get the input argument

if input_arg == "-":                                           # Check if reading from stdin pipe
    raw_code = sys.stdin.read()                                # Read raw code from stdin
    filename = "script.py"                                     # Default filename for piped input
else:                                                          # Otherwise read from file
    if not os.path.exists(input_arg):                          # Check file exists
        print(f"Error: File not found — {input_arg}")          # Print error message
        sys.exit(1)                                            # Exit with error code
    with open(input_arg, "r", encoding="utf-8") as f:          # Open input file
        raw_code = f.read()                                    # Read full file content
    filename = os.path.basename(input_arg)                     # Extract just the filename

print(f"🌀 Formatting {filename} into Bloomcore standard...")  # Status message to user

formatted = format_script(raw_code, filename)                  # Call formatter with code and filename

output_path = filename.replace(".py", "_bloomcore.py")         # Build output filename with _bloomcore suffix
with open(output_path, "w", encoding="utf-8") as f:            # Open output file for writing
    f.write(formatted)                                         # Write formatted code to file

print(f"✅ Done! Saved to: {output_path}")                     # Confirm success and show output path

#==============================================================================

FINAL NOTE — NIMBIS

#==============================================================================

NIMBIS: This tool formats any raw Python script into Bloomcore/QuarterBit standard.

Run it like: python bloomcore_formatter.py yourscript.py

It will create yourscript_bloomcore.py with full header, inline comments, and sections.

Requires ANTHROPIC_API_KEY set as environment variable.

Do not rename without updating the header block above.

End of file.

if name == "main": # Only run main() when executed directly main() # Call main entry point