rest_flex_fields2.utils
=======================

.. py:module:: rest_flex_fields2.utils

.. autoapi-nested-parse::

   Utility helpers for ``rest_flex_fields2``.

   Provides request-inspection functions (`is_expanded`, `is_included`) and
   the `split_levels` helper that partitions dot-notation field lists into
   current-level and next-level fragments.



Functions
---------

.. autoapisummary::

   rest_flex_fields2.utils.is_expanded
   rest_flex_fields2.utils.is_included
   rest_flex_fields2.utils.split_levels


Module Contents
---------------

.. py:function:: is_expanded(request, field: str) -> bool

   Return whether `field` is requested for expansion.

   Inspects the ``expand`` query parameter on `request`.  Returns
   ``True`` when `field` appears in the comma-separated expand list, or
   when a wildcard value (e.g. ``*`` or ``~all``) is present.


.. py:function:: is_included(request, field: str) -> bool

   Return whether `field` should be included in the response.

   Returns ``False`` when the ``fields`` sparse-fieldset parameter is
   present and `field` is not listed, or when the ``omit`` parameter is
   present and `field` is listed.  Returns ``True`` otherwise.


.. py:function:: split_levels(fields: str | collections.abc.Iterable[str]) -> tuple[list[str], dict[str, list[str]]]

   Split a dot-notation field list into current-level and next-level parts.

   Given an iterable such as ``['a', 'a.b', 'a.d', 'c']``, returns a
   tuple ``(first_level, next_level)`` where ``first_level`` is the
   deduplicated list of top-level names (e.g. ``['a', 'c']``) and
   ``next_level`` is a dict mapping each name to its remaining path
   fragments (e.g. ``{'a': ['b', 'd']}``).  A plain string is treated
   as a comma-separated field list.