Fix for issue 1359

This includes a structural change. I added a Class object with
a include method. This follows leaflet's `L.Class.include`
statement. This allows users to override Leaflet class behavior.

The motivating example for this can be found in the added
`test_include` in `test_map.py`. Using an include, users can
override the `createTile` method of `L.TileLayer` and add
a headers.

Author: hansthen

folium/elements.py

@@ -148,3 +148,23 @@ def __init__(self, element_name: str, element_parent_name: str):
         super().__init__()
         self.element_name = element_name
         self.element_parent_name = element_parent_name
+
+
+class IncludeStatement(MacroElement):
+    """Generate an include statement on a class."""
+
+    _template = Template(
+        """
+        L.{{ this.class_name }}.include(
+            {{ this.options | tojavascript }}
+        )
+    """
+    )
+
+    def __init__(self, class_name: str, **kwargs):
+        super().__init__()
+        self.class_name = class_name
+        self.options = kwargs
+
+    def render(self, *args, **kwargs):
+        return super().render(*args, **kwargs)

folium/features.py

@@ -36,7 +36,7 @@
 
 from folium.elements import JSCSSMixin
 from folium.folium import Map
-from folium.map import FeatureGroup, Icon, Layer, Marker, Popup, Tooltip
+from folium.map import Class, FeatureGroup, Icon, Layer, Marker, Popup, Tooltip
 from folium.template import Template
 from folium.utilities import (
     JsCode,
@@ -2023,7 +2023,7 @@ def __init__(
             self.add_child(PolyLine(val, color=key, weight=weight, opacity=opacity))
 
 
-class Control(JSCSSMixin, MacroElement):
+class Control(JSCSSMixin, Class):
     """
     Add a Leaflet Control object to the map
 

folium/map.py

@@ -4,12 +4,12 @@
 """
 
 import warnings
-from collections import OrderedDict
+from collections import OrderedDict, defaultdict
 from typing import TYPE_CHECKING, Optional, Sequence, Union, cast
 
 from branca.element import Element, Figure, Html, MacroElement
 
-from folium.elements import ElementAddToElement, EventHandler
+from folium.elements import ElementAddToElement, EventHandler, IncludeStatement
 from folium.template import Template
 from folium.utilities import (
     JsCode,
@@ -22,11 +22,47 @@
     validate_location,
 )
 
+
+class classproperty:
+    def __init__(self, f):
+        self.f = f
+
+    def __get__(self, obj, owner):
+        return self.f(owner)
+
+
 if TYPE_CHECKING:
     from folium.features import CustomIcon, DivIcon
 
 
-class Evented(MacroElement):
+class Class(MacroElement):
+    """The root class of the leaflet class hierarchy"""
+
+    _includes = defaultdict(dict)
+
+    @classmethod
+    def include(cls, **kwargs):
+        cls._includes[cls].update(**kwargs)
+
+    @classproperty
+    def includes(cls):
+        return cls._includes[cls]
+
+    def render(self, **kwargs):
+        figure = self.get_root()
+        assert isinstance(
+            figure, Figure
+        ), "You cannot render this Element if it is not in a Figure."
+        if self.includes:
+            stmt = IncludeStatement(self._name, **self.includes)
+            figure.script.add_child(
+                Element(stmt._template.render(this=stmt, kwargs=self.includes)),
+                index=-1,
+            )
+        super().render(**kwargs)
+
+
+class Evented(Class):
     """The base class for Layer and Map
 
     Adds the `on` and `once` methods for event handling capabilities.

tests/test_map.py

@@ -11,7 +11,7 @@
 
 from folium import GeoJson, Map, TileLayer
 from folium.map import CustomPane, Icon, LayerControl, Marker, Popup
-from folium.utilities import normalize
+from folium.utilities import JsCode, normalize
 
 tmpl = """
         <div id="{id}"
@@ -148,6 +148,55 @@ def test_popup_show():
     assert normalize(rendered) == normalize(expected)
 
 
+def test_include():
+    create_tile = """
+        function(coords, done) {
+            const url = this.getTileUrl(coords);
+            const img = document.createElement('img');
+            fetch(url, {
+              headers: {
+                "Authorization": "Bearer <Token>"
+              },
+            })
+            .then((response) => {
+                img.src = URL.createObjectURL(response.body);
+                done(null, img);
+            })
+            return img;
+        }
+    """
+    TileLayer.include(create_tile=JsCode(create_tile))
+    tiles = TileLayer(
+        tiles="OpenStreetMap",
+    )
+    m = Map(
+        tiles=tiles,
+    )
+    rendered = m.get_root().render()
+    expected = """
+    L.TileLayer.include({
+      "createTile":
+        function(coords, done) {
+            console.log("creating tile");
+            const url = this.getTileUrl(coords);
+            const img = document.createElement('img');
+            fetch(url, {
+              headers: {
+                "Authorization": "Bearer <Token>"
+              },
+            })
+            .then((response) => {
+                img.src = URL.createObjectURL(response.body);
+                done(null, img);
+            })
+            return img;
+        },
+    })
+    """
+
+    assert normalize(expected) in normalize(rendered)
+
+
 def test_popup_backticks():
     m = Map()
     popup = Popup("back`tick`tick").add_to(m)