django_components ¤

@classmethod
def as_view(cls, **initkwargs: Any) -> ViewFn:
    """
    Shortcut for calling `Component.View.as_view` and passing component instance to it.
    """
    # This method may be called as class method or as instance method.
    # If called as class method, create a new instance.
    if isinstance(cls, Component):
        comp: Component = cls
    else:
        comp = cls()

    # Allow the View class to access this component via `self.component`
    return comp.View.as_view(**initkwargs, component=comp)

def get_template(self, context: Context) -> Optional[Union[str, Template]]:
    """
    Inlined Django template associated with this component. Can be a plain string or a Template instance.

    Only one of `template_name`, `get_template_name`, `template` or `get_template` must be defined.
    """
    return None

def get_template_name(self, context: Context) -> Optional[str]:
    """
    Filepath to the Django template associated with this component.

    The filepath must be relative to either the file where the component class was defined,
    or one of the roots of `STATIFILES_DIRS`.

    Only one of `template_name`, `get_template_name`, `template` or `get_template` must be defined.
    """
    return None

def inject(self, key: str, default: Optional[Any] = None) -> Any:
    """
    Use this method to retrieve the data that was passed to a `{% provide %}` tag
    with the corresponding key.

    To retrieve the data, `inject()` must be called inside a component that's
    inside the `{% provide %}` tag.

    You may also pass a default that will be used if the `provide` tag with given
    key was NOT found.

    This method mut be used inside the `get_context_data()` method and raises
    an error if called elsewhere.

    Example:

    Given this template:
    ```django
    {% provide "provider" hello="world" %}
        {% component "my_comp" %}
        {% endcomponent %}
    {% endprovide %}
    ```

    And given this definition of "my_comp" component:
    ```py
    from django_components import Component, register

    @register("my_comp")
    class MyComp(Component):
        template = "hi {{ data.hello }}!"
        def get_context_data(self):
            data = self.inject("provider")
            return {"data": data}
    ```

    This renders into:
    ```
    hi world!
    ```

    As the `{{ data.hello }}` is taken from the "provider".
    """
    if self.input is None:
        raise RuntimeError(
            f"Method 'inject()' of component '{self.name}' was called outside of 'get_context_data()'"
        )

    return get_injected_context_var(self.name, self.input.context, key, default)

def on_render_after(self, context: Context, template: Template, content: str) -> Optional[SlotResult]:
    """
    Hook that runs just after the component's template was rendered.
    It receives the rendered output as the last argument.

    You can use this hook to access the context or the template, but modifying
    them won't have any effect.

    To override the content that gets rendered, you can return a string or SafeString
    from this hook.
    """
    pass

def on_render_before(self, context: Context, template: Template) -> None:
    """
    Hook that runs just before the component's template is rendered.

    You can use this hook to access or modify the context or the template.
    """
    pass

@classmethod
def render(
    cls,
    context: Optional[Union[Dict[str, Any], Context]] = None,
    args: Optional[ArgsType] = None,
    kwargs: Optional[KwargsType] = None,
    slots: Optional[SlotsType] = None,
    escape_slots_content: bool = True,
    type: RenderType = "document",
    render_dependencies: bool = True,
) -> str:
    """
    Render the component into a string.

    Inputs:
    - `args` - Positional args for the component. This is the same as calling the component
      as `{% component "my_comp" arg1 arg2 ... %}`
    - `kwargs` - Kwargs for the component. This is the same as calling the component
      as `{% component "my_comp" key1=val1 key2=val2 ... %}`
    - `slots` - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
        Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
        or render function.
    - `escape_slots_content` - Whether the content from `slots` should be escaped.
    - `context` - A context (dictionary or Django's Context) within which the component
      is rendered. The keys on the context can be accessed from within the template.
        - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
          component's args and kwargs.
    - `type` - Configure how to handle JS and CSS dependencies.
        - `"document"` (default) - JS dependencies are inserted into `{% component_js_dependencies %}`,
          or to the end of the `<body>` tag. CSS dependencies are inserted into
          `{% component_css_dependencies %}`, or the end of the `<head>` tag.
    - `render_dependencies` - Set this to `False` if you want to insert the resulting HTML into another component.

    Example:
    ```py
    MyComponent.render(
        args=[1, "two", {}],
        kwargs={
            "key": 123,
        },
        slots={
            "header": 'STATIC TEXT HERE',
            "footer": lambda ctx, slot_kwargs, slot_ref: f'CTX: {ctx['hello']} SLOT_DATA: {slot_kwargs['abc']}',
        },
        escape_slots_content=False,
    )
    ```
    """
    # This method may be called as class method or as instance method.
    # If called as class method, create a new instance.
    if isinstance(cls, Component):
        comp: Component = cls
    else:
        comp = cls()

    return comp._render(context, args, kwargs, slots, escape_slots_content, type, render_dependencies)

@classmethod
def render_to_response(
    cls,
    context: Optional[Union[Dict[str, Any], Context]] = None,
    slots: Optional[SlotsType] = None,
    escape_slots_content: bool = True,
    args: Optional[ArgsType] = None,
    kwargs: Optional[KwargsType] = None,
    type: RenderType = "document",
    *response_args: Any,
    **response_kwargs: Any,
) -> HttpResponse:
    """
    Render the component and wrap the content in the response class.

    The response class is taken from `Component.response_class`. Defaults to `django.http.HttpResponse`.

    This is the interface for the `django.views.View` class which allows us to
    use components as Django views with `component.as_view()`.

    Inputs:
    - `args` - Positional args for the component. This is the same as calling the component
      as `{% component "my_comp" arg1 arg2 ... %}`
    - `kwargs` - Kwargs for the component. This is the same as calling the component
      as `{% component "my_comp" key1=val1 key2=val2 ... %}`
    - `slots` - Component slot fills. This is the same as pasing `{% fill %}` tags to the component.
        Accepts a dictionary of `{ slot_name: slot_content }` where `slot_content` can be a string
        or render function.
    - `escape_slots_content` - Whether the content from `slots` should be escaped.
    - `context` - A context (dictionary or Django's Context) within which the component
      is rendered. The keys on the context can be accessed from within the template.
        - NOTE: In "isolated" mode, context is NOT accessible, and data MUST be passed via
          component's args and kwargs.
    - `type` - Configure how to handle JS and CSS dependencies.
        - `"document"` (default) - JS dependencies are inserted into `{% component_js_dependencies %}`,
          or to the end of the `<body>` tag. CSS dependencies are inserted into
          `{% component_css_dependencies %}`, or the end of the `<head>` tag.

    Any additional args and kwargs are passed to the `response_class`.

    Example:
    ```py
    MyComponent.render_to_response(
        args=[1, "two", {}],
        kwargs={
            "key": 123,
        },
        slots={
            "header": 'STATIC TEXT HERE',
            "footer": lambda ctx, slot_kwargs, slot_ref: f'CTX: {ctx['hello']} SLOT_DATA: {slot_kwargs['abc']}',
        },
        escape_slots_content=False,
        # HttpResponse input
        status=201,
        headers={...},
    )
    # HttpResponse(content=..., status=201, headers=...)
    ```
    """
    content = cls.render(
        args=args,
        kwargs=kwargs,
        context=context,
        slots=slots,
        escape_slots_content=escape_slots_content,
        type=type,
        render_dependencies=True,
    )
    return cls.response_class(content, *response_args, **response_kwargs)

def all(self) -> Dict[str, Type["Component"]]:
    """
    Retrieve all registered [`Component`](../api#django_components.Component) classes.

    Returns:
        Dict[str, Type[Component]]: A dictionary of component names to component classes

    **Example:**

    ```python
    # First register components
    registry.register("button", ButtonComponent)
    registry.register("card", CardComponent)
    # Then get all
    registry.all()
    # > {
    # >   "button": ButtonComponent,
    # >   "card": CardComponent,
    # > }
    ```
    """
    comps = {key: entry.cls for key, entry in self._registry.items()}
    return comps

def clear(self) -> None:
    """
    Clears the registry, unregistering all components.

    Example:

    ```python
    # First register components
    registry.register("button", ButtonComponent)
    registry.register("card", CardComponent)
    # Then clear
    registry.clear()
    # Then get all
    registry.all()
    # > {}
    ```
    """
    all_comp_names = list(self._registry.keys())
    for comp_name in all_comp_names:
        self.unregister(comp_name)

    self._registry = {}
    self._tags = {}

def get(self, name: str) -> Type["Component"]:
    """
    Retrieve a [`Component`](../api#django_components.Component)
    class registered under the given name.

    Args:
        name (str): The name under which the component was registered. Required.

    Returns:
        Type[Component]: The component class registered under the given name.

    **Raises:**

    - [`NotRegistered`](../exceptions#django_components.NotRegistered)
      if the given name is not registered.

    **Example:**

    ```python
    # First register component
    registry.register("button", ButtonComponent)
    # Then get
    registry.get("button")
    # > ButtonComponent
    ```
    """
    if name not in self._registry:
        raise NotRegistered('The component "%s" is not registered' % name)

    return self._registry[name].cls

def register(self, name: str, component: Type["Component"]) -> None:
    """
    Register a [`Component`](../api#django_components.Component) class
    with this registry under the given name.

    A component MUST be registered before it can be used in a template such as:
    ```django
    {% component "my_comp" %}
    {% endcomponent %}
    ```

    Args:
        name (str): The name under which the component will be registered. Required.
        component (Type[Component]): The component class to register. Required.

    **Raises:**

    - [`AlreadyRegistered`](../exceptions#django_components.AlreadyRegistered)
    if a different component was already registered under the same name.

    **Example:**

    ```python
    registry.register("button", ButtonComponent)
    ```
    """
    existing_component = self._registry.get(name)
    if existing_component and existing_component.cls._class_hash != component._class_hash:
        raise AlreadyRegistered('The component "%s" has already been registered' % name)

    entry = self._register_to_library(name, component)

    # Keep track of which components use which tags, because multiple components may
    # use the same tag.
    tag = entry.tag
    if tag not in self._tags:
        self._tags[tag] = set()
    self._tags[tag].add(name)

    self._registry[name] = entry

def unregister(self, name: str) -> None:
    """
    Unregister the [`Component`](../api#django_components.Component) class
    that was registered under the given name.

    Once a component is unregistered, it is no longer available in the templates.

    Args:
        name (str): The name under which the component is registered. Required.

    **Raises:**

    - [`NotRegistered`](../exceptions#django_components.NotRegistered)
    if the given name is not registered.

    **Example:**

    ```python
    # First register component
    registry.register("button", ButtonComponent)
    # Then unregister
    registry.unregister("button")
    ```
    """
    # Validate
    self.get(name)

    entry = self._registry[name]
    tag = entry.tag

    # Unregister the tag from library if this was the last component using this tag
    # Unlink component from tag
    self._tags[tag].remove(name)

    # Cleanup
    is_tag_empty = not len(self._tags[tag])
    if is_tag_empty:
        del self._tags[tag]

    # Only unregister a tag if it's NOT protected
    is_protected = is_tag_protected(self.library, tag)
    if not is_protected:
        # Unregister the tag from library if this was the last component using this tag
        if is_tag_empty and tag in self.library.tags:
            del self.library.tags[tag]

    del self._registry[name]