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

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 ..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 ..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, List
+
+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[Optional[str]]] = 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
 

edsl/scenarios/exceptions.py

@@ -7,7 +7,6 @@ that can occur when working with Scenarios, ScenarioLists, and related component
 """
 
 import re
-from typing import List
 
 from ..base import BaseException
 
@@ -16,11 +15,13 @@ class AgentListError(BaseException):
     """
     Exception raised for errors related to AgentList operations.
     
-    This exception is raised when there are issues with creating, modifying,
-    or using an AgentList in conjunction with scenarios.
+    This exception appears to be a duplicate of the exception defined in
+    edsl.agents.exceptions. It exists here for legacy reasons but is not
+    actively used from this module.
     
-    Args:
-        message: A description of the error that occurred.
+    Note: This exception is defined but not used from this module. The AgentListError
+    from edsl.agents.exceptions is used instead. This raises Exception("not used")
+    to indicate this state.
     """
     
     def __init__(self, message: str):
@@ -37,9 +38,24 @@ class ScenarioError(BaseException):
     """
     Exception raised for errors related to Scenario operations.
     
-    This exception is raised when there are issues with creating, modifying,
-    or using Scenarios. It automatically includes a link to the documentation
-    in the error message and makes URLs clickable in terminal output.
+    This exception is raised when:
+    - Invalid data is passed to initialize a Scenario (not convertible to dictionary)
+    - Required fields are missing in scenario data
+    - File operations fail when loading scenarios from files
+    - Scenario content cannot be properly parsed or processed
+    - Scenario lists encounter issues with data formats or operations
+    
+    To fix this error:
+    1. Check that your scenario data is properly formatted (valid dictionary or convertible to one)
+    2. Ensure all required fields for a scenario are present
+    3. Verify file paths and permissions when loading from files
+    4. Check for syntax or format errors in scenario content
+    
+    Examples:
+        ```python
+        Scenario(123)  # Raises ScenarioError (not convertible to dictionary)
+        Scenario({"invalid_format": True})  # May raise ScenarioError (missing required fields)
+        ```
     
     Args:
         message: A description of the error that occurred.
@@ -84,9 +100,10 @@ class ScenarioError(BaseException):
             The text with URLs converted to clickable links.
             
         Example:
-            >>> error = ScenarioError("See docs at https://example.com")
-            >>> s = str(error)  # Returns the message with clickable link
-            ...
+            ```python
+            error = ScenarioError("See docs at https://example.com")
+            s = str(error)  # Returns the message with clickable link
+            ```
         """
         url_pattern = r"https?://[^\s]+"
         urls = re.findall(url_pattern, text)
@@ -96,6 +113,213 @@ class ScenarioError(BaseException):
         return text
 
 
-if __name__ == "__main__":
-    import doctest
-    doctest.testmod(optionflags=doctest.ELLIPSIS)
+class FileNotFoundScenarioError(ScenarioError):
+    """
+    Exception raised when a file needed for a scenario cannot be found.
+    
+    This exception occurs when:
+    - A file specified in a file path does not exist
+    - A referenced image, document, or other resource is missing
+    - A directory expected to contain scenario files is not found
+    
+    To fix this error:
+    1. Check that the file path is correct and the file exists
+    2. Verify file system permissions allow access to the file
+    3. Ensure any referenced external resources are properly available
+    
+    Examples:
+        ```python
+        Scenario.from_file("/path/to/nonexistent/file.json")  # Raises FileNotFoundScenarioError
+        ```
+    """
+    
+    def __init__(self, message: str):
+        """
+        Initialize the FileNotFoundScenarioError with a message.
+        
+        Args:
+            message: A description of the error that occurred.
+        """
+        super().__init__(message)
+
+
+class ImportScenarioError(ScenarioError):
+    """
+    Exception raised when importing a library needed for scenario operations fails.
+    
+    This exception occurs when:
+    - A required library for handling specific file types is not installed
+    - A module needed for processing scenario data cannot be imported
+    - Optional dependencies for advanced features are missing
+    
+    To fix this error:
+    1. Install the required dependencies mentioned in the error message
+    2. Check for version conflicts between dependencies
+    3. Ensure your environment has all necessary packages
+    
+    Examples:
+        ```python
+        # When attempting to load a PDF without the pdf dependencies
+        Scenario.from_pdf("document.pdf")  # Raises ImportScenarioError
+        ```
+    """
+    
+    def __init__(self, message: str):
+        """
+        Initialize the ImportScenarioError with a message.
+        
+        Args:
+            message: A description of the error that occurred.
+        """
+        super().__init__(message)
+
+
+class TypeScenarioError(ScenarioError):
+    """
+    Exception raised when there's a type mismatch in scenario operations.
+    
+    This exception occurs when:
+    - A parameter is of the wrong type for a scenario operation
+    - Incompatible types are used in scenario methods
+    - Type conversion fails during scenario processing
+    
+    To fix this error:
+    1. Check the types of parameters passed to scenario methods
+    2. Ensure data structures match what scenario operations expect
+    3. Verify that operations between scenarios and other objects are compatible
+    
+    Examples:
+        ```python
+        scenario * "invalid_operand"  # Raises TypeScenarioError
+        ```
+    """
+    
+    def __init__(self, message: str):
+        """
+        Initialize the TypeScenarioError with a message.
+        
+        Args:
+            message: A description of the error that occurred.
+        """
+        super().__init__(message)
+
+
+class ValueScenarioError(ScenarioError):
+    """
+    Exception raised when there's an invalid value in scenario operations.
+    
+    This exception occurs when:
+    - A parameter value is out of its acceptable range
+    - Invalid formats are provided for scenario data
+    - Operation parameters are invalid for the requested action
+    
+    To fix this error:
+    1. Check parameter values against allowed ranges or formats
+    2. Verify inputs meet the requirements for specific operations
+    3. Ensure data formats match what's expected by scenario methods
+    
+    Examples:
+        ```python
+        scenario_list.to_table(output_type="invalid_format")  # Raises ValueScenarioError
+        ```
+    """
+    
+    def __init__(self, message: str):
+        """
+        Initialize the ValueScenarioError with a message.
+        
+        Args:
+            message: A description of the error that occurred.
+        """
+        super().__init__(message)
+
+
+class AttributeScenarioError(ScenarioError):
+    """
+    Exception raised when accessing a non-existent attribute in a scenario.
+    
+    This exception occurs when:
+    - Attempting to access a field not present in a scenario
+    - Using an attribute accessor on a scenario for a missing property
+    - CSV or dataframe column access issues
+    
+    To fix this error:
+    1. Check that the attribute name is correct
+    2. Verify the scenario contains the expected fields
+    3. Use hasattr() to check for attribute existence before access
+    
+    Examples:
+        ```python
+        scenario.nonexistent_attribute  # Raises AttributeScenarioError
+        ```
+    """
+    
+    def __init__(self, message: str):
+        """
+        Initialize the AttributeScenarioError with a message.
+        
+        Args:
+            message: A description of the error that occurred.
+        """
+        super().__init__(message)
+
+
+class IndexScenarioError(ScenarioError):
+    """
+    Exception raised when an index is out of range in scenario operations.
+    
+    This exception occurs when:
+    - Accessing a scenario index outside the valid range
+    - Using an invalid index in a scenario list operation
+    - Sequence operations with invalid indices
+    
+    To fix this error:
+    1. Check array boundaries before accessing elements
+    2. Verify indices are within valid ranges for the collection
+    3. Use len() to determine the valid index range
+    
+    Examples:
+        ```python
+        scenario_list[999]  # Raises IndexScenarioError if fewer items exist
+        ```
+    """
+    
+    def __init__(self, message: str):
+        """
+        Initialize the IndexScenarioError with a message.
+        
+        Args:
+            message: A description of the error that occurred.
+        """
+        super().__init__(message)
+
+
+class KeyScenarioError(ScenarioError):
+    """
+    Exception raised when a key is missing in scenario operations.
+    
+    This exception occurs when:
+    - Accessing a non-existent key in a scenario
+    - Using key-based access for missing fields
+    - Dictionary operations with invalid keys
+    
+    To fix this error:
+    1. Check if the key exists before attempting access
+    2. Use dictionary get() method with default values for safer access
+    3. Verify the scenario contains the expected keys
+    
+    Examples:
+        ```python
+        scenario["missing_key"]  # Raises KeyScenarioError
+        ```
+    """
+    
+    def __init__(self, message: str):
+        """
+        Initialize the KeyScenarioError with a message.
+        
+        Args:
+            message: A description of the error that occurred.
+        """
+        super().__init__(message)
+

edsl/scenarios/file_methods.py

@@ -40,7 +40,7 @@ class FileMethods(ABC):
 
         for ep in entries:
             try:
-                handler_class = ep.load()
+                ep.load()
                 # Registration happens automatically via __init_subclass__
             except Exception as e:
                 print(f"Failed to load external handler {ep.name}: {e}")

edsl/scenarios/file_store.py

@@ -4,16 +4,19 @@ import tempfile
 import mimetypes
 import asyncio
 import os
-from typing import Dict, Any, IO, Optional
+from typing import Dict, IO, Optional
 from typing import Union
 from uuid import UUID
 import time
-from typing import Dict, Any, IO, Optional, List, Union, Literal
+from typing import List, Literal, TYPE_CHECKING
 
 from .scenario import Scenario
 from ..utilities import remove_edsl_version
 from .file_methods import FileMethods
 
+if TYPE_CHECKING:
+    from .scenario_list import ScenarioList
+
 class FileStore(Scenario):
     """
     A specialized Scenario subclass for managing file content and metadata.
@@ -246,6 +249,7 @@ class FileStore(Scenario):
         Returns:
             ScenarioList containing FileStore objects with their corresponding URLs
         """
+        # Import here to avoid circular imports
         from .scenario_list import ScenarioList
 
         try:
@@ -282,7 +286,7 @@ class FileStore(Scenario):
 
     @property
     def size(self) -> int:
-        if self.base64_string != None:
+        if self.base64_string is not None:
             return (len(self.base64_string) / 4.0) * 3  # from base64 to char size
         return os.path.getsize(self.path)
 

edsl/scenarios/handlers/__init__.py

@@ -1,3 +1,20 @@
+__all__ = [
+    "PdfMethods",
+    "DocxMethods",
+    "PngMethods",
+    "TxtMethods",
+    "HtmlMethods",
+    "MarkdownMethods",
+    "CsvMethods",
+    "JsonMethods",
+    "SqlMethods",
+    "PptxMethods",
+    "LaTeXMethods",
+    "PyMethods",
+    "SQLiteMethods",
+    "JpegMethods"
+]
+
 from .pdf_file_store import PdfMethods
 from .docx_file_store import DocxMethods
 from .png_file_store import PngMethods

edsl/scenarios/handlers/docx_file_store.py

@@ -2,9 +2,6 @@ import os
 import tempfile
 
 from ..file_methods import FileMethods
-from ..scenario import Scenario
-from ..scenario_list import ScenarioList
-from ..file_store import FileStore
 
 class DocxMethods(FileMethods):
     suffix = "docx"
@@ -59,8 +56,6 @@ class DocxMethods(FileMethods):
 
     def example(self):
         from docx import Document
-        from ..scenario import Scenario
-        from ..scenario_list import ScenarioList
 
         os.makedirs("test_dir", exist_ok=True)
         doc1 = Document()

edsl/scenarios/handlers/pdf_file_store.py

@@ -27,7 +27,6 @@ class PdfMethods(FileMethods):
         return text
 
     def view_system(self):
-        import os
         import subprocess
 
         if os.path.exists(self.path):

edsl/scenarios/handlers/pptx_file_store.py

@@ -2,9 +2,6 @@ from ..file_methods import FileMethods
 import os
 import tempfile
 
-from ..scenario import Scenario
-from ..scenario_list import ScenarioList
-from ..file_store import FileStore
 
 class PptxMethods(FileMethods):
     suffix = "pptx"
@@ -76,8 +73,6 @@ class PptxMethods(FileMethods):
 
     def example(self):
         from pptx import Presentation
-        from ..scenario import Scenario
-        from ..scenario_list import ScenarioList
 
         os.makedirs("test_dir", exist_ok=True)