Section markers¶

Section markers let the upgrade engine update specific blocks of a file while preserving user code outside the markers.

Marker syntax¶

# --- bluefox:routers ---
from app.routes import health
app.include_router(health.router)
# --- end:bluefox:routers ---

The format is # --- <marker> --- for the start and # --- end:<marker> --- for the end. Indentation is preserved — markers can be nested inside functions or classes.

Tracking sections¶

Register files with section tracking using sections_tracked:

from bluefox_upgrade import sections_tracked

tracked = dict([
    sections_tracked("app/__init__.py", ["bluefox:routers", "bluefox:middleware"]),
])

A single file can have multiple independent sections.

Updating a section¶

Use UpdateSection to replace the content between markers:

UpdateSection(
    path="app/__init__.py",
    marker="bluefox:routers",
    content=(
        "from app.routes import health, users, admin\n"
        "app.include_router(health.router)\n"
        "app.include_router(users.router)\n"
        "app.include_router(admin.router)\n"
    ),
    description="add admin router",
)

The content replaces everything between the start and end markers. The markers themselves and all code outside them are preserved.

Conflict detection¶

Section-tracked files use full-file SHA-256 hashing. This means any edit to the file — even outside the markers — will trigger a conflict. This is intentional: it prevents the engine from silently overwriting user changes to surrounding code.

Multiple sections in one file¶

# --- bluefox:imports ---
from app.middleware import cors, logging
# --- end:bluefox:imports ---

# user's custom imports
from app.custom import my_thing

# --- bluefox:middleware ---
app.add_middleware(cors)
app.add_middleware(logging)
# --- end:bluefox:middleware ---

Each section is updated independently by its marker name.