html_compose.resource.css_import

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