html_compose.util_funcs

  1"""
  2Library utility functions
  3
  4Not intended to be used directly by library users.
  5"""
  6
  7import inspect
  8import json
  9from collections.abc import Iterable
 10from functools import lru_cache
 11from os import getenv
 12from pathlib import PurePath
 13from typing import Any, Generator
 14
 15
 16def join_attrs(k, value_trusted):
 17    """
 18    Join escaped value to key in form key="value"
 19    """
 20    return f'{k}="{value_trusted}"'
 21
 22
 23def is_iterable_but_not_str(input_iterable: Any) -> bool:
 24    """
 25    Check if an iterable is not a string or bytes.
 26    Which prevents some bugs.
 27    """
 28    return isinstance(input_iterable, Iterable) and not isinstance(
 29        input_iterable, (str, bytes)
 30    )
 31
 32
 33def flatten_iterable(input_iterable: Iterable) -> Generator[Any, None, None]:
 34    """
 35    Flatten an iterable of iterables into a single iterable
 36    """
 37    stack = [iter(input_iterable)]
 38
 39    while stack:
 40        try:
 41            # Get next element from top iterator on the stack
 42            current = next(stack[-1])
 43            if is_iterable_but_not_str(current):
 44                stack.append(
 45                    iter(current)
 46                )  # Push new iterator for the current iterable item
 47            else:
 48                # Item isn't iterator, yield it.
 49                yield current
 50        except StopIteration:
 51            # The iterator was exhausted
 52            stack.pop()
 53
 54
 55@lru_cache(maxsize=500)
 56def get_param_count(func):
 57    return len(inspect.signature(func).parameters)
 58
 59
 60def safe_name(name):
 61    """
 62    Some names are reserved in Python, so we need to add an underscore
 63    An underscore after was chosen so type hints match what user is looking for
 64    """
 65    # Keywords
 66    if name in ("class", "is", "for", "as", "async", "del"):
 67        name = name + "_"
 68
 69    if "-" in name:
 70        # Fixes for 'accept-charset' etc.
 71        name = name.replace("-", "_")
 72
 73    return name
 74
 75
 76def get_livereload_env() -> dict | None:
 77    enabled = getenv("HTMLCOMPOSE_LIVERELOAD") == "1"
 78    if not enabled:
 79        return None
 80    flags = getenv("HTMLCOMPOSE_LIVERELOAD_FLAGS")
 81    if not flags:
 82        return None
 83    try:
 84        return json.loads(flags)
 85    except json.JSONDecodeError:
 86        raise ValueError("Invalid JSON in HTMLCOMPOSE_LIVERELOAD_FLAGS")
 87
 88
 89def generate_livereload_env(
 90    host: str, port: int, proxy_host: str | None, proxy_uri: str | None = None
 91) -> dict:
 92    flags = {
 93        "port": port,
 94        "host": host,
 95        "proxy_host": proxy_host,
 96        "proxy_uri": proxy_uri,
 97    }
 98    return {
 99        "HTMLCOMPOSE_LIVERELOAD_FLAGS": json.dumps(flags),
100        "HTMLCOMPOSE_LIVERELOAD": "1",
101    }
102
103
104def glob_matcher(pattern, path):
105    """
106    Implementation of glob matcher which supports:
107      recursive globbing i.e. **
108      dir name matching via trailing /
109
110    Notes:
111      In Python 3.13 PurePath implemented full_match, but we don't
112      have that in 3.10.
113    """
114    pure_path = PurePath(path)
115    pure_pattern = PurePath(pattern)
116    path_parts = pure_path.parts
117    glob_parts = pure_pattern.parts
118    is_double_star = "**" in pattern
119
120    def _segment_match(pattern_segment, path_segment):
121        """Match a single path segment against a pattern segment."""
122        # fnmatch doesn't handle asterisk matching quite the same,
123        # so we use PurePath.match for * and? patterns.
124        return PurePath(path_segment).match(pattern_segment)
125
126    def _section_match(
127        pattern_segment: tuple, path_section: tuple, terminates=False
128    ):
129        """
130        Match a single path segment against a pattern segment.
131        Uses PurePath's match for * and ? patterns.
132
133        :param pattern_segment: A tuple of pattern segments.
134        :type pattern_segment: tuple
135        :param path_section: A tuple of path segments.
136        :type path_section: tuple
137        :return: Whether pattern_segment completely matches path_section.
138                 If terminates is True, pattern_segment must match to the end
139                 of path_section instead of just the size of the pattern
140        :rtype: bool
141        """
142        if len(pattern_segment) > len(path_section):
143            return False
144
145        if terminates and (len(pattern_segment) != len(path_section)):
146            return False
147
148        # We match segment by segment because PurePath will do weird generalizations
149        # such as matching "*.txt" against dir/file.txt
150        for i, seg in enumerate(pattern_segment):
151            if not _segment_match(seg, path_section[i]):
152                return False
153
154        return True
155
156    # Simple: We can just match the path_parts against the glob_parts
157    if not is_double_star:
158        if pattern.endswith("/"):
159            last_section = path_parts[0 : len(glob_parts)]
160            return _section_match(glob_parts, last_section, terminates=False)
161
162        return _section_match(glob_parts, path_parts, terminates=True)
163
164    # Oops, there's a double star.
165    # Build lists split on **
166    glob_sections = []
167    glob_section = []
168
169    for part in glob_parts:
170        if part == "**":
171            glob_sections.append(glob_section)
172            glob_section = []
173        else:
174            glob_section.append(part)
175
176    if glob_section:
177        glob_sections.append(glob_section)
178
179    j = 0
180    for i, current in enumerate(glob_sections):
181        is_last_glob = i == len(glob_sections) - 1
182        term = is_last_glob and not pattern.endswith("/")
183        matched = False
184        while j < len(path_parts):
185            if _section_match(current, path_parts[j:], terminates=term):
186                matched = True
187                break
188            if i > 0:
189                j += 1
190            else:
191                break
192        if not matched:
193            return False
194    return True