edsl 0.1.30.dev4__tar.gz → 0.1.30.dev5__tar.gz

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: edsl
-Version: 0.1.30.dev4
+Version: 0.1.30.dev5
 Summary: Create and analyze LLM-based surveys
 Home-page: https://www.expectedparrot.com/
 License: MIT

edsl-0.1.30.dev5/edsl/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.30.dev5"

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/jobs/buckets/TokenBucket.py

@@ -30,6 +30,7 @@ class TokenBucket:
         if self.turbo_mode:
             pass
         else:
+            #pass
             self.turbo_mode = True
             self.capacity = float("inf")
             self.refill_rate = float("inf")
@@ -72,7 +73,17 @@ class TokenBucket:
         self.log.append((time.monotonic(), self.tokens))
 
     def refill(self) -> None:
-        """Refill the bucket with new tokens based on elapsed time."""
+        """Refill the bucket with new tokens based on elapsed time.
+        
+
+
+        >>> bucket = TokenBucket(bucket_name="test", bucket_type="test", capacity=10, refill_rate=1)
+        >>> bucket.tokens = 0
+        >>> bucket.refill()
+        >>> bucket.tokens > 0
+        True
+        
+        """
         now = time.monotonic()
         elapsed = now - self.last_refill
         refill_amount = elapsed * self.refill_rate

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/jobs/interviews/Interview.py

@@ -20,6 +20,10 @@ from edsl.jobs.interviews.retry_management import retry_strategy
 from edsl.jobs.interviews.InterviewTaskBuildingMixin import InterviewTaskBuildingMixin
 from edsl.jobs.interviews.InterviewStatusMixin import InterviewStatusMixin
 
+import asyncio
+
+def run_async(coro):
+    return asyncio.run(coro)
 
 class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
     """
@@ -36,8 +40,8 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         model: Type["LanguageModel"],
         debug: Optional[bool] = False,
         iteration: int = 0,
-        cache: "Cache" = None,
-        sidecar_model: "LanguageModel" = None,
+        cache: Optional["Cache"] = None,
+        sidecar_model: Optional['LanguageModel'] = None,
     ):
         """Initialize the Interview instance.
 
@@ -45,6 +49,24 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         :param survey: the survey being administered to the agent.
         :param scenario: the scenario that populates the survey questions.
         :param model: the language model used to answer the questions.
+        :param debug: if True, run without calls to the language model.
+        :param iteration: the iteration number of the interview.
+        :param cache: the cache used to store the answers.
+        :param sidecar_model: a sidecar model used to answer questions.
+
+        >>> i = Interview.example()
+        >>> i.task_creators
+        {}
+
+        >>> i.exceptions
+        {}
+
+        >>> _ = asyncio.run(i.async_conduct_interview())
+        >>> i.task_status_logs['q0']
+        [{'log_time': ..., 'value': <TaskStatus.NOT_STARTED: 1>}, {'log_time': ..., 'value': <TaskStatus.WAITING_FOR_DEPENDENCIES: 2>}, {'log_time': ..., 'value': <TaskStatus.API_CALL_IN_PROGRESS: 7>}, {'log_time': ..., 'value': <TaskStatus.SUCCESS: 8>}]
+
+        >>> i.to_index
+        {'q0': 0, 'q1': 1, 'q2': 2}
 
         """
         self.agent = agent
@@ -64,7 +86,7 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         self.exceptions = InterviewExceptionCollection()
         self._task_status_log_dict = InterviewStatusLog()
 
-        # dictionary mapping question names to their index in the survey."""
+        # dictionary mapping question names to their index in the survey.
         self.to_index = {
             question_name: index
             for index, question_name in enumerate(self.survey.question_names)
@@ -76,14 +98,16 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         model_buckets: ModelBuckets = None,
         debug: bool = False,
         stop_on_exception: bool = False,
-        sidecar_model: Optional[LanguageModel] = None,
+        sidecar_model: Optional['LanguageModel'] = None,
     ) -> tuple["Answers", List[dict[str, Any]]]:
         """
         Conduct an Interview asynchronously.
+        It returns a tuple with the answers and a list of valid results.
 
         :param model_buckets: a dictionary of token buckets for the model.
         :param debug: run without calls to LLM.
         :param stop_on_exception: if True, stops the interview if an exception is raised.
+        :param sidecar_model: a sidecar model used to answer questions.
 
         Example usage:
 
@@ -91,22 +115,44 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         >>> result, _ = asyncio.run(i.async_conduct_interview())
         >>> result['q0']
         'yes'
+
+        >>> i = Interview.example(throw_exception = True)
+        >>> result, _ = asyncio.run(i.async_conduct_interview())
+        Attempt 1 failed with exception:This is a test error now waiting 1.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
+        <BLANKLINE>
+        <BLANKLINE>
+        Attempt 2 failed with exception:This is a test error now waiting 2.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
+        <BLANKLINE>
+        <BLANKLINE>
+        Attempt 3 failed with exception:This is a test error now waiting 4.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
+        <BLANKLINE>
+        <BLANKLINE>
+        Attempt 4 failed with exception:This is a test error now waiting 8.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
+        <BLANKLINE>
+        <BLANKLINE>
+
+        >>> i.exceptions
+        {'q0': [{'exception': "Exception('This is a test error')", 'time': ..., 'traceback': ...
+
+        >>> i = Interview.example()
+        >>> result, _ = asyncio.run(i.async_conduct_interview(stop_on_exception = True))
+        Traceback (most recent call last):
+        ...
+        asyncio.exceptions.CancelledError
         """
         self.sidecar_model = sidecar_model
 
         # if no model bucket is passed, create an 'infinity' bucket with no rate limits
-        # print("model_buckets", model_buckets)
         if model_buckets is None or hasattr(self.agent, "answer_question_directly"):
             model_buckets = ModelBuckets.infinity_bucket()
 
-        # FOR TESTING
-        # model_buckets = ModelBuckets.infinity_bucket()
-
+        
         ## build the tasks using the InterviewTaskBuildingMixin
         ## This is the key part---it creates a task for each question,
         ## with dependencies on the questions that must be answered before this one can be answered.
         self.tasks = self._build_question_tasks(
-            debug=debug, model_buckets=model_buckets
+            debug=debug, 
+            model_buckets=model_buckets
         )
 
         ## 'Invigilators' are used to administer the survey
@@ -123,6 +169,14 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         It iterates through the tasks and invigilators, and yields the results of the tasks that are done.
         If a task is not done, it raises a ValueError.
         If an exception is raised in the task, it records the exception in the Interview instance except if the task was cancelled, which is expected behavior.
+
+        >>> i = Interview.example()
+        >>> result, _ = asyncio.run(i.async_conduct_interview())
+        >>> results = list(i._extract_valid_results())
+        >>> len(results) == len(i.survey)
+        True
+        >>> type(results[0])
+        <class 'edsl.data_transfer_models.AgentResponseDict'>
         """
         assert len(self.tasks) == len(self.invigilators)
 
@@ -140,7 +194,18 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
             yield result
 
     def _record_exception(self, task, exception: Exception) -> None:
-        """Record an exception in the Interview instance."""
+        """Record an exception in the Interview instance.
+        
+        It records the exception in the Interview instance, with the task name and the exception entry.
+
+        >>> i = Interview.example()
+        >>> result, _ = asyncio.run(i.async_conduct_interview())
+        >>> i.exceptions
+        {}
+        >>> i._record_exception(i.tasks[0], Exception("An exception occurred."))
+        >>> i.exceptions
+        {'q0': [{'exception': "Exception('An exception occurred.')", 'time': ..., 'traceback': 'NoneType: None\\n'}]}
+        """
         exception_entry = InterviewExceptionEntry(
             exception=repr(exception),
             time=time.time(),
@@ -156,6 +221,10 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         It is used to determine the order in which questions should be answered.
         This reflects both agent 'memory' considerations and 'skip' logic.
         The 'textify' parameter is set to True, so that the question names are returned as strings rather than integer indices.
+
+        >>> i = Interview.example()
+        >>> i.dag == {'q2': {'q0'}, 'q1': {'q0'}}
+        True
         """
         return self.survey.dag(textify=True)
 
@@ -166,8 +235,15 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         """Return a string representation of the Interview instance."""
         return f"Interview(agent = {repr(self.agent)}, survey = {repr(self.survey)}, scenario = {repr(self.scenario)}, model = {repr(self.model)})"
 
-    def duplicate(self, iteration: int, cache: Cache) -> Interview:
-        """Duplicate the interview, but with a new iteration number and cache."""
+    def duplicate(self, iteration: int, cache: 'Cache') -> Interview:
+        """Duplicate the interview, but with a new iteration number and cache.
+        
+        >>> i = Interview.example()
+        >>> i2 = i.duplicate(1, None)
+        >>> i.iteration + 1 == i2.iteration
+        True
+        
+        """
         return Interview(
             agent=self.agent,
             survey=self.survey,
@@ -178,7 +254,7 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         )
 
     @classmethod
-    def example(self):
+    def example(self, throw_exception: bool = False) -> Interview:
         """Return an example Interview instance."""
         from edsl.agents import Agent
         from edsl.surveys import Survey
@@ -193,66 +269,15 @@ class Interview(InterviewStatusMixin, InterviewTaskBuildingMixin):
         survey = Survey.example()
         scenario = Scenario.example()
         model = LanguageModel.example()
+        if throw_exception:
+            model = LanguageModel.example(test_model = True, throw_exception=True)
+            agent = Agent.example()
+            return Interview(agent=agent, survey=survey, scenario=scenario, model=model)
         return Interview(agent=agent, survey=survey, scenario=scenario, model=model)
 
 
 if __name__ == "__main__":
     import doctest
 
-    doctest.testmod()
-    # from edsl import Model
-    # from edsl.agents import Agent
-    # from edsl.surveys import Survey
-    # from edsl.scenarios import Scenario
-    # from edsl.questions import QuestionMultipleChoice
-
-    # # from edsl.jobs.Interview import Interview
-
-    # #  a survey with skip logic
-    # q0 = QuestionMultipleChoice(
-    #     question_text="Do you like school?",
-    #     question_options=["yes", "no"],
-    #     question_name="q0",
-    # )
-    # q1 = QuestionMultipleChoice(
-    #     question_text="Why not?",
-    #     question_options=["killer bees in cafeteria", "other"],
-    #     question_name="q1",
-    # )
-    # q2 = QuestionMultipleChoice(
-    #     question_text="Why?",
-    #     question_options=["**lack*** of killer bees in cafeteria", "other"],
-    #     question_name="q2",
-    # )
-    # s = Survey(questions=[q0, q1, q2])
-    # s = s.add_rule(q0, "q0 == 'yes'", q2)
-
-    # # create an interview
-    # a = Agent(traits=None)
-
-    # def direct_question_answering_method(self, question, scenario):
-    #     """Answer a question directly."""
-    #     raise Exception("Error!")
-    #     # return "yes"
-
-    # a.add_direct_question_answering_method(direct_question_answering_method)
-    # scenario = Scenario()
-    # m = Model()
-    # I = Interview(agent=a, survey=s, scenario=scenario, model=m)
-
-    # result = asyncio.run(I.async_conduct_interview())
-    # # # conduct five interviews
-    # # for _ in range(5):
-    # #     I.conduct_interview(debug=True)
-
-    # # # replace missing answers
-    # # I
-    # # repr(I)
-    # # eval(repr(I))
-    # # print(I.task_status_logs.status_matrix(20))
-    # status_matrix = I.task_status_logs.status_matrix(20)
-    # numerical_matrix = I.task_status_logs.numerical_matrix(20)
-    # I.task_status_logs.visualize()
-
-    # I.exceptions.print()
-    # I.exceptions.ascii_table()
+    # add ellipsis
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/jobs/interviews/InterviewTaskBuildingMixin.py

@@ -25,7 +25,7 @@ TIMEOUT = float(CONFIG.get("EDSL_API_TIMEOUT"))
 class InterviewTaskBuildingMixin:
     def _build_invigilators(
         self, debug: bool
-    ) -> Generator[InvigilatorBase, None, None]:
+    ) -> Generator['InvigilatorBase', None, None]:
         """Create an invigilator for each question.
 
         :param debug: whether to use debug mode, in which case `InvigilatorDebug` is used.
@@ -35,7 +35,7 @@ class InterviewTaskBuildingMixin:
         for question in self.survey.questions:
             yield self._get_invigilator(question=question, debug=debug)
 
-    def _get_invigilator(self, question: QuestionBase, debug: bool) -> "Invigilator":
+    def _get_invigilator(self, question: 'QuestionBase', debug: bool) -> "Invigilator":
         """Return an invigilator for the given question.
 
         :param question: the question to be answered
@@ -84,7 +84,7 @@ class InterviewTaskBuildingMixin:
         return tuple(tasks)  # , invigilators
 
     def _get_tasks_that_must_be_completed_before(
-        self, *, tasks: list[asyncio.Task], question: QuestionBase
+        self, *, tasks: list[asyncio.Task], question: 'QuestionBase'
     ) -> Generator[asyncio.Task, None, None]:
         """Return the tasks that must be completed before the given question can be answered.
 
@@ -100,7 +100,7 @@ class InterviewTaskBuildingMixin:
     def _create_question_task(
         self,
         *,
-        question: QuestionBase,
+        question: 'QuestionBase',
         tasks_that_must_be_completed_before: list[asyncio.Task],
         model_buckets: ModelBuckets,
         debug: bool,
@@ -175,24 +175,12 @@ class InterviewTaskBuildingMixin:
 
             self._add_answer(response=response, question=question)
 
-            # With the answer to the question, we can now cancel any skipped questions
             self._cancel_skipped_questions(question)
             return AgentResponseDict(**response)
         except Exception as e:
             raise e
-            # import traceback
-            # print("Exception caught:")
-            # traceback.print_exc()
-
-            # # Extract and print the traceback info
-            # tb = e.__traceback__
-            # while tb is not None:
-            #     print(f"File {tb.tb_frame.f_code.co_filename}, line {tb.tb_lineno}, in {tb.tb_frame.f_code.co_name}")
-            #     tb = tb.tb_next
-            #     breakpoint()
-            #     raise e
-
-    def _add_answer(self, response: AgentResponseDict, question: QuestionBase) -> None:
+        
+    def _add_answer(self, response: 'AgentResponseDict', question: 'QuestionBase') -> None:
         """Add the answer to the answers dictionary.
 
         :param response: the response to the question.
@@ -200,7 +188,7 @@ class InterviewTaskBuildingMixin:
         """
         self.answers.add_answer(response=response, question=question)
 
-    def _skip_this_question(self, current_question: QuestionBase) -> bool:
+    def _skip_this_question(self, current_question: 'QuestionBase') -> bool:
         """Determine if the current question should be skipped.
 
         :param current_question: the question to be answered.

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/jobs/tasks/QuestionTaskCreator.py

@@ -88,7 +88,8 @@ class QuestionTaskCreator(UserList):
         self.append(task)
 
     def generate_task(self, debug: bool) -> asyncio.Task:
-        """Create a task that depends on the passed-in dependencies."""
+        """Create a task that depends on the passed-in dependencies.        
+        """
         task = asyncio.create_task(
             self._run_task_async(debug), name=self.question.question_name
         )
@@ -144,18 +145,14 @@ class QuestionTaskCreator(UserList):
             self.task_status = TaskStatus.FAILED
             raise e
 
-        ## This isn't working
-        # breakpoint()
-        if results.get("cache_used", False):
+        if results.get('cache_used', False):
             self.tokens_bucket.add_tokens(requested_tokens)
             self.requests_bucket.add_tokens(1)
             self.from_cache = True
-            # print("Turning on turbo!")
+            # Turbo mode means that we don't wait for tokens or requests.
             self.tokens_bucket.turbo_mode_on()
             self.requests_bucket.turbo_mode_on()
         else:
-            # breakpoint()
-            # print("Turning off turbo!")
             self.tokens_bucket.turbo_mode_off()
             self.requests_bucket.turbo_mode_off()
 

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/language_models/LanguageModel.py

@@ -494,7 +494,7 @@ class LanguageModel(
         return table
 
     @classmethod
-    def example(cls, test_model: bool = False, canned_response: str = "Hello world"):
+    def example(cls, test_model: bool = False, canned_response: str = "Hello world", throw_exception: bool = False):
         """Return a default instance of the class.
 
         >>> from edsl.language_models import LanguageModel
@@ -519,6 +519,8 @@ class LanguageModel(
             ) -> dict[str, Any]:
                 await asyncio.sleep(0.1)
                 # return {"message": """{"answer": "Hello, world"}"""}
+                if throw_exception:
+                    raise Exception("This is a test error")
                 return {"message": f'{{"answer": "{canned_response}"}}'}
 
             def parse_response(self, raw_response: dict[str, Any]) -> str:

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/questions/QuestionFunctional.py

@@ -4,10 +4,33 @@ import inspect
 from edsl.questions.QuestionBase import QuestionBase
 
 from edsl.utilities.restricted_python import create_restricted_function
-
+from edsl.utilities.decorators import add_edsl_version, remove_edsl_version
 
 class QuestionFunctional(QuestionBase):
-    """A special type of question that is *not* answered by an LLM."""
+    """A special type of question that is *not* answered by an LLM.
+    
+    >>> from edsl import Scenario, Agent
+    
+    # Create an instance of QuestionFunctional with the new function
+    >>> question = QuestionFunctional.example()
+
+    # Activate and test the function
+    >>> question.activate()
+    >>> scenario = Scenario({"numbers": [1, 2, 3, 4, 5]})
+    >>> agent = Agent(traits={"multiplier": 10})
+    >>> results = question.by(scenario).by(agent).run()
+    >>> results.select("answer.*").to_list()[0] == 150
+    True
+    
+    # Serialize the question to a dictionary
+
+    >>> from edsl.questions.QuestionBase import QuestionBase
+    >>> new_question = QuestionBase.from_dict(question.to_dict())
+    >>> results = new_question.by(scenario).by(agent).run()
+    >>> results.select("answer.*").to_list()[0] == 150
+    True
+
+    """
 
     question_type = "functional"
     default_instructions = ""
@@ -73,6 +96,7 @@ class QuestionFunctional(QuestionBase):
         """Required by Question, but not used by QuestionFunctional."""
         raise NotImplementedError
 
+    @add_edsl_version
     def to_dict(self):
         return {
             "question_name": self.question_name,
@@ -81,6 +105,8 @@ class QuestionFunctional(QuestionBase):
             "requires_loop": self.requires_loop,
             "function_name": self.function_name,
         }
+    
+    
 
     @classmethod
     def example(cls):
@@ -113,4 +139,9 @@ def main():
     scenario = Scenario({"numbers": [1, 2, 3, 4, 5]})
     agent = Agent(traits={"multiplier": 10})
     results = question.by(scenario).by(agent).run()
-    print(results)
+    assert results.select("answer.*").to_list()[0] == 150
+
+if __name__ == "__main__":
+    #main()
+    import doctest
+    doctest.testmod(optionflags=doctest.ELLIPSIS)

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/questions/QuestionMultipleChoice.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 import time
 from typing import Union
 import random
-
+from typing import Optional
 from jinja2 import Template
 
 from edsl.questions.QuestionBase import QuestionBase
@@ -10,7 +10,11 @@ from edsl.questions.descriptors import QuestionOptionsDescriptor
 
 
 class QuestionMultipleChoice(QuestionBase):
-    """This question prompts the agent to select one option from a list of options."""
+    """This question prompts the agent to select one option from a list of options.
+    
+    https://docs.expectedparrot.com/en/latest/questions.html#questionmultiplechoice-class
+
+    """
 
     question_type = "multiple_choice"
     purpose = "When options are known and limited"
@@ -35,27 +39,69 @@ class QuestionMultipleChoice(QuestionBase):
         self.question_text = question_text
         self.question_options = question_options
 
+    # @property
+    # def question_options(self) -> Union[list[str], list[list], list[float], list[int]]:
+    #     """Return the question options."""
+    #     return self._question_options
+
     ################
     # Answer methods
     ################
     def _validate_answer(
         self, answer: dict[str, Union[str, int]]
     ) -> dict[str, Union[str, int]]:
-        """Validate the answer."""
+        """Validate the answer.
+        
+        >>> q = QuestionMultipleChoice.example()
+        >>> q._validate_answer({"answer": 0, "comment": "I like custard"})
+        {'answer': 0, 'comment': 'I like custard'}
+
+        >>> q = QuestionMultipleChoice(question_name="how_feeling", question_text="How are you?", question_options=["Good", "Great", "OK", "Bad"])
+        >>> q._validate_answer({"answer": -1, "comment": "I like custard"})
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.questions.QuestionAnswerValidationError: Answer code must be a non-negative integer (got -1).
+        """
         self._validate_answer_template_basic(answer)
         self._validate_answer_multiple_choice(answer)
         return answer
 
     def _translate_answer_code_to_answer(
-        self, answer_code, scenario: "Scenario" = None
+        self, 
+        answer_code: int, 
+        scenario: Optional["Scenario"] = None
     ):
-        """Translate the answer code to the actual answer."""
+        """Translate the answer code to the actual answer.
+
+        It is used to translate the answer code to the actual answer. 
+        The question options might be templates, so they need to be rendered with the scenario.
+        
+        >>> q = QuestionMultipleChoice.example()
+        >>> q._translate_answer_code_to_answer(0, {})
+        'Good'
+        
+        >>> q = QuestionMultipleChoice(question_name="how_feeling", question_text="How are you?", question_options=["{{emotion[0]}}", "emotion[1]"])
+        >>> q._translate_answer_code_to_answer(0, {"emotion": ["Happy", "Sad"]})
+        'Happy'
+
+        """
         from edsl.scenarios.Scenario import Scenario
 
         scenario = scenario or Scenario()
-        translated_options = [
-            Template(str(option)).render(scenario) for option in self.question_options
-        ]
+
+        if isinstance(self.question_options, str):
+            # If dynamic options are provided like {{ options }}, render them with the scenario
+            from jinja2 import Environment, meta
+            env = Environment()
+            parsed_content = env.parse(self.question_options)
+            question_option_key = list(meta.find_undeclared_variables(parsed_content))[0]
+            translated_options = scenario.get(question_option_key)
+        else:
+            translated_options = [
+                Template(str(option)).render(scenario) for option in self.question_options
+            ]
+        #print("Translated options:", translated_options)
+        #breakpoint()
         return translated_options[int(answer_code)]
 
     def _simulate_answer(
@@ -75,6 +121,7 @@ class QuestionMultipleChoice(QuestionBase):
 
     @property
     def question_html_content(self) -> str:
+        """Return the HTML version of the question."""
         if hasattr(self, "option_labels"):
             option_labels = self.option_labels
         else:

{edsl-0.1.30.dev4 → edsl-0.1.30.dev5}/edsl/questions/descriptors.py

@@ -2,7 +2,7 @@
 
 from abc import ABC, abstractmethod
 import re
-from typing import Any, Callable
+from typing import Any, Callable, List, Optional
 from edsl.exceptions import (
     QuestionCreationValidationError,
     QuestionAnswerValidationError,
@@ -242,6 +242,15 @@ class QuestionNameDescriptor(BaseDescriptor):
 class QuestionOptionsDescriptor(BaseDescriptor):
     """Validate that `question_options` is a list, does not exceed the min/max lengths, and has unique items."""
 
+    @classmethod
+    def example(cls):
+        class TestQuestion:
+            question_options = QuestionOptionsDescriptor()
+
+            def __init__(self, question_options: List[str]):
+                self.question_options = question_options
+        return TestQuestion
+
     def __init__(
         self,
         num_choices: int = None,
@@ -254,7 +263,31 @@ class QuestionOptionsDescriptor(BaseDescriptor):
         self.q_budget = q_budget
 
     def validate(self, value: Any, instance) -> None:
-        """Validate the question options."""
+        """Validate the question options.
+        
+        >>> q_class = QuestionOptionsDescriptor.example()
+        >>> _ = q_class(["a", "b", "c"])
+        >>> _ = q_class(["a", "b", "c", "d", "d"])
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.questions.QuestionCreationValidationError: Question options must be unique (got ['a', 'b', 'c', 'd', 'd']).
+        
+        We allow dynamic question options, which are strings of the form '{{ question_options }}'.
+        
+        >>> _ = q_class("{{dynamic_options}}")
+        >>> _ = q_class("dynamic_options")
+        Traceback (most recent call last):
+        ...
+        edsl.exceptions.questions.QuestionCreationValidationError: Dynamic question options must be of the form: '{{ question_options }}'.
+        """
+        if isinstance(value, str):
+            # Check if the string is a dynamic question option
+            if "{{" in value and "}}" in value:
+                return None
+            else:
+                raise QuestionCreationValidationError(
+                    "Dynamic question options must be of the form: '{{ question_options }}'."
+                )
         if not isinstance(value, list):
             raise QuestionCreationValidationError(
                 f"Question options must be a list (got {value})."
@@ -339,3 +372,8 @@ class QuestionTextDescriptor(BaseDescriptor):
                 f"WARNING: Question text contains a single-braced substring: If you intended to parameterize the question with a Scenario this should be changed to a double-braced substring, e.g. {{variable}}.\nSee details on constructing Scenarios in the docs: https://docs.expectedparrot.com/en/latest/scenarios.html",
                 UserWarning,
             )
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod(optionflags=doctest.ELLIPSIS)