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

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)
 

edsl/scenarios/handlers/py_file_store.py

@@ -35,7 +35,6 @@ class PyMethods(FileMethods):
         import pygments
         from pygments.lexers import PythonLexer
         from pygments.formatters import HtmlFormatter
-        from pygments.styles import get_style_by_name
 
         try:
             with open(self.path, "r", encoding="utf-8") as f:

edsl/scenarios/handlers/sql_file_store.py

@@ -1,6 +1,6 @@
 import tempfile
 import re
-from typing import List, Optional
+from typing import List
 import textwrap
 
 
@@ -217,9 +217,6 @@ class SqlMethods(FileMethods):
         This is a simple check and doesn't replace proper SQL parsing.
         """
         try:
-            with open(self.path, "r", encoding="utf-8") as f:
-                content = f.read()
-
             statements = self.split_statements()
             for stmt in statements:
                 # Check for basic SQL keywords

edsl/scenarios/handlers/sqlite_file_store.py

@@ -50,7 +50,6 @@ class SQLiteMethods(FileMethods):
         """
         Opens the database with the system's default SQLite viewer if available.
         """
-        import os
         import subprocess
 
         if os.path.exists(self.path):

edsl/scenarios/handlers/txt_file_store.py

@@ -23,7 +23,7 @@ class TxtMethods(FileMethods):
             print("TXT file was not found.")
 
     def view_notebook(self):
-        from IPython.display import FileLink, display
+        from ...display import FileLink, display
 
         display(FileLink(self.path))
 

edsl/scenarios/scenario.py

@@ -20,7 +20,6 @@ information to questions in surveys.
 from __future__ import annotations
 import copy
 import os
-import json
 from collections import UserDict
 from typing import Union, List, Optional, TYPE_CHECKING, Collection
 from uuid import uuid4