Skip to content

Home Information - Your home, your data, organized.

Python
12.1 KB
Raw Blame
"""
Placement view request shape -- parsing the inputs, encoding the outputs.

This module owns two related concerns for the placement modal:

* ``PlacementUrlParams`` -- the URL/form-param contract.
* ``PlacementFormParser`` -- the placement-form-body parser, including
  the three-level inheritance (top default -> group default -> per-entity)
  and the sentinel/tag wire format used in the form-value dropdowns:

    ``view:<id>``           -- existing LocationView
    ``collection:<id>``     -- existing Collection
    ``__new_view__``        -- create one fresh LocationView (top only)
    ``__new_collection__``  -- create one fresh Collection (top only)
    ``__skip__``            -- explicit no-op overriding parent
    ``''``                  -- inherit from parent (top -> skip-all)

  Group/entity overrides to existing views or collections remain in
  effect even when the top is one of the new-* sentinels.
"""
import logging
from dataclasses import dataclass, field
from typing import Dict, List, Optional, Tuple

from django.core.exceptions import BadRequest
from django.utils.http import urlencode

from hi.apps.collection.collection_manager import CollectionManager
from hi.apps.collection.models import Collection
from hi.apps.common.utils import str_to_bool
from hi.apps.entity.entity_placement import PlacementDecision
from hi.apps.entity.models import Entity
from hi.apps.location.location_manager import LocationManager
from hi.apps.location.models import Location, LocationView

logger = logging.getLogger(__name__)


@dataclass(frozen=True)
class PlacementUrlParams:
    """Encoded contract for the placement view's URL/form params.

    Single source of truth for key names, value encodings, and list
    separators -- callers build URLs and parse requests via this class
    rather than handling raw strings.

    Scope: the URL query params (``?is_initial_connect=...&entity_ids=...``)
    and matching hidden form fields. Does *not* cover the per-entity /
    per-group form fields consumed by ``PlacementFormParser``.
    """

    KEY_IS_INITIAL_CONNECT = 'is_initial_connect'
    KEY_ENTITY_IDS = 'entity_ids'
    ENTITY_IDS_SEP = ','
    TRUE_VALUE = '1'
    FALSE_VALUE = '0'

    is_initial_connect : bool        = False
    entity_ids        : List[int]   = field(default_factory=list)

    def to_query_dict(self) -> Dict[str, str]:
        """Sparse query dict -- defaults are omitted, keeping URLs free of
        ``?is_initial_connect=0`` cruft."""
        result : Dict[str, str] = {}
        if self.is_initial_connect:
            result[self.KEY_IS_INITIAL_CONNECT] = self.TRUE_VALUE
        if self.entity_ids:
            result[self.KEY_ENTITY_IDS] = self.ENTITY_IDS_SEP.join(
                str(i) for i in self.entity_ids
            )
        return result

    def append_to_url( self, base_url : str ) -> str:
        """Return ``base_url`` with these params encoded as a
        query string. Empty params produce no '?' suffix."""
        qd = self.to_query_dict()
        return f'{base_url}?{urlencode(qd)}' if qd else base_url

    def is_initial_connect_form_value(self) -> str:
        """Hidden-form-field encoding of ``is_initial_connect`` for round-trip
        through a POST."""
        return self.TRUE_VALUE if self.is_initial_connect else self.FALSE_VALUE

    @classmethod
    def from_data(cls, data) -> 'PlacementUrlParams':
        """Parse from ``request.GET`` or ``request.POST`` (or any
        QueryDict-like). Malformed ``entity_ids`` raises BadRequest
        so a tampered request fails loudly rather than silently
        widening scope."""
        is_initial = str_to_bool( data.get( cls.KEY_IS_INITIAL_CONNECT, '' ) )
        raw = ( data.get( cls.KEY_ENTITY_IDS, '' ) or '' ).strip()
        entity_ids : List[int] = []
        if raw:
            try:
                entity_ids = [
                    int( piece )
                    for piece in raw.split( cls.ENTITY_IDS_SEP )
                    if piece.strip()
                ]
            except ValueError:
                raise BadRequest( f'Invalid {cls.KEY_ENTITY_IDS} parameter.' )
        return cls( is_initial_connect = is_initial, entity_ids = entity_ids )


class PlacementFormParser:
    """Translates placement modal form input into a list of
    ``PlacementDecision`` values, applying three-level inheritance
    and the skip / new-view / new-collection sentinels."""

    FORM_VALUE_SKIP = '__skip__'
    FORM_VALUE_NEW_VIEW = '__new_view__'
    FORM_VALUE_NEW_COLLECTION = '__new_collection__'

    @classmethod
    def parse( cls, request, integration_data ) -> List[PlacementDecision]:
        decisions = []
        view_lookup = cls._build_view_lookup()
        collection_lookup = cls._build_collection_lookup()

        top_value = request.POST.get('top_view', '').strip()
        top_target = cls._resolve_top_target(
            request = request,
            top_value = top_value,
            view_lookup = view_lookup,
            collection_lookup = collection_lookup,
            integration_data = integration_data,
        )

        group_indices = sorted({
            int(k.split('_')[2])
            for k in request.POST.keys()
            if k.startswith('all_group_') and k.endswith('_entity_ids')
        })
        for group_index in group_indices:
            group_value = request.POST.get(
                f'group_view_{group_index}', '' ).strip()
            group_target = cls._resolve_child_choice(
                form_value = group_value,
                parent_target = top_target,
                view_lookup = view_lookup,
                collection_lookup = collection_lookup,
            )
            entity_id_list = request.POST.getlist(
                f'all_group_{group_index}_entity_ids' )
            entities = list( Entity.objects.filter(
                id__in = [int(e) for e in entity_id_list]
            ) )
            entity_by_id = { e.id: e for e in entities }
            for entity_id_str in entity_id_list:
                entity = entity_by_id.get( int(entity_id_str) )
                if entity is None:
                    continue
                entity_value = request.POST.get(
                    f'group_{group_index}_entity_{entity.id}_view', '' ).strip()
                entity_target = cls._resolve_child_choice(
                    form_value = entity_value,
                    parent_target = group_target,
                    view_lookup = view_lookup,
                    collection_lookup = collection_lookup,
                )
                decisions.append( cls._make_decision(
                    entity = entity, target = entity_target,
                ) )

        # Ungrouped items: no group level -- entity inherits from top.
        ungrouped_ids = request.POST.getlist( 'ungrouped_entity_ids' )
        if ungrouped_ids:
            ungrouped = list( Entity.objects.filter(
                id__in = [int(e) for e in ungrouped_ids]
            ) )
            ungrouped_by_id = { e.id: e for e in ungrouped }
            for entity_id_str in ungrouped_ids:
                entity = ungrouped_by_id.get( int(entity_id_str) )
                if entity is None:
                    continue
                entity_value = request.POST.get(
                    f'ungrouped_entity_{entity.id}_view', '' ).strip()
                entity_target = cls._resolve_child_choice(
                    form_value = entity_value,
                    parent_target = top_target,
                    view_lookup = view_lookup,
                    collection_lookup = collection_lookup,
                )
                decisions.append( cls._make_decision(
                    entity = entity, target = entity_target,
                ) )

        return decisions

    @classmethod
    def _make_decision( cls, entity, target ) -> PlacementDecision:
        """target is a 2-tuple (location_view, collection) where at
        most one is non-None, or (None, None) for skip."""
        location_view, collection = target
        return PlacementDecision(
            entity = entity,
            location_view = location_view,
            collection = collection,
        )

    @classmethod
    def _resolve_top_target( cls,
                             request,
                             top_value         : str,
                             view_lookup       : dict,
                             collection_lookup : dict,
                             integration_data,
                             ) -> Tuple[Optional[LocationView], Optional[Collection]]:
        """Top-level form value -> (location_view, collection) target. Creating
        a new view/collection is the side effect of the corresponding sentinel;
        the new object then becomes the top default for everything else."""
        if top_value == cls.FORM_VALUE_NEW_VIEW:
            return cls._create_new_view(
                request = request, integration_data = integration_data,
            ), None
        if top_value == cls.FORM_VALUE_NEW_COLLECTION:
            return None, cls._create_new_collection(
                integration_data = integration_data,
            )
        if top_value == '':
            return None, None
        return cls._lookup_tagged_target(
            tagged_value = top_value,
            view_lookup = view_lookup,
            collection_lookup = collection_lookup,
        )

    @classmethod
    def _resolve_child_choice(
            cls,
            form_value         : str,
            parent_target      : Tuple[Optional[LocationView], Optional[Collection]],
            view_lookup        : dict,
            collection_lookup  : dict,
    ) -> Tuple[Optional[LocationView], Optional[Collection]]:
        """Group/entity form value -> (location_view, collection) target.
        Empty inherits from parent; ``__skip__`` overrides inheritance.
        Group/entity dropdowns do not offer the new-* sentinels -- only the
        top level can create a new target."""
        if form_value == '':
            return parent_target
        if form_value == cls.FORM_VALUE_SKIP:
            return None, None
        return cls._lookup_tagged_target(
            tagged_value = form_value,
            view_lookup = view_lookup,
            collection_lookup = collection_lookup,
        )

    @classmethod
    def _lookup_tagged_target(
            cls,
            tagged_value       : str,
            view_lookup        : dict,
            collection_lookup  : dict,
    ) -> Tuple[Optional[LocationView], Optional[Collection]]:
        """Parse 'view:<id>' or 'collection:<id>' into a
        (location_view, collection) tuple. Unknown tag prefix or
        missing id resolves to skip."""
        if ':' not in tagged_value:
            return None, None
        kind, _, raw_id = tagged_value.partition(':')
        if kind == 'view':
            return view_lookup.get( raw_id ), None
        if kind == 'collection':
            return None, collection_lookup.get( raw_id )
        return None, None

    @classmethod
    def _create_new_view( cls, request, integration_data ) -> LocationView:
        """Create a single LocationView named after the integration label,
        attached to the operator's current default Location. Name collisions
        are handled by LocationManager's built-in disambiguation."""
        try:
            location = LocationManager().get_default_location( request = request )
        except Location.DoesNotExist:
            raise BadRequest(
                'Cannot create a new view: no Location is configured.'
            )
        return LocationManager().create_location_view(
            location = location,
            name = integration_data.label,
        )

    @classmethod
    def _create_new_collection( cls, integration_data ) -> Collection:
        """Create a single Collection named after the integration label. Name
        collisions are handled by CollectionManager's built-in disambiguation."""
        return CollectionManager().create_collection(
            name = integration_data.label,
        )

    @classmethod
    def _build_view_lookup( cls ) -> dict:
        return { str(v.id): v for v in LocationView.objects.all() }

    @classmethod
    def _build_collection_lookup( cls ) -> dict:
        return { str(c.id): c for c in Collection.objects.all() }