edsl 0.1.48__py3-none-any.whl → 0.1.50__py3-none-any.whl

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:
     """

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,7 +258,7 @@ 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:
+            if key in expression and key + "." not in expression:
                 raise ValueError(
                     f"Key by iself {key} is problematic. Use the full key {key + '.' + key} name instead."
                 )
@@ -307,7 +306,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()
@@ -579,7 +578,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:

edsl/results/results.py

@@ -41,7 +41,7 @@ import json
 import random
 import warnings
 from collections import UserList, defaultdict
-from typing import Optional, Callable, Any, Type, Union, List, TYPE_CHECKING
+from typing import Optional, Callable, Any, Union, List, TYPE_CHECKING
 from bisect import bisect_left
 
 from ..base import Base
@@ -50,7 +50,6 @@ if TYPE_CHECKING:
     from ..surveys import Survey
     from ..data import Cache
     from ..agents import AgentList
-    from ..language_models import Model
     from ..scenarios import ScenarioList
     from ..results import Result
     from ..tasks import TaskHistory
@@ -113,13 +112,13 @@ def ensure_ready(method):
 
 class NotReadyObject:
     """A placeholder object that prints a message when any attribute is accessed."""
-    def __init__(self, name: str, job_info: 'RemoteJobInfo'):
+    def __init__(self, name: str, job_info: 'Any'):
         self.name = name
         self.job_info = job_info
         #print(f"Not ready to call {name}")
 
     def __repr__(self):
-        message = f"""Results not ready - job still running on server."""
+        message = """Results not ready - job still running on server."""
         for key, value in self.job_info.creation_data.items():
             message += f"\n{key}: {value}"
         return message
@@ -231,26 +230,6 @@ class Results(UserList, ResultsOperationsMixin, Base):
         if hasattr(self, "_add_output_functions"):
             self._add_output_functions()
 
-    def long(self):
-        return self.table().long()
-
-    def print_long(self, max_rows: int = None) -> None:
-        """Print the results in long format.
-
-        >>> from edsl.results import Results
-        >>> r = Results.example()
-        >>> r.select('how_feeling').print_long(max_rows = 2)
-        ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━┓
-        ┃ Result index ┃ Key         ┃ Value ┃
-        ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━┩
-        │ 0            │ how_feeling │ OK    │
-        │ 1            │ how_feeling │ Great │
-        └──────────────┴─────────────┴───────┘
-        """
-        from edsl.utilities.interface import print_results_long
-
-        print_results_long(self, max_rows=max_rows)
-
 
     def _fetch_list(self, data_type: str, key: str) -> list:
         """
@@ -467,7 +446,7 @@ class Results(UserList, ResultsOperationsMixin, Base):
                 self.fetch_remote(self.job_info)
             
             if not self.completed:
-                return f"Results not ready to call"
+                return "Results not ready to call"
         
         return super()._repr_html_()
 
@@ -482,7 +461,7 @@ class Results(UserList, ResultsOperationsMixin, Base):
     def table(
         self,
         *fields,
-        tablefmt: Optional[str] = None,
+        tablefmt: Optional[str] = "rich",
         pretty_labels: Optional[dict] = None,
         print_parameters: Optional[dict] = None,
     ):
@@ -599,7 +578,7 @@ class Results(UserList, ResultsOperationsMixin, Base):
     def hashes(self) -> set:
         return set(hash(result) for result in self.data)
 
-    def sample(self, n: int) -> Results:
+    def _sample_legacy(self, n: int) -> Results:
         """Return a random sample of the results.
 
         :param n: The number of samples to return.
@@ -643,7 +622,6 @@ class Results(UserList, ResultsOperationsMixin, Base):
         from ..caching import Cache
         from ..results import Result
         from ..tasks import TaskHistory
-        from ..agents import Agent
 
         survey = Survey.from_dict(data["survey"])
         results_data = [Result.from_dict(r) for r in data["data"]]
@@ -1076,26 +1054,7 @@ class Results(UserList, ResultsOperationsMixin, Base):
             created_columns=self.created_columns + [var_name],
         )
 
-    @ensure_ready
-    def add_column(self, column_name: str, values: list) -> Results:
-        """Adds columns to Results
-
-        >>> r = Results.example()
-        >>> r.add_column('a', [1,2,3, 4]).select('a')
-        Dataset([{'answer.a': [1, 2, 3, 4]}])
-        """
-
-        assert len(values) == len(
-            self.data
-        ), "The number of values must match the number of results."
-        new_results = self.data.copy()
-        for i, result in enumerate(new_results):
-            result["answer"][column_name] = values[i]
-        return Results(
-            survey=self.survey,
-            data=new_results,
-            created_columns=self.created_columns + [column_name],
-        )
+    # Method removed due to duplication (F811)
 
     @ensure_ready
     def rename(self, old_name: str, new_name: str) -> Results:
@@ -1275,7 +1234,7 @@ class Results(UserList, ResultsOperationsMixin, Base):
         def to_numeric_if_possible(v):
             try:
                 return float(v)
-            except:
+            except (ValueError, TypeError):
                 return v
 
         def sort_key(item):
@@ -1444,7 +1403,7 @@ class Results(UserList, ResultsOperationsMixin, Base):
         return [r.score_with_answer_key(answer_key) for r in self.data]
     
 
-    def fetch_remote(self, job_info: "RemoteJobInfo") -> None:
+    def fetch_remote(self, job_info: Any) -> None:
         """
         Fetches the remote Results object using the provided RemoteJobInfo and updates this instance with the remote data.
         
@@ -1532,7 +1491,7 @@ class Results(UserList, ResultsOperationsMixin, Base):
         from ..questions import QuestionFreeText, QuestionDict
         from ..surveys import Survey
         from ..scenarios import Scenario, ScenarioList
-        from ..language_models import Model, ModelList
+        from ..language_models import ModelList
         import pandas as pd
 
         df = self.select("agent.*", "scenario.*", "answer.*", "raw_model_response.*", "prompt.*").to_pandas()

edsl/results/results_selector.py

@@ -11,8 +11,7 @@ from typing import Union, List, Dict, Any, Optional, Tuple, Callable
 import sys
 from collections import defaultdict
 
-from ..dataset import Dataset
-from ..utilities import is_notebook
+# Import is_notebook but defer Dataset import to avoid potential circular imports
 
 from .exceptions import ResultsColumnNotFoundError
 
@@ -67,7 +66,7 @@ class Selector:
         self.columns = columns
         self.items_in_order = []  # Tracks column order for consistent output
 
-    def select(self, *columns: Union[str, List[str]]) -> Optional[Dataset]:
+    def select(self, *columns: Union[str, List[str]]) -> Optional[Any]:
         """
         Select specific columns from the data and return as a Dataset.
         
@@ -106,11 +105,16 @@ class Selector:
             to_fetch = self._get_columns_to_fetch(columns)
             new_data = self._fetch_data(to_fetch)
         except ResultsColumnNotFoundError as e:
-            if is_notebook():
+            # Check is_notebook with explicit import to ensure mock works
+            from edsl.utilities import is_notebook as is_notebook_check
+            if is_notebook_check():
                 print("Error:", e, file=sys.stderr)
                 return None
             else:
                 raise e
+                
+        # Import Dataset here to avoid circular import issues
+        from edsl.dataset import Dataset
         return Dataset(new_data)
 
     def _normalize_columns(self, columns: Union[str, List[str]]) -> Tuple[str, ...]:

edsl/scenarios/PdfExtractor.py

@@ -10,8 +10,8 @@ class PdfExtractor:
     def _check_pymupdf(self):
         """Check if PyMuPDF is installed."""
         try:
-            import fitz
-            return True
+            import importlib.util
+            return importlib.util.find_spec("fitz") is not None
         except ImportError:
             return False
         

edsl/scenarios/construct_download_link.py

@@ -1,46 +1,70 @@
+from __future__ import annotations
+
 import os
-import mimetypes
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..display import HTML
+    from ..scenarios import FileStore
 
 
 class ConstructDownloadLink:
-    """
-    A class to create HTML download links for FileStore objects.
-    The links can be displayed in Jupyter notebooks or other web interfaces.
-
-    >>> from edsl import FileStore
-    >>> fs = FileStore.example("txt")
-    >>> link = ConstructDownloadLink(fs)
-    >>> link.create_link()
-    <IPython.core.display.HTML object>
+    """Create HTML download links for FileStore objects.
+
+    This class generates downloadable HTML links for FileStore objects that can be
+    displayed in Jupyter notebooks or other web interfaces. The links are styled
+    and allow for custom filenames and styling options.
+
+    Examples:
+        >>> from edsl import FileStore
+        >>> fs = FileStore.example("txt")
+        >>> link = ConstructDownloadLink(fs)
+        >>> new_link = link.create_link()
     """
 
-    def __init__(self, filestore):
-        """
-        Initialize with a FileStore object.
+    def __init__(self, filestore: FileStore):
+        """Initialize a new download link constructor.
 
         Args:
-            filestore: A FileStore object containing the file to be made downloadable
+            filestore: A FileStore object containing the file to be made downloadable.
         """
         self.filestore = filestore
 
-    def create_link(self, custom_filename=None, style=None):
-        from IPython.display import HTML
+    def create_link(
+        self, custom_filename: Optional[str] = None, style: Optional[dict] = None
+    ) -> HTML:
+        """Create an HTML download link wrapped in an HTML display object.
+
+        Args:
+            custom_filename: Optional custom name for the downloaded file.
+                If None, uses the original filename.
+            style: Optional dictionary of CSS styles for the download button.
+                If None, uses default styling.
+
+        Returns:
+            HTML: A displayable HTML object containing the styled download link.
+        """
+        from ..display import HTML
 
         html = self.html_create_link(custom_filename, style)
         return HTML(html)
 
-    def html_create_link(self, custom_filename=None, style=None):
-        """
-        Create an HTML download link for the file.
+    def html_create_link(
+        self, custom_filename: Optional[str] = None, style: Optional[dict] = None
+    ) -> str:
+        """Generate an HTML download link string.
+
+        Creates a styled HTML anchor tag that triggers a file download when clicked.
+        The file data is embedded as a base64-encoded data URI.
 
         Args:
-            custom_filename (str, optional): Custom name for the downloaded file.
-                                          If None, uses original filename.
-            style (dict, optional): Custom CSS styles for the download button.
-                                  If None, uses default styling.
+            custom_filename: Optional custom name for the downloaded file.
+                If None, uses the original filename.
+            style: Optional dictionary of CSS styles for the download button.
+                If None, uses default styling.
 
         Returns:
-            IPython.display.HTML: HTML object containing the download link
+            str: HTML string containing the styled download link.
         """
 
         # Get filename from path or use custom filename
@@ -78,19 +102,28 @@ class ConstructDownloadLink:
         """
         return html
 
-    def create_multiple_links(self, files, custom_filenames=None, style=None):
-        """
-        Create multiple download links at once.
-        Useful when you want to provide different versions of the same file
-        or related files together.
+    def create_multiple_links(
+        self,
+        files: list[FileStore],
+        custom_filenames: Optional[list[str | None]] = None,
+        style: Optional[dict] = None,
+    ) -> HTML:
+        """Create multiple download links in a horizontal layout.
+
+        Generates a collection of download links arranged horizontally with consistent
+        styling. Useful for providing different versions of the same file or related
+        files together.
 
         Args:
-            files (list): List of FileStore objects
-            custom_filenames (list, optional): List of custom filenames for downloads
-            style (dict, optional): Custom CSS styles for the download buttons
+            files: List of FileStore objects to create download links for.
+            custom_filenames: Optional list of custom filenames for downloads.
+                If None, original filenames will be used for all files.
+            style: Optional dictionary of CSS styles applied to all download buttons.
+                If None, uses default styling.
 
         Returns:
-            IPython.display.HTML: HTML object containing all download links
+            HTML: A displayable HTML object containing all download links arranged
+                horizontally.
         """
         if custom_filenames is None:
             custom_filenames = [None] * len(files)
@@ -104,7 +137,8 @@ class ConstructDownloadLink:
                 )._repr_html_()
             )
 
-        from IPython.display import HTML
+        from ..display import HTML
+
         return HTML(
             '<div style="display: flex; gap: 10px;">' + "".join(html_parts) + "</div>"
         )
@@ -113,4 +147,4 @@ class ConstructDownloadLink:
 if __name__ == "__main__":
     import doctest
 
-    doctest.testmod()
+    doctest.testmod(optionflags=doctest.ELLIPSIS | doctest.NORMALIZE_WHITESPACE)

edsl/scenarios/directory_scanner.py

@@ -8,9 +8,8 @@ the matching files.
 """
 
 from dataclasses import dataclass
-from typing import Optional, List, Iterator, TypeVar, Generic, Callable, Any
+from typing import Optional, List, Iterator, TypeVar, Callable
 import os
-from pathlib import Path
 
 # Generic type variable for the factory function's return type
 T = TypeVar("T")
@@ -193,24 +192,44 @@ class DirectoryScanner:
             Returns:
                 True if the file should be included, False otherwise.
             """
+            # Get filename and extension
+            basename = os.path.basename(filepath)
             _, ext = os.path.splitext(filepath)
             ext = ext[1:] if ext else ""  # Remove leading dot from extension
-
-            # Handle no extension case
-            if not ext:
-                return include_no_extension
-
-            # Check exclusions first (they take precedence)
+            
+            # Skip system files like .DS_Store by default
+            if basename == '.DS_Store':
+                return False
+            
+            # If there's a specific allow list and we have a wildcard filter
+            if suffix_allow_list:
+                # Only include files with the allowed extensions
+                return ext in suffix_allow_list
+            
+            # Check exclusions (they take precedence)
             if suffix_exclude_list and ext in suffix_exclude_list:
                 return False
 
             # Check example suffix if specified
-            if example_suffix and not filepath.endswith(example_suffix):
-                return False
-
-            # Check allowed suffixes if specified
-            if suffix_allow_list and ext not in suffix_allow_list:
-                return False
+            if example_suffix:
+                # Handle wildcard patterns
+                if '*' in example_suffix:
+                    import fnmatch
+                    basename = os.path.basename(filepath)
+                    # Try to match just the filename if the pattern doesn't contain path separators
+                    if '/' not in example_suffix and '\\' not in example_suffix:
+                        if not fnmatch.fnmatch(basename, example_suffix):
+                            return False
+                    else:
+                        # Match the full path
+                        if not fnmatch.fnmatch(filepath, example_suffix):
+                            return False
+                elif not filepath.endswith(example_suffix):
+                    return False
+                
+            # Handle no extension case
+            if not ext:
+                return include_no_extension
 
             return True
 

edsl/scenarios/document_chunker.py

@@ -9,7 +9,7 @@ limits.
 """
 
 from __future__ import annotations
-from typing import Optional, Generator, TYPE_CHECKING, List, Union
+from typing import Optional, Generator
 import copy
 import hashlib