Branca: HTML+JS Generation

0.8.2 · active · verified Thu Apr 09

Branca is a Python library designed to generate complex HTML and JavaScript pages from Python objects. It serves as a low-level base for other visualization libraries, most notably Folium, providing core components like `Figure`, `Element`, and `Colormap`. The current version is 0.8.2, and it maintains an active development cycle with regular patch and minor releases.

Warnings

breaking Python 3.7 support was dropped in Branca v0.7.2. Users on Python 3.7 or older must upgrade their Python environment or stick to Branca <0.7.2.
Fix: Upgrade your Python interpreter to 3.8 or newer.
breaking The internal `_env` instance attribute was removed from the `Element` class in v0.7.1. Direct access or manipulation of this attribute will cause `AttributeError`.
Fix: Avoid direct access to `Element._env`. Use public methods or properties for element manipulation. If highly custom Jinja2 templating is needed, it might require a different approach or contributing to Branca's public API.
breaking In v0.5.0, `Element` changed how it stores HTML content, moving from `data-html` to `srcdoc`. If you have custom parsers or scripts that relied on the `data-html` attribute to extract content, they will break.
Fix: Update any custom code that extracts HTML content from Branca elements to look for the `srcdoc` attribute instead of `data-html`.
deprecated The `split_six` utility function was removed in v0.7.2. While primarily an internal utility, if any custom code used it, it will no longer be available.
Fix: Review your codebase for any direct calls to `branca.utilities.split_six` and remove or replace them with equivalent standard Python functionality.
gotcha Starting with v0.8.2, `Element` ID generation became customizable. While this offers flexibility, if you relied on the exact default ID generation pattern for JavaScript interactions in previous versions, you might encounter subtle changes or unexpected behavior if IDs change slightly.
Fix: If your application relies on predicting element IDs for JavaScript, consider using the new customization options to explicitly define IDs or ensure your JS is resilient to varying ID formats.

Install

pip install branca Install stable version

Imports

Figure
```
from branca.element import Figure
```
Element
```
from branca.element import Element
```

JavascriptLink

from branca.element import JavascriptLink

LinearColormap

from branca.colormap import LinearColormap

StepColormap

from branca.colormap import StepColormap

Quickstart

This quickstart demonstrates how to create a `Figure` object, add external JavaScript links and custom HTML `Element`s to it, and then render the entire structure to an HTML string or save it to a file. It showcases Branca's role as a low-level HTML/JS generation utility.

from branca.element import Figure, Element, JavascriptLink

# Create a new Figure object to hold elements
f = Figure(width="100%", height="400px")

# Add a JavaScript library link (e.g., jQuery) to the figure's head
f.add_child(JavascriptLink("https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"))

# Add a simple HTML element to the figure's body
f.add_child(Element("<h1>Hello from Branca!</h1><p>This is a basic HTML element generated by Python.</p>"))

# Render the figure to an HTML string
html_output = f.render()
print(html_output[:500]) # Print the first 500 characters of the generated HTML

# To save to a file (uncomment to run):
# f.save("branca_example.html")

view raw JSON →