surveyjs 0.1.0__tar.gz

surveyjs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nova Code (https://www.novacode.nl)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

surveyjs-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: surveyjs
+Version: 0.1.0
+Summary: SurveyJS (JSON data) API for Python
+Author-email: Bob Leers <bob@novacode.nl>
+License: MIT
+Project-URL: Homepage, https://github.com/novacode-nl/python-surveyjs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: File Formats :: JSON
+Classifier: Topic :: File Formats :: JSON :: JSON Schema
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# surveyjs (Python)
+
+SurveyJS (JSON Form Builder) data API for Python.
+
+For information about the SurveyJS project, see https://surveyjs.io
+
+## Introduction
+
+**surveyjs** is a Python package which loads and transforms
+SurveyJS **Creator JSON** (survey schema) and **Form JSON** (submission data)
+into **usable Python objects**.
+
+Its main aim is to provide easy access to a SurveyJS Form's questions (fields, layout elements, etc.)
+also captured as **Python objects**, which makes this API very versatile and usable.
+
+**Notes about terms:**
+  - **SurveyCreator:** The Survey Creator (form builder) schema which is the design of a Form.
+  - **SurveyForm:** A filled-in Survey Form, aka Form response, submission.
+  - **Question:** Input (field) and layout elements in SurveyJS (Creator and Form). Question is not a semantic term for a layout element (e.g. panel), but we follow the SurveyJS convention of calling all components "questions".
+
+**Question types:**
+ Source code (file prefix `question`): https://github.com/surveyjs/survey-library/tree/master/packages/survey-core/src
+
+## Features
+
+  - Compatible with Python 3.8 and later
+  - Constructor of the **SurveyCreator** and **SurveyForm** class only requires
+    the JSON (string or dict).
+  - Get a SurveyForm object's Questions as usable Python objects
+    e.g. datetime, boolean, list (for checkbox), dict (for matrix) etc.
+  - Support for all SurveyJS question types
+  - Open source (MIT License)
+
+## Installation
+
+```
+pip install surveyjs
+```
+
+### Source Install
+
+```
+git clone <repo-url>
+cd python-surveyjs
+pip install -e .
+```
+
+## Usage Examples
+
+```python
+from surveyjs import SurveyCreator, SurveyForm
+
+# survey_json is a SurveyJS Creator JSON schema (string or dict)
+# form_json is a SurveyJS Form submission JSON (string or dict)
+
+creator = SurveyCreator(survey_json)
+form = SurveyForm(form_json, creator)
+
+# Text question
+print(form.input_questions['firstName'].label)
+# 'First Name'
+
+print(form.input_questions['firstName'].value)
+# 'Bob'
+
+# Checkbox question
+print(form.input_questions['colors'].value)
+# ['red', 'blue']
+
+# Rating question
+print(form.input_questions['satisfaction'].value)
+# 4
+
+# Boolean question
+print(form.input_questions['agree'].value)
+# True
+
+# Matrix question
+print(form.input_questions['quality'].value)
+# {'affordable': 'good', 'does-what-it-claims': 'excellent'}
+
+# Access by attribute
+print(form.data.firstName.value)
+# 'Bob'
+```
+
+## Unit Tests
+
+### Run all tests
+
+From toplevel directory:
+```
+poetry run python -m unittest
+```
+
+### Run specific (questions) unittests
+
+All questions, from toplevel directory:
+
+```
+poetry run python -m unittest tests/test_question_*.py
+```
+
+Nested questions (complexity), from toplevel directory:
+
+```
+poetry run python -m unittest tests/test_nested_questions.py
+```
+
+### Run specific component unittest
+
+```
+poetry run python -m unittest tests.test_question_ranking.TestQuestionRanking.test_choices
+```
+
+## License
+
+[MIT](LICENSE)

surveyjs-0.1.0/README.md

@@ -0,0 +1,118 @@
+# surveyjs (Python)
+
+SurveyJS (JSON Form Builder) data API for Python.
+
+For information about the SurveyJS project, see https://surveyjs.io
+
+## Introduction
+
+**surveyjs** is a Python package which loads and transforms
+SurveyJS **Creator JSON** (survey schema) and **Form JSON** (submission data)
+into **usable Python objects**.
+
+Its main aim is to provide easy access to a SurveyJS Form's questions (fields, layout elements, etc.)
+also captured as **Python objects**, which makes this API very versatile and usable.
+
+**Notes about terms:**
+  - **SurveyCreator:** The Survey Creator (form builder) schema which is the design of a Form.
+  - **SurveyForm:** A filled-in Survey Form, aka Form response, submission.
+  - **Question:** Input (field) and layout elements in SurveyJS (Creator and Form). Question is not a semantic term for a layout element (e.g. panel), but we follow the SurveyJS convention of calling all components "questions".
+
+**Question types:**
+ Source code (file prefix `question`): https://github.com/surveyjs/survey-library/tree/master/packages/survey-core/src
+
+## Features
+
+  - Compatible with Python 3.8 and later
+  - Constructor of the **SurveyCreator** and **SurveyForm** class only requires
+    the JSON (string or dict).
+  - Get a SurveyForm object's Questions as usable Python objects
+    e.g. datetime, boolean, list (for checkbox), dict (for matrix) etc.
+  - Support for all SurveyJS question types
+  - Open source (MIT License)
+
+## Installation
+
+```
+pip install surveyjs
+```
+
+### Source Install
+
+```
+git clone <repo-url>
+cd python-surveyjs
+pip install -e .
+```
+
+## Usage Examples
+
+```python
+from surveyjs import SurveyCreator, SurveyForm
+
+# survey_json is a SurveyJS Creator JSON schema (string or dict)
+# form_json is a SurveyJS Form submission JSON (string or dict)
+
+creator = SurveyCreator(survey_json)
+form = SurveyForm(form_json, creator)
+
+# Text question
+print(form.input_questions['firstName'].label)
+# 'First Name'
+
+print(form.input_questions['firstName'].value)
+# 'Bob'
+
+# Checkbox question
+print(form.input_questions['colors'].value)
+# ['red', 'blue']
+
+# Rating question
+print(form.input_questions['satisfaction'].value)
+# 4
+
+# Boolean question
+print(form.input_questions['agree'].value)
+# True
+
+# Matrix question
+print(form.input_questions['quality'].value)
+# {'affordable': 'good', 'does-what-it-claims': 'excellent'}
+
+# Access by attribute
+print(form.data.firstName.value)
+# 'Bob'
+```
+
+## Unit Tests
+
+### Run all tests
+
+From toplevel directory:
+```
+poetry run python -m unittest
+```
+
+### Run specific (questions) unittests
+
+All questions, from toplevel directory:
+
+```
+poetry run python -m unittest tests/test_question_*.py
+```
+
+Nested questions (complexity), from toplevel directory:
+
+```
+poetry run python -m unittest tests/test_nested_questions.py
+```
+
+### Run specific component unittest
+
+```
+poetry run python -m unittest tests.test_question_ranking.TestQuestionRanking.test_choices
+```
+
+## License
+
+[MIT](LICENSE)

surveyjs-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "surveyjs"
+version = "0.1.0"
+description = "SurveyJS (JSON data) API for Python"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "Bob Leers", email = "bob@novacode.nl"}
+]
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: File Formats :: JSON",
+    "Topic :: File Formats :: JSON :: JSON Schema"
+]
+
+[project.urls]
+Homepage = "https://github.com/novacode-nl/python-surveyjs"
+
+[tool.setuptools.packages.find]
+include = ["surveyjs*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

surveyjs-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

surveyjs-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/surveyjs/questions/__init__.py

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

surveyjs-0.1.0/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)