branca.element

Element

A generic class for creating Elements.

class branca.element.CssLink(url: str, download: bool = False)

Bases: Link

Create a CssLink object based on a url.

Parameters:

• url (str) – The url to be linked

• download (bool, default False) – Whether the target document shall be loaded right now.

class branca.element.Div(width: int | float | str | Tuple[float, str] = '100%', height: int | float | str | Tuple[float, str] = '100%', left: int | float | str | Tuple[float, str] = '0%', top: int | float | str | Tuple[float, str] = '0%', position: str = 'relative')

Bases: Figure

Create a Div to be embedded in a Figure.

Parameters:

• width (int or str, default '100%') – The width of the div in pixels (int) or percentage (str).

• height (int or str, default '100%') – The height of the div in pixels (int) or percentage (str).

• left (int or str, default '0%') – The left-position of the div in pixels (int) or percentage (str).

• top (int or str, default '0%') – The top-position of the div in pixels (int) or percentage (str).

• position (str, default 'relative') – The position policy of the div. Usual values are ‘relative’, ‘absolute’, ‘fixed’, ‘static’.

get_root() → Div

Returns the root of the elements tree.

render(**kwargs)

Renders the HTML representation of the element.

class branca.element.Element(template: str | None = None, template_name: str | None = None)

Bases: object

Basic Element object that does nothing. Other Elements may inherit from this one.

Parameters:

• template (str, default None) –

  A jinaj2-compatible template string for rendering the element. If None, template will be:

  {% for name, element in this._children.items() %}
  {{element.render(**kwargs)}}
  {% endfor %}
  

  so that all the element’s children are rendered.

• template_name (str, default None) – If no template is provided, you can also provide a filename.

add_child(child: Element, name: str | None = None, index: int | None = None) → Element

Add a child.

add_children(child: Element, name: str | None = None, index: int | None = None) → Element

Add a child.

add_to(parent: Element, name: str | None = None, index: int | None = None) → Element

Add element to a parent.

get_bounds() → List[List[float | None]]

Computes the bounds of the object and all it’s children in the form [[lat_min, lon_min], [lat_max, lon_max]].

get_name() → str

Returns a string representation of the object. This string has to be unique and to be a python and javascript-compatible variable name.

get_root() → Element

Returns the root of the elements tree.

render(**kwargs) → str

Renders the HTML representation of the element.

save(outfile: str | bytes | Path | BinaryIO, close_file: bool = True, **kwargs)

Saves an Element into a file.

Parameters:

• outfile (str or file object) – The file (or filename) where you want to output the html.

• close_file (bool, default True) – Whether the file has to be closed after write.

to_dict(depth: int = -1, ordered: bool = True, **kwargs) → dict | OrderedDict

Returns a dict representation of the object.

to_json(depth: int = -1, **kwargs) → str

Returns a JSON representation of the object.

class branca.element.Figure(width: str = '100%', height: str | None = None, ratio: str = '60%', title: str | None = None, figsize: Tuple[int, int] | None = None)

Bases: Element

Create a Figure object, to plot things into it.

Parameters:

• width (str, default "100%") – The width of the Figure. It may be a percentage or pixel value (like “300px”).

• height (str, default None) – The height of the Figure. It may be a percentage or a pixel value (like “300px”).

• ratio (str, default "60%") – A percentage defining the aspect ratio of the Figure. It will be ignored if height is not None.

• title (str, default None) – Figure title.

• figsize (tuple of two int, default None) – If you’re a matplotlib addict, you can overwrite width and height. Values will be converted into pixels in using 60 dpi. For example figsize=(10, 5) will result in width=”600px”, height=”300px”.

add_subplot(x: int, y: int, n: int, margin: float = 0.05) → Div

Creates a div child subplot in a matplotlib.figure.add_subplot style.

Parameters:

• x (int) – The number of rows in the grid.

• y (int) – The number of columns in the grid.

• n (int) – The cell number in the grid, counted from 1 to x*y.

• margin (float, default 0.05) – Factor to add to the left, top, width and height parameters.

Example

>>> fig.add_subplot(3, 2, 5)
# Create a div in the 5th cell of a 3rows x 2columns
grid(bottom-left corner).

get_root() → Figure

Returns the root of the elements tree.

render(**kwargs) → str

Renders the HTML representation of the element.

to_dict(depth: int = -1, ordered: bool = True, **kwargs) → dict | OrderedDict

Returns a dict representation of the object.

class branca.element.Html(data: str, script: bool = False, width: int | float | str | Tuple[float, str] = '100%', height: int | float | str | Tuple[float, str] = '100%')

Bases: Element

Create an HTML div object for embedding data.

Parameters:

• data (str) – The HTML data to be embedded.

• script (bool) – If True, data will be embedded without escaping (suitable for embedding html-ready code)

• width (int or str, default '100%') – The width of the output div element. Ex: 120 , ‘80%’

• height (int or str, default '100%') – The height of the output div element. Ex: 120 , ‘80%’

class branca.element.IFrame(html: str | Element | None = None, width: str = '100%', height: str | None = None, ratio: str = '60%', figsize: Tuple[int, int] | None = None)

Bases: Element

Create a Figure object, to plot things into it.

Parameters:

• html (str, default None) – Eventual HTML code that you want to put in the frame.

• width (str, default "100%") – The width of the Figure. It may be a percentage or pixel value (like “300px”).

• height (str, default None) – The height of the Figure. It may be a percentage or a pixel value (like “300px”).

• ratio (str, default "60%") – A percentage defining the aspect ratio of the Figure. It will be ignored if height is not None.

• figsize (tuple of two int, default None) – If you’re a matplotlib addict, you can overwrite width and height. Values will be converted into pixels in using 60 dpi. For example figsize=(10, 5) will result in width=”600px”, height=”300px”.

render(**kwargs) → str

Renders the HTML representation of the element.

class branca.element.JavascriptLink(url: str, download: bool = False)

Bases: Link

Create a JavascriptLink object based on a url.

Parameters:

• url (str) – The url to be linked

• download (bool, default False) – Whether the target document shall be loaded right now.

class branca.element.Link(url: str, download: bool = False)

Bases: Element

An abstract class for embedding a link in the HTML.

get_code() → bytes

Opens the link and returns the response’s content.

to_dict(depth: int = -1, ordered: bool = True, **kwargs) → dict | OrderedDict

Returns a dict representation of the object.

class branca.element.MacroElement

Bases: Element

This is a parent class for Elements defined by a macro template. To compute your own element, all you have to do is:

• To inherit from this class

• Overwrite the ‘_name’ attribute

• Overwrite the ‘_template’ attribute with something of the form:

  {% macro header(this, kwargs) %}
      ...
  {% endmacro %}
  
  {% macro html(this, kwargs) %}
      ...
  {% endmacro %}
  
  {% macro script(this, kwargs) %}
      ...
  {% endmacro %}
  

render(**kwargs)

Renders the HTML representation of the element.