edsl 0.1.14__py3-none-any.whl → 0.1.40__py3-none-any.whl

edsl/questions/derived/QuestionLinearScale.py

@@ -1,26 +1,14 @@
 from __future__ import annotations
-import textwrap
 from typing import Optional
+
 from edsl.questions.descriptors import QuestionOptionsDescriptor, OptionLabelDescriptor
 from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
 
+from edsl.questions.decorators import inject_exception
 
-class QuestionLinearScale(QuestionMultipleChoice):
-    """
-    This question asks the user to respond to a statement on a linear scale.
-
-    Arguments:
-    - `question_name` is the name of the question (string)
-    - `question_text` is the text of the question (string)
-    - `question_options` are the options the user should select from (list of integers)
-
-    Optional arguments:
-    - `instructions` are the instructions for the question (string). If not provided, the default instructions are used. To view them, run `QuestionLinearScale.default_instructions`
-    - `option_labels` maps question_options to labels (dictionary mapping integers to strings)
-    - `short_names_dict` maps question_options to short names (dictionary mapping strings to strings)
 
-    For an example, see `QuestionLinearScale.example()`
-    """
+class QuestionLinearScale(QuestionMultipleChoice):
+    """This question prompts the agent to respond to a statement on a linear scale."""
 
     question_type = "linear_scale"
     option_labels: Optional[dict[int, str]] = OptionLabelDescriptor()
@@ -28,50 +16,75 @@ class QuestionLinearScale(QuestionMultipleChoice):
 
     def __init__(
         self,
+        question_name: str,
         question_text: str,
         question_options: list[int],
-        question_name: str,
-        short_names_dict: Optional[dict[str, str]] = None,
         option_labels: Optional[dict[int, str]] = None,
+        answering_instructions: Optional[str] = None,
+        question_presentation: Optional[str] = None,
+        include_comment: Optional[bool] = True,
     ):
+        """Instantiate a new QuestionLinearScale.
+
+        :param question_name: The name of the question.
+        :param question_text: The text of the question.
+        :param question_options: The options the respondent should select from.
+        :param option_labels: Maps question_options to labels.
+        :param instructions: Instructions for the question. If not provided, the default instructions are used. To view them, run `QuestionLinearScale.default_instructions`.
+        """
         super().__init__(
+            question_name=question_name,
             question_text=question_text,
             question_options=question_options,
-            question_name=question_name,
-            short_names_dict=short_names_dict,
+            use_code=False,  # question linear scale will have its own code
+            include_comment=include_comment,
         )
         self.question_options = question_options
-        self.option_labels = option_labels
+        if isinstance(option_labels, str):
+            self.option_labels = option_labels
+        else:
+            self.option_labels = (
+                {int(k): v for k, v in option_labels.items()} if option_labels else {}
+            )
+        self.answering_instructions = answering_instructions
+        self.question_presentation = question_presentation
 
     ################
     # Helpful
     ################
     @classmethod
-    def example(cls) -> QuestionLinearScale:
+    @inject_exception
+    def example(cls, include_comment: bool = True) -> QuestionLinearScale:
+        """Return an example of a linear scale question."""
         return cls(
             question_text="How much do you like ice cream?",
             question_options=[1, 2, 3, 4, 5],
             question_name="ice_cream",
             option_labels={1: "I hate it", 5: "I love it"},
+            include_comment=include_comment,
         )
 
 
 def main():
+    """Create an example of a linear scale question and demonstrate its functionality."""
     from edsl.questions.derived.QuestionLinearScale import QuestionLinearScale
 
     q = QuestionLinearScale.example()
     q.question_text
     q.question_options
     q.question_name
-    q.short_names_dict
     # validate an answer
-    q.validate_answer({"answer": 3, "comment": "I like custard"})
+    q._validate_answer({"answer": 3, "comment": "I like custard"})
     # translate answer code
-    q.translate_answer_code_to_answer(3, {})
+    q._translate_answer_code_to_answer(3, {})
     # simulate answer
-    q.simulate_answer()
-    q.simulate_answer(human_readable=False)
-    q.validate_answer(q.simulate_answer(human_readable=False))
+    q._simulate_answer()
+    q._simulate_answer(human_readable=False)
+    q._validate_answer(q._simulate_answer(human_readable=False))
     # serialization (inherits from Question)
     q.to_dict()
     assert q.from_dict(q.to_dict()) == q
+
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/questions/derived/QuestionTopK.py

@@ -1,26 +1,13 @@
 from __future__ import annotations
 from typing import Optional
-from edsl.exceptions import QuestionCreationValidationError
+
+from edsl.exceptions.questions import QuestionCreationValidationError
 from edsl.questions.QuestionCheckBox import QuestionCheckBox
+from edsl.questions.decorators import inject_exception
 
 
 class QuestionTopK(QuestionCheckBox):
-    """
-    This question asks the user to select exactly K options from a list.
-
-    Arguments:
-    - `question_name` is the name of the question (string)
-    - `question_text` is the text of the question (string)
-    - `question_options` are the options the user should select from (list of strings)
-    - `min_selections` is the minimum number of options that must be selected (positive integer).
-    - `max_selections` is the maximum number of options that must be selected (positive integer). Must be equal to `min_selections`
-
-    Optional arguments:
-    - `instructions` are the instructions for the question (string). If not provided, the default instructions are used. To view them, run `QuestionTopK.default_instructions`
-    - `short_names_dict` maps question_options to short names (dictionary mapping strings to strings)
-
-    For an example, run `QuestionTopK.example()`
-    """
+    """This question prompts the agent to select exactly K options from a list."""
 
     question_type = "top_k"
 
@@ -31,15 +18,29 @@ class QuestionTopK(QuestionCheckBox):
         question_options: list[str],
         min_selections: int,
         max_selections: int,
-        short_names_dict: Optional[dict[str, str]] = None,
+        question_presentation: Optional[str] = None,
+        answering_instructions: Optional[str] = None,
+        include_comment: Optional[bool] = True,
+        use_code: Optional[bool] = True,
     ):
+        """Initialize the question.
+
+        :param question_name: The name of the question.
+        :param question_text: The text of the question.
+        :param question_options: The options the respondent should select from.
+        :param instructions: Instructions for the question. If not provided, the default instructions are used. To view them, run `QuestionTopK.default_instructions`.
+        :param num_selections: The number of options that must be selected.
+        """
         super().__init__(
             question_name=question_name,
             question_text=question_text,
             question_options=question_options,
-            short_names_dict=short_names_dict,
             min_selections=min_selections,
             max_selections=max_selections,
+            question_presentation=question_presentation,
+            answering_instructions=answering_instructions,
+            include_comment=include_comment,
+            use_code=use_code,
         )
         if min_selections != max_selections:
             raise QuestionCreationValidationError(
@@ -54,32 +55,39 @@ class QuestionTopK(QuestionCheckBox):
     # Helpful
     ################
     @classmethod
-    def example(cls) -> QuestionTopK:
+    @inject_exception
+    def example(cls, include_comment: bool = True) -> QuestionTopK:
+        """Return an example question."""
         return cls(
             question_name="two_fruits",
             question_text="Which of the following fruits do you prefer?",
             question_options=["apple", "banana", "carrot", "durian"],
             min_selections=2,
             max_selections=2,
+            include_comment=include_comment,
         )
 
 
 def main():
+    """Test QuestionTopK."""
     from edsl.questions.derived.QuestionTopK import QuestionTopK
 
     q = QuestionTopK.example()
     q.question_text
     q.question_options
     q.question_name
-    q.short_names_dict
     # validate an answer
-    q.validate_answer({"answer": [0, 3], "comment": "I like custard"})
+    q._validate_answer({"answer": [0, 3], "comment": "I like custard"})
     # translate answer code
-    q.translate_answer_code_to_answer([0, 3], {})
+    q._translate_answer_code_to_answer([0, 3], {})
     # simulate answer
-    q.simulate_answer()
-    q.simulate_answer(human_readable=False)
-    q.validate_answer(q.simulate_answer(human_readable=False))
+    q._simulate_answer()
+    q._simulate_answer(human_readable=False)
+    q._validate_answer(q._simulate_answer(human_readable=False))
     # serialization (inherits from Question)
     q.to_dict()
     assert q.from_dict(q.to_dict()) == q
+
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

edsl/questions/derived/QuestionYesNo.py

@@ -1,23 +1,13 @@
 from __future__ import annotations
+from typing import Optional
 from edsl.questions.descriptors import QuestionOptionsDescriptor
 from edsl.questions.QuestionMultipleChoice import QuestionMultipleChoice
 
+from edsl.questions.decorators import inject_exception
 
-class QuestionYesNo(QuestionMultipleChoice):
-    """
-    This question asks the user to respond with "Yes" or "No".
-
-    Arguments:
-    - `question_name` is the name of the question (string)
-    - `question_text` is the text of the question (string)
-    - `question_options` are the options the user should select from (list of strings)
-
-    Optional arguments:
-    - `instructions` are the instructions for the question (string). If not provided, the default instructions are used. To view them, run `QuestionYesNo.default_instructions`
-    - `short_names_dict` maps question_options to short names (dictionary mapping strings to strings)
 
-    For an example, see `QuestionYesNo.example()`
-    """
+class QuestionYesNo(QuestionMultipleChoice):
+    """This question prompts the agent to respond with 'Yes' or 'No'."""
 
     question_type = "yes_no"
     question_options = QuestionOptionsDescriptor(num_choices=2)
@@ -26,14 +16,25 @@ class QuestionYesNo(QuestionMultipleChoice):
         self,
         question_name: str,
         question_text: str,
-        short_names_dict: dict[str, str] = None,
-        question_options: list[str] = ["Yes", "No"],
+        question_options: list[str] = ["No", "Yes"],
+        answering_instructions: Optional[str] = None,
+        question_presentation: Optional[str] = None,
+        include_comment: Optional[bool] = True,
     ):
+        """Instantiate a new QuestionYesNo.
+
+        :param question_name: The name of the question.
+        :param question_text: The text of the question.
+        :param instructions: Instructions for the question. If not provided, the default instructions are used. To view them, run `QuestionYesNo.default_instructions`.
+        """
         super().__init__(
             question_name=question_name,
             question_text=question_text,
             question_options=question_options,
-            short_names_dict=short_names_dict,
+            use_code=False,
+            answering_instructions=answering_instructions,
+            question_presentation=question_presentation,
+            include_comment=include_comment,
         )
         self.question_options = question_options
 
@@ -41,29 +42,41 @@ class QuestionYesNo(QuestionMultipleChoice):
     # Helpful
     ################
     @classmethod
-    def example(cls) -> QuestionYesNo:
+    @inject_exception
+    def example(cls, include_comment: bool = True) -> QuestionYesNo:
+        """Return an example of a yes/no question."""
         return cls(
-            question_name="is_it_raining",
-            question_text="Is it raining?",
-            short_names_dict={"Yes": "y", "No": "y"},
+            question_name="is_it_equal",
+            question_text="Is 5 + 5 equal to 11?",
+            include_comment=include_comment,
         )
 
 
 def main():
+    """Create an example of a yes/no question and demonstrate its functionality."""
     from edsl.questions.derived.QuestionYesNo import QuestionYesNo
 
     q = QuestionYesNo.example()
     q.question_text
     q.question_options
     q.question_name
-    q.short_names_dict
     # validate an answer
-    q.validate_answer({"answer": 0, "comment": "I like custard"})
+    q._validate_answer({"answer": 0, "comment": "I like custard"})
     # translate answer code
-    q.translate_answer_code_to_answer(0, {})
-    q.simulate_answer()
-    q.simulate_answer(human_readable=False)
-    q.validate_answer(q.simulate_answer(human_readable=False))
+    q._translate_answer_code_to_answer(0, {})
+    q._simulate_answer()
+    q._simulate_answer(human_readable=False)
+    q._validate_answer(q._simulate_answer(human_readable=False))
     # serialization (inherits from Question)
     q.to_dict()
     assert q.from_dict(q.to_dict()) == q
+
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)