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,
) -> 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.

    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)

def render_css_dependencies(self) -> SafeString:
    """Render only CSS dependencies available in the media class or provided as a string."""
    if self.css is not None:
        return mark_safe(f"<style>{self.css}</style>")
    return mark_safe("\n".join(self.media.render_css()))

def render_dependencies(self) -> SafeString:
    """Helper function to render all dependencies for a component."""
    dependencies = []

    css_deps = self.render_css_dependencies()
    if css_deps:
        dependencies.append(css_deps)

    js_deps = self.render_js_dependencies()
    if js_deps:
        dependencies.append(js_deps)

    return mark_safe("\n".join(dependencies))

def render_js_dependencies(self) -> SafeString:
    """Render only JS dependencies available in the media class or provided as a string."""
    if self.js is not None:
        return mark_safe(f"<script>{self.js}</script>")
    return mark_safe("\n".join(self.media.render_js()))

@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,
    *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.

    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,
    )
    return cls.response_class(content, *response_args, **response_kwargs)

def all(self) -> Dict[str, Type["Component"]]:
    """
    Retrieve all registered component classes.

    Example:

    ```py
    # 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:

    ```py
    # 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 class registered under the given name.

    Raises `NotRegistered` if the given name is not registered.

    Example:

    ```py
    # 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 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 %}
    ```

    Raises `AlreadyRegistered` if a different component was already registered
    under the same name.

    Example:

    ```py
    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:
    """
    Unlinks a previously-registered component from the registry under the given name.

    Once a component is unregistered, it CANNOT be used in a template anymore.
    Following would raise an error:
    ```django
    {% component "my_comp" %}{% endcomponent %}
    ```

    Raises `NotRegistered` if the given name is not registered.

    Example:

    ```py
    # 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]