surveyjs 0.1.0__py3-none-any.whl

surveyjs/__init__.py

@@ -0,0 +1,21 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+"""
+SurveyJS Python Package
+
+This module serves as the entry point for the surveyjs package, providing
+access to the core components for working with SurveyJS forms and the
+survey creator.
+
+It imports and exposes the following classes:
+    - SurveyForm: Handles the rendering and processing of SurveyJS forms.
+    - SurveyCreator: Provides functionality for creating and managing surveys.
+
+Copyright 2026 Nova Code (https://www.novacode.nl)
+See LICENSE file for full licensing details.
+"""
+# See LICENSE file for full licensing details.
+
+from surveyjs.creator import SurveyCreator
+from surveyjs.form import SurveyForm
+
+__all__ = ['SurveyCreator', 'SurveyForm']

surveyjs/creator.py

@@ -0,0 +1,165 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+import json
+import logging
+from collections import OrderedDict
+from copy import deepcopy
+
+from surveyjs.questions.question import Question
+
+logger = logging.getLogger(__name__)
+
+
+class SurveyCreator:
+    """
+    Represents a SurveyJS Creator schema (the survey blueprint/design).
+
+    Parses the survey JSON schema and creates Question objects for each
+    question element found in the schema.
+    """
+
+    def __init__(
+        self,
+        schema_json,
+        language='en',
+        i18n=None,
+        question_class_mapping={},
+        **kwargs
+    ):
+        """
+        @param schema_json: SurveyJS Creator JSON schema (str or dict)
+        @param language: Language code for translations (default: 'en')
+        @param i18n: Translations dict
+        """
+        if isinstance(schema_json, dict):
+            self.schema = schema_json
+        else:
+            self.schema = json.loads(schema_json)
+
+        self.language = language
+        self.i18n = i18n or {}
+
+        self.question_class_mapping = question_class_mapping
+
+        # All questions (input + layout) keyed by name
+        self.questions = OrderedDict()
+
+        # Input-only questions keyed by name (no panels, html, image)
+        self.input_questions = OrderedDict()
+
+        # Questions keyed by internal id
+        self.question_ids = OrderedDict()
+
+        # Load all questions from the schema
+        self.load_questions()
+
+    @property
+    def title(self):
+        return self.schema.get('title', '')
+
+    @property
+    def description(self):
+        return self.schema.get('description', '')
+
+    @property
+    def pages(self):
+        return self.schema.get('pages', [])
+
+    @property
+    def components(self):
+        return self.questions
+
+    @property
+    def input_components(self):
+        return self.input_questions
+
+    def load_questions(self):
+        """Load questions from the schema, handling both pages-based and
+        flat elements-based schemas."""
+        pages = self.schema.get('pages')
+        if pages:
+            for page in pages:
+                elements = page.get('elements', [])
+                self._load_elements(elements)
+        else:
+            # Single page: elements at top level
+            elements = self.schema.get('elements', [])
+            self._load_elements(elements)
+
+    def _load_elements(self, elements, parent=None):
+        """Recursively load elements from the schema."""
+        for element in elements:
+            if 'type' not in element:
+                continue
+
+            question_obj = self.get_question_object(element)
+            if not question_obj:
+                continue
+
+            question_obj.load(
+                question_owner=self,
+                parent=parent,
+                data=None,
+                is_form=False,
+            )
+            self.questions[question_obj.name] = question_obj
+
+            if question_obj.id:
+                self.question_ids[question_obj.id] = question_obj
+
+            # Recurse into panel/page elements
+            if element['type'] in ('panel', 'paneldynamic'):
+                nested = element.get('elements', [])
+                self._load_elements(nested, parent=question_obj)
+
+    def get_question_class(self, element):
+        """Dynamically load the question class based on the element type."""
+        element_type = element.get('type')
+        element_type_cap = element_type.capitalize() if element_type else None
+        if not element_type:
+            return None
+
+        cls_mapping = self.question_class_mapping.get(element_type)
+        if cls_mapping:
+            cls_mapping = cls_mapping.capitalize() if isinstance(cls_mapping, str) else cls_mapping
+            if isinstance(cls_mapping, str):
+                cls_name = f"Question{cls_mapping}"
+                import_path = f"surveyjs.questions.{element_type}.{cls_mapping}"
+                try:
+                    module = __import__(import_path, fromlist=[cls_name])
+                    cls = getattr(module, cls_name)
+                    return cls
+                except (AttributeError, ModuleNotFoundError) as e:
+                    logger.warning(
+                        "Could not load question class for type '%s': %s. "
+                        "Falling back to base Question.", element_type, e
+                    )
+                    return Question
+            else:
+                return cls_mapping
+        else:
+            cls_name = f"Question{element_type_cap}"
+            import_path = 'surveyjs.questions.%s' % element_type
+            try:
+                module = __import__(import_path, fromlist=[cls_name])
+                return getattr(module, cls_name)
+            except (AttributeError, ModuleNotFoundError) as e:
+                logger.warning(
+                    "Could not load question class for type '%s': %s. "
+                    "Falling back to base Question.", element_type, e
+                )
+                return Question
+
+    def get_question_object(self, element):
+        """Create a question object from an element dict."""
+        cls = self.get_question_class(element)
+        if cls is None:
+            return None
+        return cls(element, self, language=self.language, i18n=self.i18n)
+
+    @property
+    def form(self):
+        """Placeholder form dict (always empty). Useful in contexts where
+        a question owner's form is requested."""
+        return {}

surveyjs/form.py

@@ -0,0 +1,147 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+import json
+import logging
+from collections import OrderedDict
+
+from surveyjs import SurveyCreator
+
+logger = logging.getLogger(__name__)
+
+
+class SurveyForm:
+    """
+    Represents a filled-in SurveyJS form (submission data).
+
+    Parses the form submission JSON against a SurveyCreator schema and creates
+    Question objects with values populated from the submission.
+    """
+
+    def __init__(
+        self,
+        form_json,
+        creator=None,
+        creator_schema_json=None,
+        lang="en",
+        **kwargs
+    ):
+        """
+        @param form_json: SurveyJS Form submission JSON (str or dict)
+        @param creator: A SurveyCreator instance
+        @param creator_schema_json: SurveyCreator schema JSON (str or dict)
+            Alternative to providing a SurveyCreator instance.
+        @param lang: Language code for translations (default: 'en')
+        """
+
+        if creator and creator_schema_json:
+            raise Exception(
+                "Constructor accepts either creator or creator_schema_json, not both."
+            )
+
+        if isinstance(form_json, dict):
+            self.form = form_json
+        else:
+            self.form = json.loads(form_json)
+
+        self.creator = creator
+        self.creator_schema_json = creator_schema_json
+
+        if self.creator is None and self.creator_schema_json:
+            self.creator = SurveyCreator(self.creator_schema_json)
+
+        if self.creator:
+            if not isinstance(self.creator, SurveyCreator):
+                raise TypeError("creator must be a SurveyCreator instance")
+        elif self.creator_schema_json:
+            assert isinstance(self.creator_schema_json, str)
+
+        else:
+            raise Exception(
+                "Provide either the argument: creator or creator_schema_json."
+            )
+
+        self.lang = lang
+        # defaults to English (en) date/time format
+        self.date_format = kwargs.get('date_format', '%m/%d/%Y')
+        self.time_format = kwargs.get('time_format', '%H:%M:%S')
+
+        # All questions (input + layout) keyed by name
+        self.questions = OrderedDict()
+
+        # Input-only questions keyed by name
+        self.input_questions = OrderedDict()
+
+        # Questions keyed by id
+        self.question_ids = {}
+
+        # Load questions from survey schema + populate values from form data
+        self.load_questions()
+
+        # Create attribute-style accessor
+        self._data = FormData(self)
+
+    def set_creator_by_creator_schema_json(self):
+        self.creator = SurveyCreator(
+            self.creator_schema_json,
+            language=self.lang,
+        )
+
+    @property
+    def data(self):
+        """Attribute-style access to input questions."""
+        return self._data
+
+    @property
+    def components(self):
+        """ Alias for questions, including both input and layout questions."""
+        return self.questions
+
+    @property
+    def input_components(self):
+        """ Alias for questions, including input queastions."""
+        return self.input_questions
+
+    def load_questions(self):
+        """Load questions from the survey schema and populate values from
+        form submission data."""
+        for key, creator_question in self.creator.questions.items():
+            # Create a new question object (don't affect the Survey's question)
+            question_obj = self.creator.get_question_object(creator_question.raw)
+            question_obj.load(
+                question_owner=self,
+                parent=None,
+                data=self.form,
+                is_form=True,
+            )
+            self.questions[key] = question_obj
+
+            if question_obj.id:
+                self.question_ids[question_obj.id] = question_obj
+
+    def get_question_by_name(self, name):
+        """Get a question by its name."""
+        return self.input_questions.get(name)
+
+    def get_value(self, name):
+        """Get the value of a question by name."""
+        question = self.input_questions.get(name)
+        if question:
+            return question.value
+        return None
+
+
+class FormData:
+    """Provides attribute-style access to form input questions.
+
+    Example:
+        form.data.firstName.value  # => 'Bob'
+    """
+
+    def __init__(self, form):
+        self._form = form
+
+    def __getattr__(self, key):
+        if key.startswith('_'):
+            return super().__getattribute__(key)
+        return self._form.input_questions.get(key)

surveyjs/questions/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.

surveyjs/questions/boolean.py

@@ -0,0 +1,46 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+from .question import Question
+
+
+class QuestionBoolean(Question):
+    """SurveyJS Boolean (Yes/No) question.
+
+    Value is typically True/False.
+    """
+
+    @property
+    def label_true(self):
+        return self.raw.get('labelTrue', 'Yes')
+
+    @property
+    def label_false(self):
+        return self.raw.get('labelFalse', 'No')
+
+    @property
+    def value_true(self):
+        return self.raw.get('valueTrue', True)
+
+    @property
+    def value_false(self):
+        return self.raw.get('valueFalse', False)
+
+    @property
+    def render_as(self):
+        """Render mode: 'default' (toggle) or 'checkbox' or 'radio'."""
+        return self.raw.get('renderAs', 'default')
+
+    def to_bool(self):
+        """Convert the value to a Python bool."""
+        val = self.value
+        if val is None:
+            return None
+        if isinstance(val, bool):
+            return val
+        if val == self.value_true:
+            return True
+        if val == self.value_false:
+            return False
+        # Fallback
+        return bool(val)

surveyjs/questions/checkbox.py

@@ -0,0 +1,65 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+from .question import Question
+
+
+class QuestionCheckbox(Question):
+    """SurveyJS Checkbox (multiple selection) question.
+
+    Value is typically a list of selected choice values.
+    """
+
+    @property
+    def choices(self):
+        return self.raw.get('choices', [])
+
+    @property
+    def choices_values(self):
+        """Get normalized choice values as a list of dicts."""
+        result = []
+        for choice in self.choices:
+            if isinstance(choice, dict):
+                result.append({
+                    'value': choice.get('value'),
+                    'text': choice.get('text', str(choice.get('value', '')))
+                })
+            else:
+                result.append({'value': choice, 'text': str(choice)})
+        return result
+
+    @property
+    def value_texts(self):
+        """Get the display texts for the currently selected values."""
+        val = self.value
+        if not val or not isinstance(val, list):
+            return []
+        texts = []
+        choice_map = {c['value']: c['text'] for c in self.choices_values}
+        for v in val:
+            texts.append(choice_map.get(v, str(v)))
+        return texts
+
+    @property
+    def has_other(self):
+        return self.raw.get('showOtherItem', self.raw.get('hasOther', False))
+
+    @property
+    def has_none(self):
+        return self.raw.get('showNoneItem', self.raw.get('hasNone', False))
+
+    @property
+    def has_select_all(self):
+        return self.raw.get('showSelectAllItem', self.raw.get('hasSelectAll', False))
+
+    @property
+    def max_selected_choices(self):
+        return self.raw.get('maxSelectedChoices', 0)
+
+    @property
+    def min_selected_choices(self):
+        return self.raw.get('minSelectedChoices', 0)
+
+    @property
+    def col_count(self):
+        return self.raw.get('colCount', 0)

surveyjs/questions/comment.py

@@ -0,0 +1,25 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+from .question import Question
+
+
+class QuestionComment(Question):
+    """SurveyJS Comment (Long Text / Multi-line) question."""
+
+    @property
+    def max_length(self):
+        return self.raw.get('maxLength', 0)
+
+    @property
+    def rows(self):
+        """Number of visible rows in the text area."""
+        return self.raw.get('rows', 4)
+
+    @property
+    def auto_grow(self):
+        return self.raw.get('autoGrow', False)
+
+    @property
+    def allow_resize(self):
+        return self.raw.get('allowResize', True)

surveyjs/questions/dropdown.py

@@ -0,0 +1,59 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+from .question import Question
+
+
+class QuestionDropdown(Question):
+    """SurveyJS Dropdown (single-select) question."""
+
+    @property
+    def choices(self):
+        return self.raw.get('choices', [])
+
+    @property
+    def choices_values(self):
+        result = []
+        for choice in self.choices:
+            if isinstance(choice, dict):
+                result.append({
+                    'value': choice.get('value'),
+                    'text': choice.get('text', str(choice.get('value', '')))
+                })
+            else:
+                result.append({'value': choice, 'text': str(choice)})
+        return result
+
+    @property
+    def value_text(self):
+        """Get the display text for the current value."""
+        val = self.value
+        for choice in self.choices_values:
+            if choice['value'] == val:
+                return choice['text']
+        return str(val) if val is not None else None
+
+    @property
+    def has_other(self):
+        return self.raw.get('showOtherItem', self.raw.get('hasOther', False))
+
+    @property
+    def other_text(self):
+        return self.raw.get('otherText', 'Other')
+
+    @property
+    def choices_by_url(self):
+        """Get choices loaded from a URL configuration."""
+        return self.raw.get('choicesByUrl', None)
+
+    @property
+    def search_enabled(self):
+        return self.raw.get('searchEnabled', True)
+
+    @property
+    def placeholder_text(self):
+        return self.raw.get('placeholder', '')
+
+    @property
+    def allow_clear(self):
+        return self.raw.get('allowClear', True)

surveyjs/questions/expression.py

@@ -0,0 +1,49 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+from .question import Question
+
+
+class QuestionExpression(Question):
+    """SurveyJS Expression question.
+
+    A read-only calculated field. Value is computed from an expression.
+    """
+
+    @property
+    def expression(self):
+        """The calculation expression."""
+        return self.raw.get('expression', '')
+
+    @property
+    def display_style(self):
+        """'none', 'decimal', 'currency', or 'percent'."""
+        return self.raw.get('displayStyle', 'none')
+
+    @property
+    def currency(self):
+        return self.raw.get('currency', 'USD')
+
+    @property
+    def maximum_fraction_digits(self):
+        return self.raw.get('maximumFractionDigits', -1)
+
+    @property
+    def minimum_fraction_digits(self):
+        return self.raw.get('minimumFractionDigits', -1)
+
+    @property
+    def use_grouping(self):
+        return self.raw.get('useGrouping', True)
+
+    def to_number(self):
+        """Try to convert the expression value to a number."""
+        val = self.value
+        if val is None:
+            return None
+        try:
+            if isinstance(val, (int, float)):
+                return val
+            return float(val)
+        except (ValueError, TypeError):
+            return None

surveyjs/questions/file.py

@@ -0,0 +1,53 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+from .question import Question
+
+
+class QuestionFile(Question):
+    """SurveyJS File Upload question.
+
+    Value is typically a list of file metadata objects or base64 data.
+    """
+
+    @property
+    def store_data_as_text(self):
+        """Whether files are stored as base64 text."""
+        return self.raw.get('storeDataAsText', True)
+
+    @property
+    def allow_multiple(self):
+        return self.raw.get('allowMultiple', False)
+
+    @property
+    def max_size(self):
+        """Maximum file size in bytes (0 = unlimited)."""
+        return self.raw.get('maxSize', 0)
+
+    @property
+    def accepted_types(self):
+        """Accepted file types (MIME types or extensions)."""
+        return self.raw.get('acceptedTypes', '')
+
+    @property
+    def allow_camera_access(self):
+        return self.raw.get('allowCameraAccess', False)
+
+    @property
+    def source_type(self):
+        return self.raw.get('sourceType', 'file')
+
+    @property
+    def files(self):
+        """Get the list of file objects from the value."""
+        val = self.value
+        if val is None:
+            return []
+        if isinstance(val, list):
+            return val
+        return [val]
+
+    @property
+    def file_count(self):
+        """Number of uploaded files."""
+        return len(self.files)

surveyjs/questions/html.py

@@ -0,0 +1,21 @@
+# Copyright 2026 Nova Code (https://www.novacode.nl)
+# See LICENSE file for full licensing details.
+
+from .question import Question
+
+
+class QuestionHtml(Question):
+    """SurveyJS HTML question.
+
+    Displays static HTML content. Not an input element.
+    """
+
+    @property
+    def is_input(self):
+        """HTML elements are display-only, not input questions."""
+        return False
+
+    @property
+    def html(self):
+        """Get the HTML content."""
+        return self.raw.get('html', '')