Module

utils.swizzle

SwizzleManager - Safe template override management for themes.

Features:

  • Copy ("swizzle") a theme template/partial into projecttemplates/preserving relative path
  • Track provenance in.bengal/themes/sources.json
  • List swizzled files
  • Naive update: if local file is unchanged from its original swizzle, replace with upstream

Note: Three-way merge can be added later; for now we only auto-update when no local edits.

View source
2 Classes 2 Functions

Classes

SwizzleRecord dataclass
0

Attributes

Name Type Description
target str
source str
theme str
upstream_checksum str
local_checksum str
timestamp float
SwizzleManager
6

Methods 4

swizzle
Copy a theme template into project templates/ and record provenance.
1 Path 
def swizzle(self, template_rel_path: str) -> Path

Copy a theme template into project templates/ and record provenance.

Parameters 1
template_rel_path str

Relative path inside theme templates/ (e.g., 'partials/toc.html')
Returns

Path —

Path to copied file under project templates/

list
0 builtins.list[Swizz… 
def list(self) -> builtins.list[SwizzleRecord]
Returns

builtins.list[SwizzleRecord]

list_swizzled
Alias for list() for backward compatibility.
0 builtins.list[Swizz… 
def list_swizzled(self) -> builtins.list[SwizzleRecord]

Alias for list() for backward compatibility.

Returns

builtins.list[SwizzleRecord]

update
Attempt to update swizzled files from upstream if local is unchanged. Returns …
0 dict[str, int] 
def update(self) -> dict[str, int]

Attempt to update swizzled files from upstream if local is unchanged.

Returns a summary dict with counts: {updated, skipped_changed, missing_upstream}

Returns

dict[str, int]

Internal Methods 2
__init__
1 None 
def __init__(self, site: Site) -> None
Parameters 1
site Site
_is_modified
Check if a swizzled template has been modified locally.
1 bool 
def _is_modified(self, template_rel_path: str) -> bool

Check if a swizzled template has been modified locally.

Parameters 1
template_rel_path str

Relative path inside templates/ (e.g., 'partials/toc.html')
Returns

bool —

True if template has been modified locally, False otherwise

Functions

_checksum_file
Compute truncated checksum of file content.
1 str 
def _checksum_file(path: Path) -> str

Compute truncated checksum of file content.

Parameters 1

Name Type Default Description
path Path —

Returns

str

_checksum_str
Compute truncated checksum of string content.
1 str 
def _checksum_str(content: str) -> str

Compute truncated checksum of string content.

Parameters 1

Name Type Default Description
content str —

Returns

str