edsl 0.1.49__py3-none-any.whl → 0.1.51__py3-none-any.whl

edsl/questions/{derived/question_yes_no.py → question_yes_no.py}

@@ -1,9 +1,8 @@
 from __future__ import annotations
 from typing import Optional
-from ..descriptors import QuestionOptionsDescriptor
-from ..question_multiple_choice import QuestionMultipleChoice
-
-from ..decorators import inject_exception
+from .descriptors import QuestionOptionsDescriptor
+from .question_multiple_choice import QuestionMultipleChoice
+from .decorators import inject_exception
 
 
 class QuestionYesNo(QuestionMultipleChoice):

edsl/questions/register_questions_meta.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 from abc import ABCMeta
 import inspect
 
-from ..enums import QuestionType
 from .exceptions import QuestionMissingTypeError, QuestionBadTypeError
 
 class RegisterQuestionsMeta(ABCMeta):
@@ -63,7 +62,8 @@ class RegisterQuestionsMeta(ABCMeta):
             if hasattr(cls, "question_type"):
                 d[cls.question_type] = cls
             else:
-                raise Exception(
+                from .exceptions import QuestionMissingTypeError
+                raise QuestionMissingTypeError(
                     f"Class {classname} does not have a question_type class attribute"
                 )
         return d

edsl/questions/response_validator_abc.py

@@ -1,7 +1,7 @@
-from abc import ABC, abstractmethod
-from typing import Optional, Any, List, TypedDict, TYPE_CHECKING
+from abc import ABC
+from typing import Optional, List, TYPE_CHECKING
 
-from pydantic import BaseModel, Field, field_validator, ValidationError
+from pydantic import BaseModel, ValidationError
 
 from .exceptions import QuestionAnswerValidationError
 from .ExceptionExplainer import ExceptionExplainer
@@ -22,7 +22,8 @@ class ResponseValidatorABC(ABC):
         required_class_vars = ["required_params", "valid_examples", "invalid_examples"]
         for var in required_class_vars:
             if not hasattr(cls, var):
-                raise ValueError(f"Class {cls.__name__} must have a '{var}' attribute.")
+                from .exceptions import QuestionValueError
+                raise QuestionValueError(f"Class {cls.__name__} must have a '{var}' attribute.")
 
     def __init__(
         self,
@@ -41,7 +42,8 @@ class ResponseValidatorABC(ABC):
             param for param in self.required_params if param not in kwargs
         ]
         if missing_params:
-            raise ValueError(
+            from .exceptions import QuestionValueError
+            raise QuestionValueError(
                 f"Missing required parameters: {', '.join(missing_params)}"
             )
 
@@ -75,8 +77,12 @@ class ResponseValidatorABC(ABC):
         ConstrainedNumericResponse(answer=42, comment=None, generated_tokens=None)
         """
         try:
-            return self.response_model(**data)
-        except ValidationError as e:
+            # Use model_validate instead of direct instantiation
+            return self.response_model.model_validate(data)
+        except (ValidationError, QuestionAnswerValidationError) as e:
+            # Pass through QuestionAnswerValidationError or convert ValidationError
+            if isinstance(e, QuestionAnswerValidationError):
+                raise
             raise QuestionAnswerValidationError(
                 message=str(e), pydantic_error=e, data=data, model=self.response_model
             )
@@ -98,20 +104,12 @@ class ResponseValidatorABC(ABC):
         {'answer': 42, 'comment': None, 'generated_tokens': None}
         >>> rv.max_value
         86.7
-        >>> rv.validate({"answer": "120"})
-        Traceback (most recent call last):
-        ...
-        edsl.questions.exceptions.QuestionAnswerValidationError:...
         >>> from edsl import QuestionNumerical
         >>> q = QuestionNumerical.example()
         >>> q.permissive = True
         >>> rv = q.response_validator
         >>> rv.validate({"answer": "120"})
         {'answer': 120, 'comment': None, 'generated_tokens': None}
-        >>> rv.validate({"answer": "poo"})
-        Traceback (most recent call last):
-        ...
-        edsl.questions.exceptions.QuestionAnswerValidationError:...
         """
         proposed_edsl_answer_dict = self._preprocess(raw_edsl_answer_dict)
         try:

edsl/questions/response_validator_factory.py

@@ -1,5 +1,6 @@
-from edsl.questions.data_structures import BaseModel
-from edsl.questions.response_validator_abc import ResponseValidatorABC
+from typing import Type, List
+from .data_structures import BaseModel
+from .response_validator_abc import ResponseValidatorABC
 
 
 class ResponseValidatorFactory:
@@ -9,7 +10,7 @@ class ResponseValidatorFactory:
         self.question = question
 
     @property
-    def response_model(self) -> type["BaseModel"]:
+    def response_model(self) -> Type["BaseModel"]:
         if self.question._response_model is not None:
             return self.question._response_model
         else:
@@ -18,17 +19,14 @@ class ResponseValidatorFactory:
     @property
     def response_validator(self) -> "ResponseValidatorABC":
         """Return the response validator."""
-        params = (
-            {
-                "response_model": self.question.response_model,
-            }
-            | {k: getattr(self.question, k) for k in self.validator_parameters}
-            | {"exception_to_throw": getattr(self.question, "exception_to_throw", None)}
-            | {"override_answer": getattr(self.question, "override_answer", None)}
-        )
+        params = {}
+        params.update({"response_model": self.question.response_model})
+        params.update({k: getattr(self.question, k) for k in self.validator_parameters})
+        params.update({"exception_to_throw": getattr(self.question, "exception_to_throw", None)})
+        params.update({"override_answer": getattr(self.question, "override_answer", None)})
         return self.question.response_validator_class(**params)
 
     @property
-    def validator_parameters(self) -> list[str]:
+    def validator_parameters(self) -> List[str]:
         """Return the parameters required for the response validator."""
         return self.question.response_validator_class.required_params

edsl/questions/templates/dict/answering_instructions.jinja

@@ -1,4 +1,5 @@
 Please respond with a dictionary using the following keys: {{ answer_keys | join(', ') }}.
+Do not include "python" for create a code block. Just return the dictionary.
 
 {% if value_descriptions %}
 Here are descriptions of the values to provide:

edsl/questions/templates/rank/question_presentation.jinja

@@ -11,5 +11,5 @@ The options are:
 {% endfor %}
 {% endif %}
 {% if num_selections %}
-You can inlcude up to {{num_selections}} options in your answer.
+You have to include {{num_selections}} options in your answer.
 {% endif %}

edsl/results/__init__.py

@@ -2,4 +2,4 @@
 from .results import Results
 from .result import Result
 
-__all__ = ["Results"]
+__all__ = ["Results", "Result"]

edsl/results/exceptions.py

@@ -2,28 +2,162 @@
 from ..base import BaseException
 
 class ResultsError(BaseException):
-    relevant_docs = "https://docs.expectedparrot.com/en/latest/results.html"
+    """
+    Base exception class for all results-related errors.
+    
+    This is the parent class for all exceptions related to Results objects
+    operations, including data manipulation, selection, and filtering.
+    
+    This exception is raised in the following cases:
+    - When trying to add two Results objects with different surveys or created columns
+    - When trying to sample more items than available
+    - When Survey is not defined when accessing answer_keys
+    - When fetching remote Results fails
+    - When inappropriate model types are used with Results methods
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/results.html"
 
 
 class ResultsDeserializationError(ResultsError):
-    pass
+    """
+    Exception raised when Results object deserialization fails.
+    
+    This exception occurs when a Results object cannot be properly reconstructed
+    from its serialized representation, typically during from_dict() operations.
+    
+    Reasons this might occur:
+    - Missing required fields in the serialized data
+    - Corrupted serialized data
+    - Version incompatibility between serialized data and current code
+    
+    To fix this error:
+    1. Check that the serialized data is complete and uncorrupted
+    2. Ensure you're using a compatible version of EDSL to deserialize the data
+    3. If the issue persists, you may need to recreate the results from raw data
+    
+    Examples:
+        ```python
+        Results.from_dict(incomplete_or_corrupted_data)  # Raises ResultsDeserializationError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/results.html#saving-and-loading-results"
 
 
 class ResultsBadMutationstringError(ResultsError):
-    pass
+    """
+    Exception raised when an invalid mutation string is provided.
+    
+    This exception occurs when the mutation string doesn't follow the required format,
+    which should be 'column_name = expression' where expression is a valid Python
+    expression that can reference other columns.
+    
+    To fix this error:
+    1. Ensure your mutation string contains an equals sign
+    2. Check that the left side is a valid column name
+    3. Verify the right side is a valid Python expression
+    
+    Examples:
+        ```python
+        results.mutate("invalid_mutation_no_equals")  # Raises ResultsBadMutationstringError
+        results.mutate("column_name == value")  # Raises ResultsBadMutationstringError (should use single =)
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/results.html#creating-new-columns"
 
 
 class ResultsColumnNotFoundError(ResultsError):
-    pass
+    """
+    Exception raised when attempting to access a non-existent column.
+    
+    This exception occurs when trying to access, filter, or perform operations
+    on a column that doesn't exist in the Results object.
+    
+    To fix this error:
+    1. Check for typos in the column name
+    2. Verify the column exists using results.columns() or results.df.columns
+    3. If the column is dynamic, ensure it has been created with mutate() first
+    
+    The error message typically includes suggestions for similar column names 
+    that do exist, which can help identify typos.
+    
+    Examples:
+        ```python
+        results.table(keys=["non_existent_column"])  # Raises ResultsColumnNotFoundError
+        results.select("typo_in_column_name")  # Raises ResultsColumnNotFoundError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/results.html#selecting-columns"
 
 
 class ResultsInvalidNameError(ResultsError):
-    pass
+    """
+    Exception raised when an invalid column name is provided.
+    
+    This exception occurs when:
+    - The provided name is not a valid Python identifier
+    - The name conflicts with reserved names or methods
+    - The name contains invalid characters or starts with a number
+    
+    To fix this error:
+    1. Use names that follow Python variable naming rules
+    2. Avoid using reserved words or existing method names
+    3. Use only letters, numbers, and underscores (not starting with a number)
+    
+    Examples:
+        ```python
+        results.mutate("123invalid = 1")  # Raises ResultsInvalidNameError (starts with number)
+        results.mutate("invalid-name = 1")  # Raises ResultsInvalidNameError (contains hyphen)
+        results.mutate("filter = 1")  # Raises ResultsInvalidNameError (reserved method name)
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/results.html#creating-new-columns"
 
 
 class ResultsMutateError(ResultsError):
-    pass
+    """
+    Exception raised when a mutation operation fails.
+    
+    This exception occurs when an error happens during the execution of a mutation
+    expression, such as:
+    - Syntax errors in the expression
+    - Reference to non-existent columns
+    - Type errors in operations (e.g., adding a string to a number)
+    
+    To fix this error:
+    1. Check the expression syntax
+    2. Verify all columns referenced in the expression exist
+    3. Ensure type compatibility in operations
+    4. Test the expression with simple cases first
+    
+    Examples:
+        ```python
+        results.mutate("new_col = old_col + 'text'")  # Raises ResultsMutateError if old_col contains numbers
+        results.mutate("new_col = undefined_col + 1")  # Raises ResultsMutateError if undefined_col doesn't exist
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/results.html#creating-new-columns"
 
 
 class ResultsFilterError(ResultsError):
-    pass
+    """
+    Exception raised when a filter operation fails.
+    
+    This exception occurs when there's an error in the filter expression, such as:
+    - Using single equals (=) instead of double equals (==) for comparison
+    - Syntax errors in the filter expression
+    - Reference to non-existent columns
+    - Type errors in comparisons
+    
+    To fix this error:
+    1. Use == (double equals) for equality comparisons, not = (single equals)
+    2. Check the filter expression syntax
+    3. Verify all columns referenced in the expression exist
+    4. Ensure type compatibility in comparisons
+    
+    Examples:
+        ```python
+        results.filter("column = value")  # Raises ResultsFilterError (use == instead)
+        results.filter("column == undefined_var")  # Raises ResultsFilterError if undefined_var isn't defined
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/results.html#filtering-results"

edsl/results/report.py

@@ -1,6 +1,5 @@
 import jinja2
 import textwrap
-import warnings
 
 class Report:
     """
@@ -174,7 +173,7 @@ class Report:
 
 if __name__ == "__main__":
     # Suppose you have an existing Dataset
-    from edsl import Results
+    from .. import Results
     ds = Results.example().select("how_feeling", "how_feeling_yesterday")
 
     # Provide a custom template string

edsl/results/result.py

@@ -23,7 +23,7 @@ maintaining a rich object model.
 from __future__ import annotations
 import inspect
 from collections import UserDict
-from typing import Any, Type, Callable, Optional, TYPE_CHECKING, Union
+from typing import Any, Callable, Optional, TYPE_CHECKING, Union
 
 from ..base import Base
 from ..utilities import remove_edsl_version
@@ -35,7 +35,6 @@ if TYPE_CHECKING:
     from ..agents import Agent
     from ..scenarios import Scenario
     from ..language_models import LanguageModel
-    from ..prompts import Prompt
     from ..surveys import Survey
 
 QuestionName = str
@@ -259,15 +258,17 @@ class Result(Base, UserDict):
 
     def check_expression(self, expression: str) -> None:
         for key in self.problem_keys:
-            if key in expression and not key + "." in expression:
-                raise ValueError(
-                    f"Key by iself {key} is problematic. Use the full key {key + '.' + key} name instead."
+            if key in expression and key + "." not in expression:
+                from .exceptions import ResultsColumnNotFoundError
+                raise ResultsColumnNotFoundError(
+                    f"Key by itself {key} is problematic. Use the full key {key + '.' + key} name instead."
                 )
         return None
 
     def code(self):
         """Return a string of code that can be used to recreate the Result object."""
-        raise NotImplementedError
+        from .exceptions import ResultsError
+        raise ResultsError("The code() method is not implemented for Result objects")
 
     @property
     def problem_keys(self) -> list[str]:
@@ -307,7 +308,7 @@ class Result(Base, UserDict):
         return self._combined_dict
 
     @property
-    def problem_keys(self) -> list[str]:
+    def get_problem_keys(self) -> list[str]:
         """Return a list of keys that are problematic."""
         if self._combined_dict is None or self._problem_keys is None:
             self._compute_combined_dict_and_problem_keys()
@@ -568,7 +569,8 @@ class Result(Base, UserDict):
             elif v.default is not v.empty:
                 params[k] = v.default
             else:
-                raise ValueError(f"Parameter {k} not found in Result object")
+                from .exceptions import ResultsError
+                raise ResultsError(f"Parameter {k} not found in Result object")
         return scoring_function(**params)
 
     @classmethod
@@ -579,7 +581,7 @@ class Result(Base, UserDict):
 
         def get_question_results(
             model_response_objects,
-        ) -> dict[str, "EDSLResultObjectInput"]:
+        ) -> dict[str, Any]:
             """Maps the question name to the EDSLResultObjectInput."""
             question_results = {}
             for result in model_response_objects: