util ¤

Modules:

cache –
html –
loader –
logger –
misc –
tag_parser –
types –

cache ¤

Functions:

lazy_cache –

Decorator that caches the given function similarly to functools.lru_cache.

lazy_cache ¤

lazy_cache(make_cache: Callable[[], Callable[[Callable], Callable]]) -> Callable[[TFunc], TFunc]

Decorator that caches the given function similarly to functools.lru_cache. But the cache is instantiated only at first invocation.

cache argument is a function that generates the cache function, e.g. functools.lru_cache().

Source code in src/django_components/util/cache.py

def lazy_cache(
    make_cache: Callable[[], Callable[[Callable], Callable]],
) -> Callable[[TFunc], TFunc]:
    """
    Decorator that caches the given function similarly to `functools.lru_cache`.
    But the cache is instantiated only at first invocation.

    `cache` argument is a function that generates the cache function,
    e.g. `functools.lru_cache()`.
    """
    _cached_fn = None

    def decorator(fn: TFunc) -> TFunc:
        @functools.wraps(fn)
        def wrapper(*args: Any, **kwargs: Any) -> Any:
            # Lazily initialize the cache
            nonlocal _cached_fn
            if not _cached_fn:
                # E.g. `lambda: functools.lru_cache(maxsize=app_settings.TEMPLATE_CACHE_SIZE)`
                cache = make_cache()
                _cached_fn = cache(fn)

            return _cached_fn(*args, **kwargs)

        # Allow to access the LRU cache methods
        # See https://stackoverflow.com/a/37654201/9788634
        wrapper.cache_info = lambda: _cached_fn.cache_info()  # type: ignore
        wrapper.cache_clear = lambda: _cached_fn.cache_clear()  # type: ignore

        # And allow to remove the cache instance (mostly for tests)
        def cache_remove() -> None:
            nonlocal _cached_fn
            _cached_fn = None

        wrapper.cache_remove = cache_remove  # type: ignore

        return cast(TFunc, wrapper)

    return decorator

html ¤

Functions:

parse_document_or_nodes –

Use this if you do NOT know whether the given HTML is a full document
parse_multiroot_html –

Use this when you know the given HTML is a multiple nodes like
parse_node –

Use this when you know the given HTML is a single node like

parse_document_or_nodes ¤

parse_document_or_nodes(html: str) -> Union[List[LexborNode], LexborHTMLParser]

Use this if you do NOT know whether the given HTML is a full document with <html>, <head>, and <body> tags, or an HTML fragment.

Source code in src/django_components/util/html.py

def parse_document_or_nodes(html: str) -> Union[List[LexborNode], LexborHTMLParser]:
    """
    Use this if you do NOT know whether the given HTML is a full document
    with `<html>`, `<head>`, and `<body>` tags, or an HTML fragment.
    """
    html = html.strip()
    tree = LexborHTMLParser(html)
    is_fragment = is_html_parser_fragment(html, tree)

    if is_fragment:
        nodes = parse_multiroot_html(html)
        return nodes
    else:
        return tree

parse_multiroot_html ¤

parse_multiroot_html(html: str) -> List[LexborNode]

Use this when you know the given HTML is a multiple nodes like

<div> Hi </div> <span> Hello </span>

Source code in src/django_components/util/html.py

def parse_multiroot_html(html: str) -> List[LexborNode]:
    """
    Use this when you know the given HTML is a multiple nodes like

    `<div> Hi </div> <span> Hello </span>`
    """
    # NOTE: HTML / XML MUST have a single root. So, to support multiple
    # top-level elements, we wrap them in a dummy singular root.
    parser = LexborHTMLParser(f"<root>{html}</root>")

    # Get all contents of the root
    root_elem = parser.css_first("root")
    elems = [*root_elem.iter()] if root_elem else []
    return elems

parse_node ¤

parse_node(html: str) -> LexborNode

Use this when you know the given HTML is a single node like

<div> Hi </div>

Source code in src/django_components/util/html.py

def parse_node(html: str) -> LexborNode:
    """
    Use this when you know the given HTML is a single node like

    `<div> Hi </div>`
    """
    tree = LexborHTMLParser(html)
    # NOTE: The parser automatically places <style> tags inside <head>
    # while <script> tags are inside <body>.
    return tree.body.child or tree.head.child  # type: ignore[union-attr, return-value]

loader ¤

Classes:

ComponentFileEntry –

Result returned by get_component_files().

Functions:

get_component_dirs –

Get directories that may contain component files.
get_component_files –

Search for files within the component directories (as defined in

ComponentFileEntry ¤

Bases: NamedTuple

Result returned by get_component_files().

Attributes:

dot_path (str) –

The python import path for the module. E.g. app.components.mycomp
filepath (Path) –

The filesystem path to the module. E.g. /path/to/project/app/components/mycomp.py

dot_path `instance-attribute` ¤

dot_path: str

The python import path for the module. E.g. app.components.mycomp

filepath `instance-attribute` ¤

filepath: Path

The filesystem path to the module. E.g. /path/to/project/app/components/mycomp.py

get_component_dirs ¤

get_component_dirs(include_apps: bool = True) -> List[Path]

Get directories that may contain component files.

This is the heart of all features that deal with filesystem and file lookup. Autodiscovery, Django template resolution, static file resolution - They all use this.

Parameters:

include_apps (bool, default: True ) –

Include directories from installed Django apps. Defaults to True.

Returns:

List[Path] –

List[Path]: A list of directories that may contain component files.

get_component_dirs() searches for dirs set in COMPONENTS.dirs settings. If none set, defaults to searching for a "components" app.

In addition to that, also all installed Django apps are checked whether they contain directories as set in COMPONENTS.app_dirs (e.g. [app]/components).

Notes:

Paths that do not point to directories are ignored.
BASE_DIR setting is required.
The paths in COMPONENTS.dirs must be absolute paths.

Source code in src/django_components/util/loader.py

def get_component_dirs(include_apps: bool = True) -> List[Path]:
    """
    Get directories that may contain component files.

    This is the heart of all features that deal with filesystem and file lookup.
    Autodiscovery, Django template resolution, static file resolution - They all use this.

    Args:
        include_apps (bool, optional): Include directories from installed Django apps.\
            Defaults to `True`.

    Returns:
        List[Path]: A list of directories that may contain component files.

    `get_component_dirs()` searches for dirs set in
    [`COMPONENTS.dirs`](../settings#django_components.app_settings.ComponentsSettings.dirs)
    settings. If none set, defaults to searching for a `"components"` app.

    In addition to that, also all installed Django apps are checked whether they contain
    directories as set in
    [`COMPONENTS.app_dirs`](../settings#django_components.app_settings.ComponentsSettings.app_dirs)
    (e.g. `[app]/components`).

    **Notes:**

    - Paths that do not point to directories are ignored.

    - `BASE_DIR` setting is required.

    - The paths in [`COMPONENTS.dirs`](../settings#django_components.app_settings.ComponentsSettings.dirs)
        must be absolute paths.
    """
    # Allow to configure from settings which dirs should be checked for components
    component_dirs = app_settings.DIRS

    # TODO_REMOVE_IN_V1
    raw_component_settings = getattr(settings, "COMPONENTS", {})
    if isinstance(raw_component_settings, dict):
        raw_dirs_value = raw_component_settings.get("dirs", None)
    elif isinstance(raw_component_settings, ComponentsSettings):
        raw_dirs_value = raw_component_settings.dirs
    else:
        raw_dirs_value = None
    is_component_dirs_set = raw_dirs_value is not None
    is_legacy_paths = (
        # Use value of `STATICFILES_DIRS` ONLY if `COMPONENT.dirs` not set
        not is_component_dirs_set
        and hasattr(settings, "STATICFILES_DIRS")
        and settings.STATICFILES_DIRS
    )
    if is_legacy_paths:
        # NOTE: For STATICFILES_DIRS, we use the defaults even for empty list.
        # We don't do this for COMPONENTS.dirs, so user can explicitly specify "NO dirs".
        component_dirs = settings.STATICFILES_DIRS or [settings.BASE_DIR / "components"]
    # END TODO_REMOVE_IN_V1

    source = "STATICFILES_DIRS" if is_legacy_paths else "COMPONENTS.dirs"

    logger.debug(
        "get_component_dirs will search for valid dirs from following options:\n"
        + "\n".join([f" - {str(d)}" for d in component_dirs])
    )

    # Add `[app]/[APP_DIR]` to the directories. This is, by default `[app]/components`
    app_paths: List[Path] = []
    if include_apps:
        for conf in apps.get_app_configs():
            for app_dir in app_settings.APP_DIRS:
                comps_path = Path(conf.path).joinpath(app_dir)
                if comps_path.exists():
                    app_paths.append(comps_path)

    directories: Set[Path] = set(app_paths)

    # Validate and add other values from the config
    for component_dir in component_dirs:
        # Consider tuples for STATICFILES_DIRS (See #489)
        # See https://docs.djangoproject.com/en/5.0/ref/settings/#prefixes-optional
        if isinstance(component_dir, (tuple, list)):
            component_dir = component_dir[1]
        try:
            Path(component_dir)
        except TypeError:
            logger.warning(
                f"{source} expected str, bytes or os.PathLike object, or tuple/list of length 2. "
                f"See Django documentation for STATICFILES_DIRS. Got {type(component_dir)} : {component_dir}"
            )
            continue

        if not Path(component_dir).is_absolute():
            raise ValueError(f"{source} must contain absolute paths, got '{component_dir}'")
        else:
            directories.add(Path(component_dir).resolve())

    logger.debug(
        "get_component_dirs matched following template dirs:\n" + "\n".join([f" - {str(d)}" for d in directories])
    )
    return list(directories)

get_component_files ¤

get_component_files(suffix: Optional[str] = None) -> List[ComponentFileEntry]

Search for files within the component directories (as defined in get_component_dirs()).

Requires BASE_DIR setting to be set.

Parameters:

suffix (Optional[str], default: None ) –

The suffix to search for. E.g. .py, .js, .css. Defaults to None, which will search for all files.

Returns:

List[ComponentFileEntry] –

List[ComponentFileEntry] A list of entries that contain both the filesystem path and the python import path (dot path).

Example:

from django_components import get_component_files

modules = get_component_files(".py")

Source code in src/django_components/util/loader.py

def get_component_files(suffix: Optional[str] = None) -> List[ComponentFileEntry]:
    """
    Search for files within the component directories (as defined in
    [`get_component_dirs()`](../api#django_components.get_component_dirs)).

    Requires `BASE_DIR` setting to be set.

    Args:
        suffix (Optional[str], optional): The suffix to search for. E.g. `.py`, `.js`, `.css`.\
            Defaults to `None`, which will search for all files.

    Returns:
        List[ComponentFileEntry] A list of entries that contain both the filesystem path and \
            the python import path (dot path).

    **Example:**

    ```python
    from django_components import get_component_files

    modules = get_component_files(".py")
    ```
    """
    search_glob = f"**/*{suffix}" if suffix else "**/*"

    dirs = get_component_dirs(include_apps=False)
    component_filepaths = _search_dirs(dirs, search_glob)

    if hasattr(settings, "BASE_DIR") and settings.BASE_DIR:
        project_root = str(settings.BASE_DIR)
    else:
        # Fallback for getting the root dir, see https://stackoverflow.com/a/16413955/9788634
        project_root = os.path.abspath(os.path.dirname(__name__))

    # NOTE: We handle dirs from `COMPONENTS.dirs` and from individual apps separately.
    modules: List[ComponentFileEntry] = []

    # First let's handle the dirs from `COMPONENTS.dirs`
    #
    # Because for dirs in `COMPONENTS.dirs`, we assume they will be nested under `BASE_DIR`,
    # and that `BASE_DIR` is the current working dir (CWD). So the path relatively to `BASE_DIR`
    # is ALSO the python import path.
    for filepath in component_filepaths:
        module_path = _filepath_to_python_module(filepath, project_root, None)
        # Ignore files starting with dot `.` or files in dirs that start with dot.
        #
        # If any of the parts of the path start with a dot, e.g. the filesystem path
        # is `./abc/.def`, then this gets converted to python module as `abc..def`
        #
        # NOTE: This approach also ignores files:
        #   - with two dots in the middle (ab..cd.py)
        #   - an extra dot at the end (abcd..py)
        #   - files outside of the parent component (../abcd.py).
        # But all these are NOT valid python modules so that's fine.
        if ".." in module_path:
            continue

        entry = ComponentFileEntry(dot_path=module_path, filepath=filepath)
        modules.append(entry)

    # For for apps, the directories may be outside of the project, e.g. in case of third party
    # apps. So we have to resolve the python import path relative to the package name / the root
    # import path for the app.
    # See https://github.com/EmilStenstrom/django-components/issues/669
    for conf in apps.get_app_configs():
        for app_dir in app_settings.APP_DIRS:
            comps_path = Path(conf.path).joinpath(app_dir)
            if not comps_path.exists():
                continue
            app_component_filepaths = _search_dirs([comps_path], search_glob)
            for filepath in app_component_filepaths:
                app_component_module = _filepath_to_python_module(filepath, conf.path, conf.name)
                entry = ComponentFileEntry(dot_path=app_component_module, filepath=filepath)
                modules.append(entry)

    return modules

logger ¤

Functions:

trace –

TRACE level logger.
trace_msg –

TRACE level logger with opinionated format for tracing interaction of components,

trace ¤

trace(logger: Logger, message: str, *args: Any, **kwargs: Any) -> None

TRACE level logger.

To display TRACE logs, set the logging level to 5.

Example:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "stream": sys.stdout,
        },
    },
    "loggers": {
        "django_components": {
            "level": 5,
            "handlers": ["console"],
        },
    },
}

Source code in src/django_components/util/logger.py

def trace(logger: logging.Logger, message: str, *args: Any, **kwargs: Any) -> None:
    """
    TRACE level logger.

    To display TRACE logs, set the logging level to 5.

    Example:
    ```py
    LOGGING = {
        "version": 1,
        "disable_existing_loggers": False,
        "handlers": {
            "console": {
                "class": "logging.StreamHandler",
                "stream": sys.stdout,
            },
        },
        "loggers": {
            "django_components": {
                "level": 5,
                "handlers": ["console"],
            },
        },
    }
    ```
    """
    if actual_trace_level_num == -1:
        setup_logging()
    if logger.isEnabledFor(actual_trace_level_num):
        logger.log(actual_trace_level_num, message, *args, **kwargs)

trace_msg ¤

trace_msg(
    action: Literal["PARSE", "RENDR", "GET", "SET"],
    node_type: Literal["COMP", "FILL", "SLOT", "PROVIDE", "N/A"],
    node_name: str,
    node_id: str,
    msg: str = "",
    component_id: Optional[str] = None,
) -> None

TRACE level logger with opinionated format for tracing interaction of components, nodes, and slots. Formats messages like so:

"ASSOC SLOT test_slot ID 0088 TO COMP 0087"

Source code in src/django_components/util/logger.py

def trace_msg(
    action: Literal["PARSE", "RENDR", "GET", "SET"],
    node_type: Literal["COMP", "FILL", "SLOT", "PROVIDE", "N/A"],
    node_name: str,
    node_id: str,
    msg: str = "",
    component_id: Optional[str] = None,
) -> None:
    """
    TRACE level logger with opinionated format for tracing interaction of components,
    nodes, and slots. Formats messages like so:

    `"ASSOC SLOT test_slot ID 0088 TO COMP 0087"`
    """
    msg_prefix = ""
    if action == "RENDR" and node_type == "FILL":
        if not component_id:
            raise ValueError("component_id must be set for the RENDER action")
        msg_prefix = f"FOR COMP {component_id}"

    msg_parts = [f"{action} {node_type} {node_name} ID {node_id}", *([msg_prefix] if msg_prefix else []), msg]
    full_msg = " ".join(msg_parts)

    # NOTE: When debugging tests during development, it may be easier to change
    # this to `print()`
    trace(logger, full_msg)

misc ¤

Functions:

gen_id –

Generate a unique ID that can be associated with a Node
get_import_path –

Get the full import path for a class or a function, e.g. "path.to.MyClass"

gen_id ¤

gen_id() -> str

Generate a unique ID that can be associated with a Node

Source code in src/django_components/util/misc.py

def gen_id() -> str:
    """Generate a unique ID that can be associated with a Node"""
    # Alphabet is only alphanumeric. Compared to the default alphabet used by nanoid,
    # we've omitted `-` and `_`.
    # With this alphabet, at 6 chars, the chance of collision is 1 in 3.3M.
    # See https://zelark.github.io/nano-id-cc/
    return generate(
        "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
        size=6,
    )

get_import_path ¤

get_import_path(cls_or_fn: Type[Any]) -> str

Get the full import path for a class or a function, e.g. "path.to.MyClass"

Source code in src/django_components/util/misc.py

def get_import_path(cls_or_fn: Type[Any]) -> str:
    """
    Get the full import path for a class or a function, e.g. `"path.to.MyClass"`
    """
    module = cls_or_fn.__module__
    if module == "builtins":
        return cls_or_fn.__qualname__  # avoid outputs like 'builtins.str'
    return module + "." + cls_or_fn.__qualname__

tag_parser ¤

Classes:

TagAttr –

TagAttr `dataclass` ¤

TagAttr(key: Optional[str], value: str, start_index: int, quoted: bool)

Attributes:

quoted (bool) –

Whether the value is quoted (either with single or double quotes)
start_index (int) –

Start index of the attribute (include both key and value),

quoted `instance-attribute` ¤

quoted: bool

Whether the value is quoted (either with single or double quotes)

start_index `instance-attribute` ¤

start_index: int

Start index of the attribute (include both key and value), relative to the start of the owner Tag.

types ¤

Classes:

EmptyDict –

TypedDict with no members.

Attributes:

EmptyTuple –

Tuple with no members.

EmptyTuple `module-attribute` ¤

EmptyTuple = Tuple[]

Tuple with no members.

You can use this to define a Component that accepts NO positional arguments:

from django_components import Component, EmptyTuple

class Table(Component(EmptyTuple, Any, Any, Any, Any, Any))
    ...

After that, when you call Component.render() or Component.render_to_response(), the args parameter will raise type error if args is anything else than an empty tuple.

Table.render(
    args: (),
)

Omitting args is also fine:

Table.render()

Other values are not allowed. This will raise an error with MyPy:

Table.render(
    args: ("one", 2, "three"),
)

EmptyDict ¤

Bases: TypedDict

TypedDict with no members.

You can use this to define a Component that accepts NO kwargs, or NO slots, or returns NO data from Component.get_context_data() / Component.get_js_data() / Component.get_css_data():

Accepts NO kwargs:

from django_components import Component, EmptyDict

class Table(Component(Any, EmptyDict, Any, Any, Any, Any))
    ...

Accepts NO slots:

from django_components import Component, EmptyDict

class Table(Component(Any, Any, EmptyDict, Any, Any, Any))
    ...

Returns NO data from get_context_data():

from django_components import Component, EmptyDict

class Table(Component(Any, Any, Any, EmptyDict, Any, Any))
    ...

Going back to the example with NO kwargs, when you then call Component.render() or Component.render_to_response(), the kwargs parameter will raise type error if kwargs is anything else than an empty dict.

Table.render(
    kwargs: {},
)

Omitting kwargs is also fine:

Table.render()

Other values are not allowed. This will raise an error with MyPy:

Table.render(
    kwargs: {
        "one": 2,
        "three": 4,
    },
)

util ¤

cache ¤

lazy_cache ¤

html ¤

parse_document_or_nodes ¤

parse_multiroot_html ¤

parse_node ¤

loader ¤

ComponentFileEntry ¤

dot_path instance-attribute ¤

filepath instance-attribute ¤

get_component_dirs ¤

get_component_files ¤

logger ¤

trace ¤

trace_msg ¤

misc ¤

gen_id ¤

get_import_path ¤

tag_parser ¤

TagAttr dataclass ¤

quoted instance-attribute ¤

start_index instance-attribute ¤

types ¤

EmptyTuple module-attribute ¤

EmptyDict ¤

dot_path `instance-attribute` ¤

filepath `instance-attribute` ¤

TagAttr `dataclass` ¤

quoted `instance-attribute` ¤

start_index `instance-attribute` ¤

EmptyTuple `module-attribute` ¤