html_compose.resource

 19class js_import:
 20    """
 21    A javascript import helper class which employs one or more of:
 22
 23    - `script(` to define the import
 24    - `importmap` which maps javascript module names to URLs
 25    Setting the name parameter like so
 26    ```python
 27    js_import(
 28        "https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm",
 29        name="alpinejs")
 30    ```
 31    creates an import map so javascript modules can be imported by name
 32    - `link(rel="modulepreload")` to preload the import
 33    - if cache_bust is true, appends a timestamp to the URL to
 34
 35    An production usage might look like:
 36
 37    ```python
 38    [
 39    js_import('./static/admin.js',
 40                name='admin',
 41                cache_bust=True),
 42
 43    js_import(
 44        "https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm",
 45        name="alpinejs",
 46        preload=True,
 47        hash=(
 48            "sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/"
 49            "9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p"
 50            ),
 51        crossorigin="anonymous"
 52        ),
 53
 54    ]
 55    ```
 56
 57    ...
 58
 59    ## Usage in window:
 60
 61    ```python
 62    script(type="module")[
 63        '''
 64        import Alpine from 'alpinejs'
 65        window.Alpine = Alpine
 66        Alpine.start()
 67        '''
 68    ]
 69    ```
 70
 71    ## Generated "HTML":
 72
 73    ```python
 74    import json
 75    from html_compose import el, unsafe_text
 76
 77    [
 78        el.script(type="importmap")[
 79            unsafe_text('{"imports": {"admin": "./static/admin.js?ts=1760157623", "alpinejs": "https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm"}}')
 80        ],
 81
 82        el.link(href="./static/admin.js?ts=1760157623", rel=["modulepreload"]),
 83
 84
 85        el.link(
 86            href="https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm",
 87            integrity="sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p",
 88            crossorigin="anonymous",
 89            rel=["modulepreload"],
 90        ),
 91
 92        el.script(src="./static/admin.js?ts=1760157623", type="module"),
 93
 94        el.script(
 95            src="https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm",
 96            type="module",
 97            integrity="sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p",
 98            crossorigin="anonymous",
 99        ),
100    ]
101    ```
102
103    See:
104    - https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap
105    - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
106    - https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/modulepreload
107    - https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/preload
108    - https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
109    - https://www.srihash.org/
110
111    """
112
113    def __init__(
114        self,
115        source: str,
116        name: str | None = None,
117        preload: bool = False,
118        hash: str | None = None,
119        async_: bool = False,
120        defer: bool = False,
121        nomodule: bool = False,
122        scope_url: str | Iterable[str] | None = None,
123        crossorigin: Literal["", "anonymous", "user-credentials"]
124        | str
125        | None = None,
126        cache_bust: bool = False,
127    ):
128        """
129        A javascript import wrapper to manage optimal window import strategies.
130
131        If name is set, the import is added to an import map and imported
132        as a module.
133
134        Parameters
135        ----------
136        `source`:
137            The literal src passed to tags i.e. script and link preload.
138
139            If cache_bust is set, a timestamp is appended to the URL.
140        `name`:
141            The name of the import, e.g. "lodash" which can be used in
142            javascript type="module" imports.
143
144            Doing this automatically changes the script type to module
145
146        `preload`:
147            The modulepreload keyword, for the rel attribute of the `<link/>`
148            element, provides a declarative way to preemptively fetch a module
149            script, parse and compile it, and store it in the document's module
150            map for later execution.
151
152            If this is not a javascript module (i.e. name is not set),
153            the rel attribute is set to "preload" and the as_ attribute
154            is set to "script" instead.
155
156        `async_`:
157            The async attribute causes the script to be executed asynchronously as soon as it is available,
158            without blocking HTML parsing.
159
160        `defer`:
161            Defers script execution until document parsing is complete.
162            Has no effect on module scripts (they are deferred by default).
163
164        `nomodule`:
165            Added to script tag.
166
167            Indicates that the script should not be executed in browsers that
168            support ES modules — in effect, this can be used to serve fallback
169            scripts to older browsers that do not support javascript modules.
170
171        `hash`:
172            An optional SRI integrity hash for the import
173
174        `crossorigin`:
175            Optionally sets the crossorigin attribute on the script tag.
176            Valid values are "", "anonymous", "use-credentials"
177
178        `cache_bust`:
179            If true, appends a timestamp to the URL to work with browser
180            caching. Webservers configured for static resources manage this
181            feature automatically, but for development this can be useful.
182
183            This feature only works for local resources, i.e. those that
184            exist relative to `resource.settings.base_dir`
185
186        `scope_url`:
187            Optional route or list of paths where this import should be
188            included.
189
190            Scopes let you have different mappings for different parts of your
191            app.
192
193            Because they affect the import map but not what is loaded -
194            the script tag controls what loads - they are rarely used.
195
196        """
197
198        self.name = name
199        self.source = source
200        self.preload = preload
201        self.hash = hash
202        self.scope_urls = scope_url
203        if scope_url:
204            if isinstance(scope_url, str):
205                self.scope_urls = [scope_url]
206            elif is_iterable_but_not_str(scope_url):
207                # Materialize scope URLs so they can be iterated multiple times
208                # (flatten_iterable returns a generator by default).
209                self.scope_urls = list(flatten_iterable(scope_url))
210            else:
211                self.scope_urls = [str(scope_url)]
212        self.crossorigin = crossorigin
213        self.cache_bust = cache_bust
214        self.has_link = preload
215        self.async_ = async_
216        self.defer = defer
217        self.nomodule = nomodule
218        self._src = self.uri()
219        if hash and self.crossorigin is None:
220            raise ValueError(
221                "If hash is set, crossorigin must be set to ''/'anonymous'"
222            )
223
224    def uri(self) -> str:
225        """
226        Returns the source URI - with cache busting if enabled
227        which is implemented by getting the mtime of the local file
228
229        This operation performs up to two fs stats per call
230
231        1. The base static directory is checked once and cached per interpreter
232        2. The specific resource is checked if it is time to poll again
233           based on settings.stat_poll_interval
234        """
235        if not self.cache_bust:
236            return self.source
237
238        return _cachebust_resource_uri(self.source)
239
240    def import_map_entry(self) -> _ImportMapEntry | None:
241        """
242        Returns a tuple of (name, source, scope_url) for use in an import map
243        """
244
245        if self.name:
246            if self.scope_urls is None:
247                return _ImportMapEntry(name=self.name, src=self._src)
248            else:
249                return _ImportMapEntry(
250                    name=self.name, src=self._src, scope_urls=self.scope_urls
251                )
252
253        return None
254
255    def preload_link(self) -> el.link | None:
256        """
257        Returns one or more link element for this import
258        """
259        if self.preload:
260            attrs = {"href": self._src}
261            if self.hash:
262                attrs["integrity"] = self.hash
263            if self.crossorigin:
264                attrs["crossorigin"] = self.crossorigin
265            if self.name:
266                return el.link(attrs=attrs, rel="modulepreload")
267            else:
268                return el.link(attrs=attrs, rel="preload", as_="script")
269
270        return None
271
272    def script(self) -> el.script:
273        """
274        Returns a script tag for this import
275        """
276        attrs: dict[str, str | bool] = {"src": self._src}
277
278        if self.name:
279            attrs["type"] = "module"
280        if self.hash:
281            attrs["integrity"] = self.hash
282        if self.crossorigin:
283            attrs["crossorigin"] = self.crossorigin
284        if self.async_:
285            attrs["async"] = True
286        if self.defer and not self.name:
287            # Only set defer for non-modules
288            attrs["defer"] = True
289        if self.nomodule:
290            attrs["nomodule"] = True
291
292        return el.script(attrs=attrs)

  8class css_import:
  9    """
 10    A css import helper class which employs:
 11    - `link(rel="stylesheet")` to define the import
 12    - `link(rel="preload")` to preload the import
 13    - `hash` and `crossorigin` for SRI
 14    - Local resource cache busting
 15
 16    An production usage might look like:
 17    ```python
 18    [
 19    css_import('./static/admin.css',
 20                cache_bust=True),
 21
 22    css_import(
 23        "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
 24        hash=(
 25            "sha384-9ndCyUaIbzAi2FUVXJi0CjmCapS"
 26            "mO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM"
 27            ),
 28        crossorigin="anonymous",
 29        preload=True
 30    )
 31
 32    ]
 33    ```
 34
 35    ## Generated "HTML":
 36
 37    ```python
 38    import json
 39    from html_compose import el
 40
 41    [
 42        link(rel='preload',
 43            href='https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css',
 44            as_='style',
 45            integrity='sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7'
 46            'SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM',
 47            crossorigin='anonymous'),
 48
 49        link(rel='stylesheet', href='./static/admin.css?ts=1760153426'),
 50
 51        link(rel='stylesheet',
 52            href='https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css',
 53            integrity='sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7'
 54            'SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM',
 55            crossorigin='anonymous')
 56    ]
 57    ```
 58
 59    See:
 60        https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/preload
 61        https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
 62        https://www.srihash.org/
 63
 64    """
 65
 66    def __init__(
 67        self,
 68        href: str,
 69        preload: bool = False,
 70        hash: str | None = None,
 71        crossorigin: Literal["", "anonymous", "user-credentials"]
 72        | str
 73        | None = None,
 74        cache_bust: bool = False,
 75    ):
 76        """
 77        A css import wrapper to wrap some of the complexity of optimal
 78        resource loading.
 79
 80
 81        Parameters
 82        ----------
 83        `href`:
 84            The literal href passed to the link tag
 85
 86        `preload`:
 87            If true, adds a preload link for this resource
 88
 89        `hash`:
 90            An optional SRI integrity hash for the import
 91
 92        `crossorigin`:
 93            Optionally sets the crossorigin attribute on the link tag.
 94            Valid values are "", "anonymous", "use-credentials"
 95
 96        `cache_bust`:
 97            If true, appends a timestamp to the URL to prevent browser
 98            caching. Webservers configured for static resources manage this
 99            feature automatically, but for development this can be useful.
100
101            This feature only works for local resources, i.e. those that
102            exist in `resource.settings.base_dir`
103
104        """
105        self.href = href
106        self.preload = preload
107        self.hash = hash
108        self.crossorigin = crossorigin
109        self.cache_bust = cache_bust
110        self.has_link = preload
111        self._href = self.uri()
112
113        if hash and self.crossorigin is None:
114            raise ValueError(
115                "If hash is set, crossorigin must be set to ''/'anonymous'"
116            )
117
118    def uri(self):
119        """
120        Returns the source URI - with cache busting if enabled
121        which is implemented by getting the mtime of the local file
122
123        This operation performs up to two fs stats per call
124
125        1. The base static directory is checked once and cached per interpreter
126        2. The specific resource is checked if it is time to poll again
127           based on settings.stat_poll_interval
128        """
129        if not self.cache_bust:
130            return self.href
131
132        return _cachebust_resource_uri(self.href)
133
134    def preloads(self) -> list[el.link]:
135        """
136        Returns a link element for preloading this import if preload is set
137        """
138        attrs = {"href": self._href}
139        if self.hash:
140            attrs["integrity"] = self.hash
141        if self.crossorigin:
142            attrs["crossorigin"] = self.crossorigin
143        if self.preload:
144            return [el.link(attrs=attrs, rel="preload", as_="style")]
145
146        return []
147
148    def links(self):
149        """
150        Returns one or more link element for this import
151        """
152        links = []
153        attrs = {"href": self._href}
154        if self.hash:
155            attrs["integrity"] = self.hash
156        if self.crossorigin:
157            attrs["crossorigin"] = self.crossorigin
158
159        links.append(el.link(attrs=attrs, rel="stylesheet"))
160
161        return links

 45class font_import_manual(_font_import_base):
 46    def __init__(
 47        self,
 48        hrefs: str | Iterable[str],
 49        family: str,
 50        weight: int
 51        | tuple
 52        | str
 53        | Literal["bold", "light", "lighter", "bolder", "normal"]
 54        | None = "normal",
 55        style: Literal["normal", "italic", "oblique"] | str = "normal",
 56        display: Literal["swap", "optional", "fallback", "auto", "block"]
 57        | str = "swap",
 58        preload: bool = True,
 59        crossorigin: Literal["", "anonymous", "use-credentials"] | None = None,
 60        unicode_range: str | None = None,
 61        cache_bust: bool = False,
 62    ) -> None:
 63        """
 64        Declare a web font via @font-face and (optionally) emit
 65        a preload `<link>`.
 66        This initializer targets the direct-file flow (you supply the exact .woff2 URL).
 67
 68        If multiple hrefs are provided, preload must choose only one and so
 69        the first href is used for preload and the rest are only
 70        in the @font-face.
 71
 72        Values are passed verbatim. NEVER use this with untrusted user input.
 73
 74        Parameters
 75        ----------
 76
 77        `hrefs`:
 78            1 or more URL to the font file (typically .woff2).
 79            Pass a str for a single URL, or an iterable of str for multiple URLs.
 80
 81            The @font-face `src` will reference this URL verbatim.
 82
 83        `family`:
 84            CSS `font-family` name to expose (e.g., "Noto Sans").
 85            Do not include quotes; they are added automatically.
 86
 87        `weight`:
 88            Single numeric weight (e.g., 400) for a static face, or a `(low, high)`
 89            tuple (e.g., `(100, 900)`) for a variable font range.
 90
 91        `style`:
 92            Font style for this face: `"normal"` or `"italic"`. Declare another
 93            instance for the other style if needed.
 94
 95        `display`:
 96            `font-display` strategy. `"swap"` is a safe default to avoid FOIT.
 97
 98        `preload`:
 99            If `True`, also create a `<link rel="preload" as="font" ...>` for `href`.
100            Preload only warms the fetch; the @font-face rule still does the actual use.
101
102        `crossorigin`:
103            CORS mode for cross-origin fonts. When unset, it is
104            fetched as same-origin Use `""` or `anonymous` for most CDN/remote
105            cases, or `"use-credentials"` to pass cookies if strictly necessary.
106
107        `unicode_range`:
108            Optional CSS `unicode-range` (e.g., `"U+0000-00FF"`) to subset coverage.
109        """
110        if isinstance(hrefs, str):
111            hrefs = [hrefs]
112        self.hrefs = hrefs
113        self.weight = weight
114        self.style = style
115        self.display = display
116        self.preload = preload
117        self.crossorigin = crossorigin
118        self.cache_bust = cache_bust
119        self.has_link = preload
120        self.unicode_range = unicode_range
121        self._hrefs = self.uris()
122
123        # Escape most stuff that could break out of quotes
124        safe_family = (
125            family.replace("\\", "\\\\").replace("'", "\\'").replace('"', '\\"')
126        )
127        self.family = safe_family
128
129    def uris(self) -> list[str]:  # -> list[str] | list[Any]:
130        """
131        Returns the source URI - with cache busting if enabled
132        which is implemented by getting the mtime of the local file
133
134        This operation performs up to two fs stats per call
135
136        1. The base static directory is checked once and cached per interpreter
137        2. The specific resource is checked if it is time to poll again
138           based on settings.stat_poll_interval
139        """
140        hrefs = []
141        for h in self.hrefs:
142            if not self.cache_bust:
143                hrefs.append(h)
144                continue
145
146            hrefs.append(_cachebust_resource_uri(h))
147        return hrefs
148
149    @staticmethod
150    def get_font_format(href: str) -> str | None:
151        ext = href.split(".")[-1].lower()
152        return _AUTODETECT_CSS_FONT_TYPES.get(ext, None)
153
154    @staticmethod
155    def get_font_mime(href: str) -> str | None:
156        ext = href.split(".")[-1].lower()
157        return _AUTODETECT_FONT_MIMETYPES.get(ext, None)
158
159    def preload_links(self) -> list[el.link]:
160        """
161        Returns preload links if preload is set
162        """
163        if not self.preload:
164            return []
165
166        first_href = self._hrefs[0]
167        attrs = {"href": first_href}
168
169        if self.crossorigin:
170            attrs["crossorigin"] = self.crossorigin
171
172        mimetype = font_import_manual.get_font_mime(first_href)
173
174        if mimetype:
175            attrs["type"] = mimetype
176
177        return [el.link(attrs=attrs, rel="preload", as_="font")]
178
179    def links(self) -> list[el.link]:
180        return []
181
182    def style_data(self) -> str:
183        """
184        Returns one or more nodes for this import
185        """
186
187        font_refs = []
188
189        if len(self._hrefs) == 1:
190            # we don't have to hint format if there's only one
191            font_refs.append(f"url('{self._hrefs[0]}')")
192        else:
193            for h in self._hrefs:
194                entry = f"url('{h}')"
195                format = font_import_manual.get_font_format(h)
196                if format:
197                    entry += f" format('{format}')"
198
199                font_refs.append(entry)
200
201        if isinstance(self.weight, tuple):
202            font_weight = f"{self.weight[0]} {self.weight[1]}"
203        elif isinstance(self.weight, str):
204            font_weight = self.weight
205        elif isinstance(self.weight, int):
206            font_weight = str(self.weight)
207        else:
208            raise TypeError("font weight must be int, str, or tuple")
209
210        style_attrs = {
211            "font-family": f"'{self.family}'",
212            "src": ",\n\t\t".join(font_refs),
213            "font-style": self.style,
214            "font-display": self.display,
215            "font-weight": font_weight,
216            "unicode-range": self.unicode_range,
217        }
218        for k in list(style_attrs.keys()):
219            v = style_attrs[k]
220            if v is None:
221                del style_attrs[k]
222
223        return "\n".join(
224            [
225                "@font-face {",
226                "".join(
227                    [
228                        "\t",
229                        ";\n\t".join(
230                            [f"{k}: {v}" for k, v in style_attrs.items()]
231                        ),
232                        ";",  # Ensure last property ends with semicolon
233                    ]
234                ),
235                "}",
236            ]
237        )
238
239    def preconnect_links(self) -> list[el.link]:
240        return []