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

edsl/plugins/plugins_registry.py

@@ -0,0 +1,168 @@
+"""
+Plugin registry module for accessing available plugins.
+
+This module provides functionality to discover and retrieve information about
+available plugins from the Expected Parrot cloud service. It defines data structures
+for plugin metadata and provides methods to access the plugin registry.
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional, Dict, Any
+import json
+import random
+from datetime import datetime
+
+from ..base.base_exception import BaseException
+from .exceptions import PluginException
+
+
+@dataclass
+class AvailablePlugin:
+    """
+    Data class representing an available plugin in the registry.
+    
+    Attributes:
+        name: The name of the plugin
+        description: A description of the plugin's functionality
+        github_url: URL to the plugin's GitHub repository
+        version: Version of the plugin
+        author: Author of the plugin
+        tags: List of tags associated with the plugin
+        created_at: Date when the plugin was created
+        is_installed: Whether the plugin is currently installed locally
+    """
+    name: str
+    description: str
+    github_url: str
+    version: str = "0.1.0"
+    author: str = "Expected Parrot"
+    tags: List[str] = None
+    created_at: str = None
+    is_installed: bool = False
+    
+    def __post_init__(self):
+        """Initialize default values for optional fields."""
+        if self.tags is None:
+            self.tags = []
+        if self.created_at is None:
+            self.created_at = datetime.now().strftime("%Y-%m-%d")
+
+
+class PluginRegistryError(PluginException):
+    """
+    Exception raised when there's an issue with the plugin registry.
+    
+    This exception is raised when the plugin registry cannot be accessed
+    or when there's an issue with the plugin data format.
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/plugins.html"
+
+
+def get_available_plugins(refresh: bool = False) -> List[AvailablePlugin]:
+    """
+    Get a list of available plugins from the Expected Parrot.
+    
+    This retrieves the official list of plugins available for EDSL.
+    
+    Args:
+        refresh: Whether to refresh the cache and fetch the latest data
+        
+    Returns:
+        List of AvailablePlugin objects representing available plugins
+        
+    Raises:
+        PluginRegistryError: If the registry cannot be accessed or data is invalid
+    """
+    # Official plugins list
+    plugins = [
+        AvailablePlugin(
+            name="conjure",
+            description="Create EDSL objects from Qualtrics, SPSS, Stata, and other survey/statistical files",
+            github_url="https://github.com/expectedparrot/edsl-conjure",
+            version="1.0.0",
+            author="Expected Parrot",
+            tags=["qualtrics", "stata", "spss", "survey", "web", "import", "convert"],
+        )
+    ]
+    
+    return plugins
+
+
+def search_plugins(query: str, tags: Optional[List[str]] = None) -> List[AvailablePlugin]:
+    """
+    Search for plugins matching a query string or tags.
+    
+    Args:
+        query: Search query string
+        tags: Optional list of tags to filter by
+        
+    Returns:
+        List of matching AvailablePlugin objects
+    """
+    all_plugins = get_available_plugins()
+    
+    # Filter by search query
+    if query:
+        query = query.lower()
+        filtered_plugins = [
+            plugin for plugin in all_plugins 
+            if query in plugin.name.lower() or query in plugin.description.lower()
+        ]
+    else:
+        filtered_plugins = all_plugins
+    
+    # Filter by tags if provided
+    if tags:
+        tags = [tag.lower() for tag in tags]
+        filtered_plugins = [
+            plugin for plugin in filtered_plugins
+            if any(tag in [t.lower() for t in plugin.tags] for tag in tags)
+        ]
+    
+    return filtered_plugins
+
+
+def get_plugin_details(plugin_name: str) -> Optional[Dict[str, Any]]:
+    """
+    Get detailed information about a specific plugin.
+    
+    Args:
+        plugin_name: Name of the plugin to get details for
+        
+    Returns:
+        Dictionary of detailed plugin information or None if not found
+    """
+    all_plugins = get_available_plugins()
+    
+    # Find the plugin by name
+    for plugin in all_plugins:
+        if plugin.name.lower() == plugin_name.lower():
+            # Convert dataclass to dict and add additional details
+            plugin_dict = {
+                "name": plugin.name,
+                "description": plugin.description,
+                "github_url": plugin.github_url,
+                "version": plugin.version,
+                "author": plugin.author,
+                "tags": plugin.tags,
+                "created_at": plugin.created_at,
+            }
+            return plugin_dict
+    
+    return None
+
+
+def get_github_url_by_name(plugin_name: str) -> Optional[str]:
+    """
+    Get a plugin's GitHub URL by its name.
+    
+    Args:
+        plugin_name: Name of the plugin
+        
+    Returns:
+        GitHub URL of the plugin or None if not found
+    """
+    plugin_details = get_plugin_details(plugin_name)
+    if plugin_details:
+        return plugin_details.get("github_url")
+    return None

edsl/prompts/__init__.py

@@ -1,2 +1,4 @@
 # from edsl.prompts.registry import get_classes
 from .prompt import Prompt
+
+__all__ = ["Prompt"]

edsl/prompts/exceptions.py

@@ -1,17 +1,119 @@
 from ..base import BaseException
 
 class PromptError(BaseException):
-    pass
+    """
+    Base exception class for all prompt-related errors.
+    
+    This is the parent class for all exceptions related to prompt processing,
+    rendering, and validation in the EDSL framework.
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/prompts.html"
 
 
 class TemplateRenderError(PromptError):
-    "TODO: Move to exceptions file"
-    pass
+    """
+    Exception raised when template rendering fails.
+    
+    This exception is raised when:
+    - Template rendering exceeds the maximum nesting level (potential infinite loop)
+    - Template variables cannot be correctly substituted
+    - The template contains syntax errors
+    
+    To fix this error:
+    1. Check for circular references in your template variables
+    2. Ensure all referenced variables are available in the template context
+    3. Verify template syntax follows the correct format
+    
+    Examples:
+        ```python
+        # Circular reference causing infinite loop
+        prompt.add_variable("var1", "{var2}")
+        prompt.add_variable("var2", "{var1}")
+        prompt.render()  # Raises TemplateRenderError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/prompts.html#template-variables"
 
 
 class PromptBadQuestionTypeError(PromptError):
-    pass
+    """
+    Exception raised when an invalid question type is used with a prompt.
+    
+    This exception is for cases where a prompt is configured for a specific
+    question type but is used with an incompatible question.
+    
+    To fix this error:
+    1. Ensure you're using the correct question type with the prompt
+    2. Check if the prompt needs to be updated to support the question type
+    
+    Note: This exception is defined but not currently used in the codebase.
+    It raises Exception("not used") to indicate this state.
+    """
+    def __init__(self, message="Invalid question type for this prompt", **kwargs):
+        super().__init__(message, **kwargs)
 
 
 class PromptBadLanguageModelTypeError(PromptError):
-    pass
+    """
+    Exception raised when an incompatible language model is used with a prompt.
+    
+    This exception is for cases where a prompt requires specific language model
+    capabilities that the provided model doesn't support.
+    
+    To fix this error:
+    1. Use a different language model that supports the required capabilities
+    2. Modify the prompt to work with the available language model
+    
+    Note: This exception is defined but not currently used in the codebase.
+    It raises Exception("not used") to indicate this state.
+    """
+    def __init__(self, message="Incompatible language model for this prompt", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class PromptValueError(PromptError):
+    """
+    Exception raised when there's an invalid value in prompt operations.
+    
+    This exception occurs when:
+    - A path to a template folder is invalid
+    - Invalid parameters are provided for prompt configuration
+    - Other validation errors during prompt operations
+    
+    To fix this error:
+    1. Check that file paths are valid and accessible
+    2. Verify that parameter values are within expected ranges or formats
+    3. Ensure that all required prompt attributes are properly set
+    
+    Examples:
+        ```python
+        # Invalid path for loading templates
+        prompt = Prompt.from_folder("/nonexistent/path")  # Raises PromptValueError
+        ```
+    """
+    def __init__(self, message="Invalid value in prompt operation", **kwargs):
+        super().__init__(message, **kwargs)
+
+
+class PromptImplementationError(PromptError):
+    """
+    Exception raised when a required method or feature is not implemented.
+    
+    This exception occurs when:
+    - An abstract method is not implemented by a prompt subclass
+    - A feature is requested that is not implemented for a specific prompt type
+    
+    To fix this error:
+    1. Implement the required method in your prompt subclass
+    2. Use a different prompt type that supports the requested feature
+    3. Check for updates that might add the missing functionality
+    
+    Examples:
+        ```python
+        # Calling an unimplemented method
+        custom_prompt = CustomPrompt()
+        custom_prompt.unimplemented_method()  # Raises PromptImplementationError
+        ```
+    """
+    def __init__(self, message="Required method or feature is not implemented", **kwargs):
+        super().__init__(message, **kwargs)

edsl/prompts/prompt.py

@@ -2,13 +2,16 @@ from __future__ import annotations
 from typing import Any, List, Union, Dict, Optional
 from pathlib import Path
 import time
+import logging
 from functools import lru_cache
 
 from jinja2 import Environment, meta, Undefined
 
-from .exceptions import TemplateRenderError
+from .exceptions import TemplateRenderError, PromptValueError, PromptImplementationError
 from ..base import PersistenceMixin, RepresentationMixin
 
+logger = logging.getLogger(__name__)
+
 MAX_NESTING = 100
 
 class PreserveUndefined(Undefined):
@@ -55,6 +58,12 @@ def _make_hashable(value):
         return frozenset((k, _make_hashable(v)) for k, v in value.items())
     return value
 
+@lru_cache(maxsize=1024)
+def _compile_template(text: str):
+    """Compile a Jinja template with caching."""
+    env = make_env()
+    return env.from_string(text)
+
 @lru_cache(maxsize=1024)
 def _cached_render(text: str, frozen_replacements: frozenset) -> str:
     """Cached version of template rendering with frozen replacements."""
@@ -135,14 +144,13 @@ class Prompt(PersistenceMixin, RepresentationMixin):
         # Convert path_to_folder to a Path object if it's a string
         if path_to_folder is None:
             from importlib import resources
-            import os
 
             path_to_folder = resources.path("edsl.questions", "prompt_templates")
 
         try:
             folder_path = Path(path_to_folder)
         except Exception as e:
-            raise ValueError(f"Invalid path: {path_to_folder}. Error: {e}")
+            raise PromptValueError(f"Invalid path: {path_to_folder}. Error: {e}")
 
         with open(folder_path.joinpath(file_name), "r") as f:
             text = f.read()
@@ -306,7 +314,7 @@ class Prompt(PersistenceMixin, RepresentationMixin):
         # Provide access to the 'vars' object inside the template.
         env.globals['vars'] = template_vars
 
-        previous_text = None
+        # Start with the original text
         current_text = text
 
         for _ in range(MAX_NESTING):
@@ -317,7 +325,7 @@ class Prompt(PersistenceMixin, RepresentationMixin):
                 # No more changes, return final text with captured variables.
                 return rendered_text, template_vars.get_all()
 
-            previous_text = current_text
+            # Update current_text for next iteration
             current_text = rendered_text
 
         raise TemplateRenderError(
@@ -363,7 +371,7 @@ class Prompt(PersistenceMixin, RepresentationMixin):
         >>> p = Prompt("Hello, {{person}}")
         """
 
-        raise NotImplementedError("This method should be implemented by the subclass.")
+        raise PromptImplementationError("This method should be implemented by the subclass.")
         start = time.time()
         
         # Build all the components

edsl/questions/HTMLQuestion.py

@@ -1,5 +1,4 @@
 from typing import Optional
-from ..prompts import Prompt
 
 
 class HTMLQuestion:
@@ -81,23 +80,18 @@ class HTMLQuestion:
                 "include_question_name": include_question_name,
             }
         except Exception as e:
-            raise ValueError(
+            from .exceptions import QuestionValueError
+            raise QuestionValueError(
                 f"Error rendering question: params = {params}, error = {e}"
             )
         rendered_html = base_template.render(**params)
 
         if iframe:
-            import html
-            from IPython.display import display, HTML
-
+            from ..display import display_html
+            
             height = height or 200
             width = width or 600
-            escaped_output = html.escape(rendered_html)
-            # escaped_output = rendered_html
-            iframe = f""""
-            <iframe srcdoc="{ escaped_output }" style="width: {width}px; height: {height}px;"></iframe>
-            """
-            display(HTML(iframe))
+            display_html(rendered_html, width=width, height=height, as_iframe=True)
             return None
 
         return rendered_html

edsl/questions/Quick.py

@@ -3,7 +3,6 @@ from edsl import (
     QuestionMultipleChoice,
     Survey,
     QuestionList,
-    Question,
 )
 
 

edsl/questions/__init__.py

@@ -128,6 +128,8 @@ from .derived.question_top_k import QuestionTopK
 from .exceptions import QuestionScenarioRenderError
 
 __all__ = [
+    # Exceptions
+    "QuestionScenarioRenderError",
     # Schema and metadata
     "Settings",
     "RegisterQuestionsMeta",