tracktable.render.backends.folium_proxy module

Folium is a wrapper around leaflet.js. As such, it includes links for the browser to go download Leaflet and whatever plugins are being used. This works great on systems connected to the Internet but fails on isolated networks or stand-alone systems.

Most institutions that deal with this on a regular basis have built their own versions of Folium that either embeds the Javascript resources inline or changes the URLs to point to servers accessible on whatever network they use. The point of the folium_proxy module is to make it easier to use those alternate versions of Folium.

Here’s how we use it:

# Instead of this...
import folium

# Do this.
from tracktable.render.backends import folium_proxy
folium = folium_proxy.import_folium()

# Instead of this...
from folium.plugins import heat_map

# Do this.
from tracktable.render.backends import folium_proxy
heat_map = folium_proxy.import_folium("plugins.heat_map")

By default, the import_folium method will first try to import the package offlinefolium. If it can’t find that package, it will fall back to regular Folium.

You can change the name of the package that import_folium looks for by calling set_folium_proxy_name(new_module_name), documented below. You can disable the proxy mechanism entirely with set_folium_proxy_enabled(onoff).

This is a new feature in Tracktable 1.7.2. We are experimenting with different approaches in the hope of simplifying it further.

Module contents

Folium proxy: import offlinefolium if available

When on high-side or air-gapped networks, it is convenient to have a version of Folium that includes all of its necessary Javascript resources inline instead of reaching out to the open Internet for them. We typically install a package offlinefolium that does that.

This module does the following:

1. Provide a wrapper (import()) that imports offlinefolium if available; folium otherwise.

2. Allow the user to change offlinefolium to some other module name.

3. Allow the user to enable/disable this mechanism.

Functions:

• folium_proxy_name() - Get the name of the offline Folium package

• set_folium_proxy_name() - Set the name of the offline Folium package

• folium_proxy_enabled() - Get whether or not preferential import of offlinefolium is enabled

• set_folium_proxy_enabled() - Set whether or not to preferentially import offlinefolium

• import_folium() - Import either offlinefolium or folium, whichever is found first, or some subpackage

tracktable.render.backends.folium_proxy.folium_proxy_enabled() → bool

Is the Folium proxy module enabled?

If True (the default), we will try to import the module named in folium_proxy_module() first, then fall back to importing folium.

No arguments.

Returns:

Whether or not preferential import is enabled

Return type:

bool

tracktable.render.backends.folium_proxy.folium_proxy_name() → str

Get the name of the Folium proxy module

This is the name of the module that we will try to import whenever Folium is requested. Defaults to “offlinefolium”. Change with set_folium_proxy_name().

No arguments.

Returns:

Name of module as string

tracktable.render.backends.folium_proxy.import_folium(subpackage: str | None = None) → ModuleType

Import Folium or some subpackage

This function will try to import offlinefolium or whatever package was specified with set_folium_proxy_name(). If that fails, it will try to import folium. Use as follows:

Instead of import folium: >>> folium = import_folium()

Instead of from folium.plugins import heat_map: >>> heat_map = import_folium(“plugins.heat_map”)

Note that you can only import a module or package. To access members of the module such as folium.plugins.heat_map.HeatMap, use the following:

>>> heat_map_module = import_folium("plugins.heat_map")
>>> HeatMap = heat_map_module.HeatMap

This function will print a log message at level INFO when we successfully import the proxy module instead of regular Folium. It will also print a log message at level WARNING if we get a different module than the one that was already imported.

Keyword Arguments:

subpackage (str) – Sub-package of Folium to import. To get “folium.plugins.heat_map”, specify “plugins.heat_map”.

Returns:

Imported module.

Raises:

• ImportError – Neither the proxy module nor folium could

• be imported –

tracktable.render.backends.folium_proxy.set_folium_proxy_enabled(enabled: bool) → None

Enable or disable preferential import of offlinefolium

If True, we will try to import the proxy module first, then fall back to folium if it is not found. If False, we will only try to import folium.

Parameters:

enabled (bool) – Whether to do preferential import

Returns:

None

tracktable.render.backends.folium_proxy.set_folium_proxy_name(package_name: str) → None

Set the name of the Folium proxy module

Change the name of the module that we will try to import whenever Folium is requested.

Parameters:

package_name (str) – Name of module to try to import instead of Folium

Returns:

None