Home Information - Your home, your data, organized.
Python
"""Paperless-ngx simulator: parametric document-search responses.
Unlike the entity-shaped simulators (HASS, HomeBox, ZoneMinder),
paperless-ngx has no 1-to-1 mapping onto HI Entities — its
contribution is the EXTERNAL_REFERENCE capability, which produces
TEXT attributes on existing Entity / Location records, not new
entities. So this simulator has no SimEntities and no persistent
corpus. Instead it generates synthetic search results on the fly,
shaped by a small set of operator-tunable knobs held on the
singleton:
- result_count : how many documents each search returns (chosen
to exercise empty / single / multi-page picker
rendering paths)
- mime_mix : which mime-type mix populates result rows (PDF
only, images only, plain text only, or mixed)
- thumbnails : whether ``/api/documents/<id>/thumb/`` serves
a thumbnail (when off the endpoint 404s and HI
falls back to the ``/api/documents/<id>/download/``
original-bytes -> pdf2image -> thumbnail
pipeline -- which produces a HI-generated
thumbnail visually distinguishable from the
upstream placeholder). To exercise the full
no-thumbnail path (mime fallback icon on the
card), force a ``ServiceFaultMode.SERVER_ERROR``
so all endpoints fail.
- snippets : whether each result carries a content snippet
(exercises picker layout with / without it)
Artificial latency is intentionally NOT a knob here -- the
framework ``ServiceFaultMode`` already exposes a ``SLOW`` mode that
covers the same operator need without per-simulator duplication.
Settings live in memory on the singleton (same lifecycle as
HomeBox's ``_api_version``) — lost on server restart, survives
SimProfile switches.
"""
from dataclasses import dataclass
from enum import Enum
from typing import Dict, List
from hi.simulator.services.base_models import SimEntityDefinition
from hi.simulator.services.service_simulator import ServiceSimulator
class MimeMix( Enum ):
"""Which mime types populate generated search results. Drives
the picker's thumbnail / fallback-icon path through different
code branches."""
PDF_ONLY = 'PDF only'
IMAGE_ONLY = 'Images only'
TEXT_ONLY = 'Plain text only'
MIXED = 'Mixed'
@classmethod
def default(cls) -> 'MimeMix':
return cls.MIXED
@property
def label(self) -> str:
return self.value
# Discrete result counts the operator can pick from the extras form.
# Chosen to exercise distinct picker rendering paths: empty,
# single-result, small-multi, scroll-into-view, and large-page.
RESULT_COUNT_CHOICES = ( 0, 1, 3, 10, 50 )
@dataclass
class PaperlessSimSettings:
"""Knobs that parametrize every documents-search response. Held
on the PaperlessSimulator singleton; ephemeral."""
result_count : int = 3
mime_mix : MimeMix = MimeMix.MIXED
thumbnails : bool = True
snippets : bool = True
class PaperlessSimulator( ServiceSimulator ):
"""Stub paperless-ngx server. Responds to any documents query
with a parametrically-generated result list shaped by the
operator-tuned ``PaperlessSimSettings``."""
def __init_singleton__( self ):
# Set BEFORE initialize() so a SimProfile switch does NOT
# reset operator-tuned settings (same lifecycle as
# ``_fault_mode`` on the base class).
self._settings = PaperlessSimSettings()
super().__init_singleton__()
return
@property
def id(self) -> str:
return 'paperless'
@property
def label(self) -> str:
return 'Paperless-ngx'
@property
def integration_urls(self) -> List[ tuple ]:
return [ ( 'Paperless API base', 'services/paperless/' ) ]
@property
def settings(self) -> PaperlessSimSettings:
return self._settings
def set_settings( self, settings : PaperlessSimSettings ) -> None:
self._settings = settings
return
@property
def sim_entity_definition_list(self) -> List[ SimEntityDefinition ]:
# Paperless contributes only via EXTERNAL_REFERENCE — no
# SimEntity rows ever, so the service page's entity-list
# area renders empty. The extras pane carries the operator
# UI.
return []
@property
def extras_template_name(self) -> str:
return 'paperless/panes/settings_form.html'
@property
def extras_context(self) -> Dict:
return {
'settings': self._settings,
'result_count_choices': RESULT_COUNT_CHOICES,
'mime_mix_choices': list( MimeMix ),
}