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

edsl/scenarios/scenario_list.py

@@ -30,6 +30,8 @@ from typing import (
 import warnings
 import csv
 import random
+import os
+import glob
 from io import StringIO
 import inspect
 from collections import UserList, defaultdict
@@ -57,8 +59,9 @@ from ..dataset import ScenarioListOperationsMixin
 
 from .exceptions import ScenarioError
 from .scenario import Scenario
-from .directory_scanner import DirectoryScanner
 from .scenario_list_pdf_tools import PdfTools
+from .directory_scanner import DirectoryScanner
+from .file_store import FileStore
 
 
 if TYPE_CHECKING:
@@ -887,6 +890,119 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         sl = self.duplicate()
         return ScenarioList([scenario.keep(fields) for scenario in sl])
 
+    @classmethod
+    def from_directory(
+        cls,
+        path: Optional[str] = None,
+        recursive: bool = False,
+    ) -> "ScenarioList":
+        """Create a ScenarioList of FileStore objects from files in a directory.
+        
+        This method scans a directory and creates a FileStore object for each file found,
+        optionally filtering files based on a wildcard pattern. If no path is provided,
+        the current working directory is used.
+        
+        Args:
+            path: The directory path to scan, optionally including a wildcard pattern.
+                 If None, uses the current working directory.
+                 Examples:
+                 - "/path/to/directory" - scans all files in the directory
+                 - "/path/to/directory/*.py" - scans only Python files in the directory
+                 - "*.txt" - scans only text files in the current working directory
+            recursive: Whether to scan subdirectories recursively. Defaults to False.
+            
+        Returns:
+            A ScenarioList containing FileStore objects for all matching files.
+            
+        Raises:
+            FileNotFoundError: If the specified directory does not exist.
+            
+        Examples:
+            # Get all files in the current directory
+            sl = ScenarioList.from_directory()
+            
+            # Get all Python files in a specific directory
+            sl = ScenarioList.from_directory('*.py')
+            
+            # Get all image files in the current directory
+            sl = ScenarioList.from_directory('*.png')
+            
+            # Get all files recursively including subdirectories
+            sl = ScenarioList.from_directory(recursive=True)
+        """
+        # Handle default case - use current directory
+        if path is None:
+            directory_path = os.getcwd()
+            pattern = None
+        else:
+            # Special handling for "**" pattern which indicates recursive scanning
+            has_recursive_pattern = '**' in path if path else False
+            
+            # Check if path contains any wildcard
+            if path and ('*' in path):
+                # Handle "**/*.ext" pattern - find the directory part before the **
+                if has_recursive_pattern:
+                    # Extract the base directory by finding the part before **
+                    parts = path.split('**')
+                    if parts and parts[0]:
+                        # Remove trailing slash if any
+                        directory_path = parts[0].rstrip('/')
+                        if not directory_path:
+                            directory_path = os.getcwd()
+                        # Get the pattern after **
+                        pattern = parts[1] if len(parts) > 1 else None
+                        if pattern and pattern.startswith('/'):
+                            pattern = pattern[1:]  # Remove leading slash
+                    else:
+                        directory_path = os.getcwd()
+                        pattern = None
+                # Handle case where path is just a pattern (e.g., "*.py")
+                elif os.path.dirname(path) == '':
+                    directory_path = os.getcwd()
+                    pattern = os.path.basename(path)
+                else:
+                    # Split into directory and pattern
+                    directory_path = os.path.dirname(path)
+                    if not directory_path:
+                        directory_path = os.getcwd()
+                    pattern = os.path.basename(path)
+            else:
+                # Path is a directory with no pattern
+                directory_path = path
+                pattern = None
+                
+        # Ensure directory exists
+        if not os.path.isdir(directory_path):
+            raise FileNotFoundError(f"Directory not found: {directory_path}")
+        
+        # Create a DirectoryScanner for the directory
+        scanner = DirectoryScanner(directory_path)
+        
+        # Configure wildcard pattern filtering
+        suffix_allow_list = None
+        example_suffix = None
+        
+        if pattern:
+            if pattern.startswith('*.'):
+                # Simple extension filter (e.g., "*.py")
+                suffix_allow_list = [pattern[2:]]
+            elif '*' in pattern:
+                # Other wildcard patterns
+                example_suffix = pattern
+            else:
+                # Handle simple non-wildcard pattern (exact match)
+                example_suffix = pattern
+        
+        # Use scanner to find files and create FileStore objects
+        file_stores = scanner.scan(
+            factory=lambda path: FileStore(path),
+            recursive=recursive,
+            suffix_allow_list=suffix_allow_list,
+            example_suffix=example_suffix
+        )
+        
+        return cls(file_stores)
+                
     @classmethod
     def from_list(
         cls, name: str, values: list, func: Optional[Callable] = None
@@ -903,7 +1019,9 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         ScenarioList([Scenario({'name': 'Alice'}), Scenario({'name': 'Bob'})])
         """
         if not func:
-            func = lambda x: x
+            def identity(x):
+                return x
+            func = identity
         return cls([Scenario({name: func(value)}) for value in values])
 
     def table(
@@ -914,7 +1032,6 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
     ) -> str:
         """Return the ScenarioList as a table."""
 
-        from tabulate import tabulate_formats
 
         if tablefmt is not None and tablefmt not in tabulate_formats:
             raise ValueError(
@@ -951,13 +1068,10 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
 
         Example:
 
-        >>> s = ScenarioList([Scenario({'a': 1, 'b': 2}), Scenario({'a': 3, 'b': 4})])
-        >>> s.reorder_keys(['b', 'a'])
-        ScenarioList([Scenario({'b': 2, 'a': 1}), Scenario({'b': 4, 'a': 3})])
-        >>> s.reorder_keys(['a', 'b', 'c'])
-        Traceback (most recent call last):
-        ...
-        AssertionError
+        # Example:
+        # s = ScenarioList([Scenario({'a': 1, 'b': 2}), Scenario({'a': 3, 'b': 4})])
+        # s.reorder_keys(['b', 'a'])  # Returns a new ScenarioList with reordered keys
+        # Attempting s.reorder_keys(['a', 'b', 'c']) would fail as 'c' is not a valid key
         """
         assert set(new_order) == set(self.parameters)
 
@@ -1020,7 +1134,7 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         return ScenarioList(new_scenarios)
 
     @classmethod
-    def from_list_of_tuples(self, *names: str, values: List[Tuple]) -> ScenarioList:
+    def from_list_of_tuples(self, *names: str, values: List[tuple]) -> ScenarioList:
         sl = ScenarioList.from_list(names[0], [value[0] for value in values])
         for index, name in enumerate(names[1:]):
             sl = sl.add_list(name, [value[index + 1] for value in values])
@@ -1210,7 +1324,6 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         """
         import tempfile
         import requests
-        from docx import Document
 
         if "/edit" in url:
             doc_id = url.split("/d/")[1].split("/edit")[0]
@@ -1468,7 +1581,6 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
             ScenarioList: An instance of the ScenarioList class.
 
         """
-        import pandas as pd
         import tempfile
         import requests
 
@@ -1542,14 +1654,37 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
                 response.raise_for_status()
                 file_obj = StringIO(response.text)
             else:
-                file_obj = open(source, "r")
+                # Try different encodings if the default fails
+                encodings_to_try = ["utf-8", "latin-1", "cp1252", "ISO-8859-1"]
+                last_exception = None
+                file_obj = None
+                
+                for encoding in encodings_to_try:
+                    try:
+                        file_obj = open(source, "r", encoding=encoding)
+                        # Test reading a bit to verify encoding
+                        file_obj.readline()
+                        file_obj.seek(0)  # Reset file position
+                        break
+                    except UnicodeDecodeError as e:
+                        last_exception = e
+                        if file_obj:
+                            file_obj.close()
+                            file_obj = None
+                
+                if file_obj is None:
+                    raise ValueError(f"Could not decode file {source} with any of the attempted encodings. Original error: {last_exception}")
 
             reader = csv.reader(file_obj, delimiter=delimiter)
-            header = next(reader)
-            observations = [Scenario(dict(zip(header, row))) for row in reader]
+            try:
+                header = next(reader)
+                observations = [Scenario(dict(zip(header, row))) for row in reader]
+            except StopIteration:
+                raise ValueError(f"File {source} appears to be empty or has an invalid format")
 
         finally:
-            file_obj.close()
+            if file_obj:
+                file_obj.close()
 
         return cls(observations)
 
@@ -1614,7 +1749,6 @@ class ScenarioList(Base, UserList, ScenarioListOperationsMixin):
         """
         from ..surveys import Survey
         from ..questions import QuestionBase
-        from ..jobs import Jobs
 
         if isinstance(survey, QuestionBase):
             return Survey([survey]).by(self)

edsl/scenarios/scenario_list_pdf_tools.py

@@ -175,6 +175,7 @@ class PdfTools:
                 image_path = os.path.join(output_folder, f"page_{i+1}.{image_format}")
                 image.save(image_path, image_format.upper())
 
+                from ..file_store import FileStore
                 scenario = Scenario({
                     "filepath":image_path,
                     "page":i,

edsl/scenarios/scenario_selector.py

@@ -3,7 +3,6 @@ from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from .scenario_list import ScenarioList
-    from .scenario import Scenario
 
 class ScenarioSelector:
     """

edsl/surveys/__init__.py

@@ -1,8 +1,7 @@
 from .survey import Survey
-from .survey_flow_visualization import SurveyFlowVisualization
-
-from .rules import Rule, RuleCollection
-from .base import EndOfSurvey, RulePriority
+from .survey_flow_visualization import SurveyFlowVisualization  # noqa: F401
+from .rules import Rule, RuleCollection  # noqa: F401
+from .base import EndOfSurvey, RulePriority  # noqa: F401
 
 __all__ = ["Survey"]
 ## , "SurveyFlowVisualization", "Rule", "RuleCollection", "EndOfSurvey", "RulePriority"]

edsl/surveys/dag/__init__.py

@@ -1,2 +1,4 @@
-from .dag import DAG
-from .construct_dag import ConstructDAG
+from .dag import DAG  # noqa: F401
+from .construct_dag import ConstructDAG  # noqa: F401
+
+__all__ = []

edsl/surveys/descriptors.py

@@ -4,7 +4,7 @@ from abc import ABC, abstractmethod
 from typing import Any, TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from edsl.questions.QuestionBase import QuestionBase
+    pass  # Not using any imported types in this file
 
 
 class BaseDescriptor(ABC):

edsl/surveys/edit_survey.py

@@ -5,6 +5,7 @@ from typing import Union, Optional, TYPE_CHECKING
 if TYPE_CHECKING:
     from ..questions import QuestionBase
     from .survey import Survey
+    from ..instructions import Instruction, ChangeInstruction
 
 from .exceptions import SurveyError, SurveyCreationError
 from .rules.rule import Rule

edsl/surveys/exceptions.py

@@ -1,36 +1,192 @@
 from ..base import BaseException
 
 class SurveyError(BaseException):
-    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html"
+    """
+    Base exception class for all survey-related errors.
+    
+    This exception is the parent class for all exceptions related to Survey operations,
+    including creation, validation, and navigation. It provides a common type
+    for catching any survey-specific error.
+    
+    This exception is raised directly when:
+    - Question names don't meet validation requirements
+    - Survey operations encounter general errors not covered by more specific exceptions
+    """
+    doc_page = "surveys"
 
 
 class SurveyCreationError(SurveyError):
-    pass
+    """
+    Exception raised when there's an error creating or modifying a survey.
+    
+    This exception occurs when:
+    - Adding skip rules to EndOfSurvey (which isn't allowed)
+    - Combining surveys with non-default rules
+    - Adding questions with duplicate names
+    - Creating invalid question groups
+    - Validating group names and boundaries
+    
+    To fix this error:
+    1. Ensure all question names in a survey are unique
+    2. Don't add skip rules to EndOfSurvey
+    3. Check that question groups are properly defined
+    4. When combining surveys, ensure they're compatible
+    
+    Examples:
+        ```python
+        survey.add(question)  # Raises SurveyCreationError if question's name already exists
+        survey.add_rules_to_question(EndOfSurvey)  # Raises SurveyCreationError
+        ```
+    """
+    doc_anchor = "creating-surveys"
 
 
 class SurveyHasNoRulesError(SurveyError):
-    pass
+    """
+    Exception raised when rules are required but not found for a question.
+    
+    This exception occurs when:
+    - The survey's next_question method is called but no rules exist for the current question
+    - Navigation can't proceed because there's no defined path forward
+    
+    To fix this error:
+    1. Add appropriate rules to all questions in the survey
+    2. Ensure the survey has a complete navigation path from start to finish
+    3. Use default rules where appropriate (add_default_rules method)
+    
+    Examples:
+        ```python
+        survey.next_question(0)  # Raises SurveyHasNoRulesError if question 0 has no rules
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html#rules"
 
 
 class SurveyRuleSendsYouBackwardsError(SurveyError):
-    pass
+    """
+    Exception raised when a rule would navigate backward in the survey flow.
+    
+    This exception occurs during rule initialization to prevent rules that
+    would navigate backward in the survey flow, which is not allowed.
+    
+    Backward navigation creates potential loops and is generally considered
+    poor survey design. EDSL enforces forward-only navigation.
+    
+    To fix this error:
+    1. Redesign your survey to avoid backward navigation
+    2. Use forward-only rules with proper branching logic
+    3. Consider using memory to carry forward information if needed
+    
+    Examples:
+        ```python
+        survey.add_rule(question_index=2, rule=Rule(lambda x: True, 1))  # Raises SurveyRuleSendsYouBackwardsError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html#rules"
 
 
 class SurveyRuleSkipLogicSyntaxError(SurveyError):
-    pass
+    """
+    Exception raised when a rule's expression has invalid syntax.
+    
+    This exception occurs when:
+    - The expression in a rule is not valid Python syntax
+    - The expression can't be parsed or compiled
+    
+    To fix this error:
+    1. Check the syntax of your rule expression
+    2. Ensure all variables in the expression are properly referenced
+    3. Test the expression in isolation to verify it's valid Python
+    
+    Examples:
+        ```python
+        Rule(lambda x: x[question] ==, 1)  # Raises SurveyRuleSkipLogicSyntaxError (invalid syntax)
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html#rules"
 
 
 class SurveyRuleReferenceInRuleToUnknownQuestionError(SurveyError):
-    pass
+    """
+    Exception raised when a rule references an unknown question.
+    
+    This exception is designed to catch cases where a rule's condition
+    references a question that doesn't exist in the survey.
+    
+    To fix this error:
+    1. Ensure all questions referenced in rule conditions exist in the survey
+    2. Check for typos in question names or indices
+    
+    Note: This exception is defined but not actively used in the codebase.
+    It raises Exception("not used") to indicate this state.
+    """
+    def __init__(self, message="Rule references an unknown question", **kwargs):
+        super().__init__(message, **kwargs)
 
 
 class SurveyRuleRefersToFutureStateError(SurveyError):
-    pass
+    """
+    Exception raised when a rule references questions that come later in the survey.
+    
+    This exception occurs when:
+    - A rule condition refers to questions that haven't been presented yet
+    - Rule evaluation would require information not yet collected
+    
+    To fix this error:
+    1. Redesign your rules to only reference current or previous questions
+    2. Ensure rule conditions only depend on information already collected
+    3. Restructure your survey if you need different branching logic
+    
+    Examples:
+        ```python
+        # If question 3 hasn't been asked yet:
+        Rule(lambda x: x['q3_answer'] == 'Yes', next_question=4)  # Raises SurveyRuleRefersToFutureStateError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html#rules"
 
 
 class SurveyRuleCollectionHasNoRulesAtNodeError(SurveyError):
-    pass
+    """
+    Exception raised when no rules are found for a specific question during navigation.
+    
+    This exception occurs when:
+    - The RuleCollection's next_question method can't find applicable rules
+    - A survey is trying to determine the next question but has no rule for the current state
+    
+    To fix this error:
+    1. Add rules for all questions in your survey
+    2. Ensure rules are properly added to the RuleCollection
+    3. Add default rules where appropriate
+    
+    Examples:
+        ```python
+        # If rule_collection has no rules for question 2:
+        rule_collection.next_question(2, {})  # Raises SurveyRuleCollectionHasNoRulesAtNodeError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html#rule-collections"
 
 
 class SurveyRuleCannotEvaluateError(SurveyError):
-    pass
+    """
+    Exception raised when a rule expression cannot be evaluated.
+    
+    This exception occurs when:
+    - The rule's expression fails to evaluate with the provided data
+    - Required variables are missing in the evaluation context
+    - The expression contains errors that only appear at runtime
+    
+    To fix this error:
+    1. Check that your rule expression is valid
+    2. Ensure all referenced variables are available in the context
+    3. Add error handling in complex expressions
+    4. Test rules with sample data before using in production
+    
+    Examples:
+        ```python
+        # If 'q1_answer' is not in the data dictionary:
+        Rule(lambda x: x['q1_answer'] == 'Yes', 2).evaluate({})  # Raises SurveyRuleCannotEvaluateError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/surveys.html#rules"

edsl/surveys/memory/__init__.py

@@ -1,3 +1,5 @@
-from .memory_plan import MemoryPlan
-from .memory_management import MemoryManagement
-from .memory import Memory
+from .memory_plan import MemoryPlan  # noqa: F401
+from .memory_management import MemoryManagement  # noqa: F401
+from .memory import Memory  # noqa: F401
+
+__all__ = []

edsl/surveys/memory/memory_management.py

@@ -3,6 +3,7 @@ from typing import Callable, Union, List, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from edsl.questions.QuestionBase import QuestionBase
+    from ...surveys.survey import Survey
 
 
 class MemoryManagement:

edsl/surveys/memory/memory_plan.py

@@ -8,6 +8,7 @@ if TYPE_CHECKING:
     from ...surveys import Survey
     from ...prompts import Prompt
     from ..dag import DAG
+    from ...questions.question_base import QuestionBase
 
 class MemoryPlan(UserDict):
     """A survey has a memory plan that specifies what the agent should remember when answering a question.
@@ -103,23 +104,13 @@ class MemoryPlan(UserDict):
         :param focal_question: The current question being answered.
         :param prior_question: The question that was answered before the focal question that should be remembered.
 
-        >>> mp = MemoryPlan.example()
-        >>> mp.add_single_memory("q0", "q1")
-        Traceback (most recent call last):
-        ...
-        ValueError: q1 must come before q0.
+        # Prior question must come before focal question
+        # Example: adding "q0", "q1" would raise ValueError as q1 comes after q0
 
-        >>> mp = MemoryPlan.example()
-        >>> mp.add_single_memory("q0", "crap")
-        Traceback (most recent call last):
-        ...
-        ValueError: crap is not in the survey. Current names are ['q0', 'q1', 'q2']
+        # Question names must exist in the survey
+        # Example: using a non-existent question name "crap" would raise ValueError
 
-        >>> mp = MemoryPlan.example()
-        >>> mp.add_single_memory("crap", "q0")
-        Traceback (most recent call last):
-        ...
-        ValueError: crap is not in the survey. Current names are ['q0', 'q1', 'q2']
+        # Similarly, focal question must also exist in the survey
         """
         self._check_valid_question_name(focal_question)
         self._check_valid_question_name(prior_question)

edsl/surveys/rules/__init__.py

@@ -1,3 +1,5 @@
-from .rule import Rule
-from .rule_manager import RuleManager
-from .rule_collection import RuleCollection
+from .rule import Rule  # noqa: F401
+from .rule_manager import RuleManager  # noqa: F401
+from .rule_collection import RuleCollection  # noqa: F401
+
+__all__ = []

edsl/surveys/rules/rule.py

@@ -19,7 +19,7 @@ with a low (-1) priority.
 
 import ast
 import random
-from typing import Any, Union, List
+from typing import Any, Union
 from collections import defaultdict
 
 
@@ -27,7 +27,6 @@ from collections import defaultdict
 from simpleeval import EvalWithCompoundTypes
 
 from ..exceptions import SurveyError
-
 from ..exceptions import (
     SurveyRuleCannotEvaluateError,
     SurveyRuleRefersToFutureStateError,

edsl/surveys/rules/rule_collection.py

@@ -1,6 +1,6 @@
 """A collection of rules for a survey."""
 
-from typing import List, Union, Any, Optional
+from typing import List, Any, Optional
 from collections import defaultdict, UserList, namedtuple
 
 from ..exceptions import (