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

edsl/base/base_class.py

@@ -18,11 +18,12 @@ import json
 from typing import Any, Optional, Union
 from uuid import UUID
 import difflib
-import json
-from typing import Any, Dict, Tuple
+from typing import Dict, Tuple
 from collections import UserList
 import inspect
 
+from .. import logger
+
 class BaseException(Exception):
     """Base exception class for all EDSL exceptions.
     
@@ -35,12 +36,13 @@ class BaseException(Exception):
     """
     relevant_doc = "https://docs.expectedparrot.com/"
 
-    def __init__(self, message, *, show_docs=True):
+    def __init__(self, message, *, show_docs=True, log_level="error"):
         """Initialize a new BaseException with formatted error message.
         
         Args:
             message: The primary error message
             show_docs: If True, append documentation links to the error message
+            log_level: The logging level to use ("debug", "info", "warning", "error", "critical")
         """
         # Format main error message
         formatted_message = [message.strip()]
@@ -59,6 +61,19 @@ class BaseException(Exception):
         # Join with double newlines for clear separation
         final_message = "\n\n".join(formatted_message)
         super().__init__(final_message)
+        
+        # Log the exception
+        if log_level == "debug":
+            logger.debug(f"{self.__class__.__name__}: {message}")
+        elif log_level == "info":
+            logger.info(f"{self.__class__.__name__}: {message}")
+        elif log_level == "warning":
+            logger.warning(f"{self.__class__.__name__}: {message}")
+        elif log_level == "error":
+            logger.error(f"{self.__class__.__name__}: {message}")
+        elif log_level == "critical":
+            logger.critical(f"{self.__class__.__name__}: {message}")
+        # Default to error if an invalid log level is provided
 
 
 class DisplayJSON:
@@ -176,7 +191,7 @@ class PersistenceMixin:
             A new instance of the class populated with the deserialized data
             
         Raises:
-            ValueError: If neither yaml_str nor filename is provided
+            BaseValueError: If neither yaml_str nor filename is provided
         """
         if yaml_str is None and filename is not None:
             with open(filename, "r") as f:
@@ -188,7 +203,8 @@ class PersistenceMixin:
             d = yaml.load(yaml_str, Loader=yaml.FullLoader)
             return cls.from_dict(d)
         else:
-            raise ValueError("Either yaml_str or filename must be provided.")
+            from edsl.base.exceptions import BaseValueError
+            raise BaseValueError("Either yaml_str or filename must be provided.")
 
     def create_download_link(self):
         """Generate a downloadable link for this object.
@@ -365,23 +381,28 @@ class PersistenceMixin:
             >>> obj.save("my_object.json.gz")  # Compressed
             >>> obj.save("my_object.json", compress=False)  # Uncompressed
         """
+        logger.debug(f"Saving {self.__class__.__name__} to file: {filename}")
+        
         if filename.endswith("json.gz"):
-            import warnings
-
             filename = filename[:-8]
         if filename.endswith("json"):
             filename = filename[:-5]
 
-        if compress:
-            full_file_name = filename + ".json.gz"
-            with gzip.open(full_file_name, "wb") as f:
-                f.write(json.dumps(self.to_dict()).encode("utf-8"))
-        else:
-            full_file_name = filename + ".json"
-            with open(filename + ".json", "w") as f:
-                f.write(json.dumps(self.to_dict()))
-
-        print("Saved to", full_file_name)
+        try:
+            if compress:
+                full_file_name = filename + ".json.gz"
+                with gzip.open(full_file_name, "wb") as f:
+                    f.write(json.dumps(self.to_dict()).encode("utf-8"))
+            else:
+                full_file_name = filename + ".json"
+                with open(filename + ".json", "w") as f:
+                    f.write(json.dumps(self.to_dict()))
+                    
+            logger.info(f"Successfully saved {self.__class__.__name__} to {full_file_name}")
+            print("Saved to", full_file_name)
+        except Exception as e:
+            logger.error(f"Failed to save {self.__class__.__name__} to {filename}: {str(e)}")
+            raise
 
     @staticmethod
     def open_compressed_file(filename):
@@ -429,19 +450,30 @@ class PersistenceMixin:
         Raises:
             Various exceptions may be raised if the file doesn't exist or contains invalid data
         """
-        if filename.endswith("json.gz"):
-            d = cls.open_compressed_file(filename)
-        elif filename.endswith("json"):
-            d = cls.open_regular_file(filename)
-        else:
-            try:
-                d = cls.open_compressed_file(filename + ".json.gz")
-            except:
-                d = cls.open_regular_file(filename + ".json")
-            # finally:
-            #    raise ValueError("File must be a json or json.gz file")
-
-        return cls.from_dict(d)
+        logger.debug(f"Loading {cls.__name__} from file: {filename}")
+        
+        try:
+            if filename.endswith("json.gz"):
+                d = cls.open_compressed_file(filename)
+                logger.debug(f"Loaded compressed file {filename}")
+            elif filename.endswith("json"):
+                d = cls.open_regular_file(filename)
+                logger.debug(f"Loaded regular file {filename}")
+            else:
+                try:
+                    logger.debug(f"Attempting to load as compressed file: {filename}.json.gz")
+                    d = cls.open_compressed_file(filename + ".json.gz")
+                except Exception as e:
+                    logger.debug(f"Failed to load as compressed file, trying regular: {e}")
+                    d = cls.open_regular_file(filename + ".json")
+                # finally:
+                #    raise ValueError("File must be a json or json.gz file")
+
+            logger.info(f"Successfully loaded {cls.__name__} from {filename}")
+            return cls.from_dict(d)
+        except Exception as e:
+            logger.error(f"Failed to load {cls.__name__} from {filename}: {str(e)}")
+            raise
 
 
 class RegisterSubclassesMeta(ABCMeta):
@@ -739,7 +771,8 @@ class Base(
         Returns:
             An instance of the class with sample data
         """
-        raise NotImplementedError("This method is not implemented yet.")
+        from edsl.base.exceptions import BaseNotImplementedError
+        raise BaseNotImplementedError("This method is not implemented yet.")
     
     def json(self):
         """Get a formatted JSON representation of this object.
@@ -755,7 +788,6 @@ class Base(
         Returns:
             DisplayYAML: A displayable YAML representation
         """
-        import yaml
         return DisplayYAML(self.to_dict(add_edsl_version=False))
 
 
@@ -770,7 +802,8 @@ class Base(
         Returns:
             dict: A dictionary representation of the object
         """
-        raise NotImplementedError("This method is not implemented yet.")
+        from edsl.base.exceptions import BaseNotImplementedError
+        raise BaseNotImplementedError("This method is not implemented yet.")
 
     def to_json(self):
         """Serialize this object to a JSON string.
@@ -806,7 +839,8 @@ class Base(
         Returns:
             An instance of the class populated with data from the dictionary
         """
-        raise NotImplementedError("This method is not implemented yet.")
+        from edsl.base.exceptions import BaseNotImplementedError
+        raise BaseNotImplementedError("This method is not implemented yet.")
 
     @abstractmethod
     def code():
@@ -818,7 +852,8 @@ class Base(
         Returns:
             str: Python code that, when executed, creates an equivalent object
         """
-        raise NotImplementedError("This method is not implemented yet.")
+        from edsl.base.exceptions import BaseNotImplementedError
+        raise BaseNotImplementedError("This method is not implemented yet.")
 
     def show_methods(self, show_docstrings=True):
         """Display all public methods available on this object.
@@ -1240,7 +1275,7 @@ class BaseDiff:
                 result.append(f"    Old value: {v1}")
                 result.append(f"    New value: {v2}")
                 if diff:
-                    result.append(f"    Diff:")
+                    result.append("    Diff:")
                     try:
                         for line in diff:
                             result.append(f"      {line}")

edsl/base/base_exception.py

@@ -0,0 +1,204 @@
+import sys
+from IPython.core.interactiveshell import InteractiveShell
+from IPython.display import HTML, display
+from pathlib import Path
+import traceback
+
+# Example logger import
+from .. import logger
+
+
+class BaseException(Exception):
+    """Base exception class for all EDSL exceptions.
+
+    This class extends the standard Python Exception class to provide more helpful error messages
+    by including links to relevant documentation and example notebooks when available.
+
+    Attributes:
+        relevant_doc: URL to documentation explaining this type of exception
+        relevant_notebook: Optional URL to a notebook with usage examples
+        doc_page: Optional string with the document page name (without extension)
+        doc_anchor: Optional string with the anchor within the document page
+    """
+
+    relevant_doc = "https://docs.expectedparrot.com/"
+    relevant_notebook = None  # or set a default if you like
+    suppress_traceback = True
+    doc_page = None
+    doc_anchor = None
+
+    @classmethod
+    def get_doc_url(cls):
+        """Construct the documentation URL from the doc_page and doc_anchor attributes.
+
+        Returns:
+            str: The full documentation URL
+        """
+        base_url = "https://docs.expectedparrot.com/en/latest/"
+
+        if cls.doc_page:
+            url = f"{base_url}{cls.doc_page}.html"
+            if cls.doc_anchor:
+                url = f"{url}#{cls.doc_anchor}"
+            return url
+
+        return base_url
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        show_docs: bool = True,
+        log_level: str = "error",
+        silent: bool = False,
+    ):
+        """
+        Initialize a new BaseException with a formatted error message.
+
+        Args:
+            message (str): The primary error message.
+            show_docs (bool): If True, append documentation links to the error message.
+            log_level (str): The logging level to use
+                             ("debug", "info", "warning", "error", "critical").
+            silent (bool): If True, suppress all output when the exception is caught.
+        """
+        self.silent = silent
+
+        # Format main error message
+        formatted_message = [message.strip()]
+
+        # Add class docstring if available
+        if self.__class__.__doc__:
+            doc = self.__class__.__doc__.strip()
+            formatted_message.append(f"\n{doc}")
+
+        # Add documentation links if requested
+        if show_docs:
+            # Use the class method to get the documentation URL if doc_page is set
+            if hasattr(self.__class__, "doc_page") and self.__class__.doc_page:
+                formatted_message.append(
+                    f"\nFor more information, see: {self.__class__.get_doc_url()}"
+                )
+            # Fall back to relevant_doc if it's explicitly set
+            elif hasattr(self, "relevant_doc"):
+                formatted_message.append(
+                    f"\nFor more information, see: {self.relevant_doc}"
+                )
+            if self.relevant_notebook:
+                formatted_message.append(
+                    f"\nFor a usage example, see: {self.relevant_notebook}"
+                )
+
+        # Join with double newlines for clear separation
+        final_message = "\n\n".join(formatted_message)
+        super().__init__(final_message)
+
+        # Log the exception unless silent is True
+        if not self.silent:
+            self._log_message(log_level, message)
+
+    @staticmethod
+    def _log_message(log_level: str, message: str):
+        """Helper to log a message at the specified log level."""
+        # Adjust as needed for your logger setup
+        if log_level == "debug":
+            logger.debug(message)
+        elif log_level == "info":
+            logger.info(message)
+        elif log_level == "warning":
+            logger.warning(message)
+        elif log_level == "error":
+            logger.error(message)
+        elif log_level == "critical":
+            logger.critical(message)
+
+    @classmethod
+    def install_exception_hook(cls):
+        """
+        Install custom exception handling for EDSL exceptions.
+
+        In an IPython/Jupyter environment, this uses `set_custom_exc` to handle
+        BaseException (and its subclasses). In a standard Python environment,
+        it falls back to overriding `sys.excepthook`.
+        """
+        if cls._in_ipython():
+            cls._install_ipython_hook()
+        else:
+            cls._install_sys_excepthook()
+
+    @classmethod
+    def _install_ipython_hook(cls):
+        """Use IPython's recommended approach for a custom exception handler."""
+
+        shell = InteractiveShell.instance()
+
+        # Wrap in a function so we can pass it to set_custom_exc.
+        def _ipython_custom_exc(shell, etype, evalue, tb, tb_offset=None):
+            if issubclass(etype, BaseException) and cls.suppress_traceback:
+                # Show custom message only if not silent
+                if not getattr(evalue, "silent", False):
+                    # Try HTML display first; fall back to stderr
+                    # try:
+                    #     display(
+                    #         HTML(
+                    #             f"<div style='color: red'>❌ EDSL ERROR: "
+                    #             f"{etype.__name__}: {evalue}</div>"
+                    #         )
+                    #     )
+                    # except:
+                    print(f"❌ EDSL ERROR: {etype.__name__}: {evalue}", file=sys.stderr)
+                # Suppress IPython’s normal traceback
+                return
+            # Otherwise, fall back to the usual traceback
+            return shell.showtraceback((etype, evalue, tb), tb_offset=tb_offset)
+
+        shell.set_custom_exc((BaseException,), _ipython_custom_exc)
+
+    @classmethod
+    def _install_sys_excepthook(cls):
+        """
+        Override the default sys.excepthook in a standard Python environment.
+        This is typically NOT recommended for IPython/Jupyter.
+        """
+        if getattr(sys, "custom_excepthook_installed", False):
+            return  # Already installed
+
+        original_excepthook = sys.excepthook
+
+        def _custom_excepthook(exc_type, exc_value, exc_traceback):
+            if issubclass(exc_type, BaseException) and cls.suppress_traceback:
+                # Show custom message only if not silent
+                if not getattr(exc_value, "silent", False):
+                    # try:
+                    #     display(
+                    #         HTML(
+                    #             f"<div style='color: red'>❌ EDSL ERROR: "
+                    #             f"{exc_type.__name__}: {exc_value}</div>"
+                    #         )
+                    #     )
+                    # except:
+                    print(
+                        f"❌ EDSL ERROR: {exc_type.__name__}: {exc_value}",
+                        exc_traceback,
+                        file=sys.stderr,
+                    )
+                # Suppress traceback
+                traceback.print_exception(
+                    exc_type, exc_value, exc_traceback, file=sys.stderr
+                )
+
+                return
+            # Otherwise, use the default handler
+            return original_excepthook(exc_type, exc_value, exc_traceback)
+
+        sys.excepthook = _custom_excepthook
+        sys.custom_excepthook_installed = True
+
+    @staticmethod
+    def _in_ipython() -> bool:
+        """Return True if running inside IPython/Jupyter, False otherwise."""
+        try:
+            get_ipython()  # noqa
+            return True
+        except NameError:
+            return False

edsl/base/data_transfer_models.py

@@ -1,5 +1,5 @@
 from collections import UserDict
-from typing import NamedTuple, Dict, List, Optional, Any
+from typing import NamedTuple, Dict, Optional, Any
 from dataclasses import dataclass, fields
 
 

edsl/base/exceptions.py

@@ -0,0 +1,94 @@
+"""
+Base-specific exception classes.
+
+This module defines custom exceptions for the base module, extending the BaseException
+class to provide consistent error handling throughout the EDSL framework.
+"""
+
+from .base_exception import BaseException
+
+class BaseValueError(BaseException):
+    """
+    Exception raised for invalid values in base module operations.
+    
+    This exception is raised when an operation in the base module encounters an
+    inappropriate value that prevents it from being completed successfully. It 
+    replaces standard ValueError with domain-specific error handling.
+    
+    Examples:
+        - Missing required parameters
+        - Parameter values outside acceptable ranges
+        - Incompatible parameter combinations
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/base.html"
+    
+    def __init__(self, message="Invalid value provided", **kwargs):
+        super().__init__(message, **kwargs)
+
+class BaseNotImplementedError(BaseException):
+    """
+    Exception raised when a method that should be implemented is not.
+    
+    This exception is raised when calling an abstract or unimplemented method 
+    in the base module. It should be used for methods that are expected to be
+    overridden by subclasses but have not been implemented yet.
+    
+    Examples:
+        - Abstract methods called directly
+        - Interface methods not yet implemented
+        - Placeholder methods requiring implementation
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/base.html"
+    
+    def __init__(self, message="This method is not implemented yet", **kwargs):
+        super().__init__(message, **kwargs)
+
+class BaseKeyError(BaseException):
+    """
+    Exception raised for missing keys in base module operations.
+    
+    This exception is raised when a required key is missing from a dictionary
+    or similar data structure in the base module.
+    
+    Examples:
+        - Accessing a non-existent key in a configuration dictionary
+        - Missing required fields in serialized data
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/base.html"
+    
+    def __init__(self, message="Required key not found", **kwargs):
+        super().__init__(message, **kwargs)
+
+class BaseFileError(BaseException):
+    """
+    Exception raised for file-related errors in base module operations.
+    
+    This exception is raised when file operations in the base module encounter
+    issues such as missing files, permission problems, or format errors.
+    
+    Examples:
+        - File not found
+        - File format incompatible with the operation
+        - Permission denied when accessing a file
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/base.html"
+    
+    def __init__(self, message="Error in file operation", **kwargs):
+        super().__init__(message, **kwargs)
+
+class BaseTypeError(BaseException):
+    """
+    Exception raised for type-related errors in base module operations.
+    
+    This exception is raised when an operation in the base module encounters
+    an inappropriate type that prevents it from being completed successfully.
+    
+    Examples:
+        - Function arguments of incorrect type
+        - Type conversion failures
+        - Incompatible types in operations
+    """
+    relevant_doc = "https://docs.expectedparrot.com/en/latest/base.html"
+    
+    def __init__(self, message="Invalid type provided", **kwargs):
+        super().__init__(message, **kwargs)

edsl/buckets/__init__.py

@@ -21,5 +21,19 @@ multiple processes or machines need to share rate limits.
 from .bucket_collection import BucketCollection
 from .model_buckets import ModelBuckets
 from .token_bucket import TokenBucket
+from .exceptions import (
+    BucketError,
+    TokenLimitError,
+    TokenBucketClientError,
+    BucketConfigurationError,
+)
 
-__all__ = ["BucketCollection", "ModelBuckets", "TokenBucket"]
+__all__ = [
+    "BucketCollection", 
+    "ModelBuckets", 
+    "TokenBucket",
+    "BucketError",
+    "TokenLimitError",
+    "TokenBucketClientError",
+    "BucketConfigurationError",
+]

edsl/buckets/bucket_collection.py

@@ -7,10 +7,9 @@ API rate limits are respected while allowing models from the same service to
 share the same rate limit buckets.
 """
 
-from typing import Optional, TYPE_CHECKING, Dict, List, Any, Tuple
+from typing import TYPE_CHECKING, Dict, List, Tuple
 from collections import UserDict
 from threading import RLock
-import matplotlib.pyplot as plt
 from matplotlib.figure import Figure
 
 from .token_bucket import TokenBucket
@@ -74,7 +73,6 @@ class BucketCollection(UserDict):
         self._lock = RLock()
 
         # Check for remote token bucket server URL in environment
-        from edsl.config import CONFIG
         import os
 
         url = os.environ.get("EDSL_REMOTE_TOKEN_BUCKET_URL", None)
@@ -137,7 +135,8 @@ class BucketCollection(UserDict):
             >>> # The following would raise an exception:
             >>> # bucket_collection.get_tokens(m, 'tokens', 10)
         """
-        raise Exception("This method is deprecated and should not be used")
+        from edsl.buckets.exceptions import BucketError
+        raise BucketError("This method is deprecated and should not be used")
         # The following code is kept for reference only
         # relevant_bucket = getattr(self[model], bucket_type)
         # return relevant_bucket.get_tokens(num_tokens)

edsl/buckets/exceptions.py

@@ -0,0 +1,75 @@
+"""
+Exceptions module for bucket-related operations.
+
+This module defines custom exception classes for all bucket-related error conditions
+in the EDSL framework, ensuring consistent error handling for token bucket operations,
+rate limiting, and related functionality.
+"""
+
+from ..base import BaseException
+
+
+class BucketError(BaseException):
+    """
+    Base exception class for all bucket-related errors.
+    
+    This is the parent class for exceptions related to token bucket operations
+    in the EDSL framework, including token management, rate limiting, and related
+    functionality.
+    
+    Examples:
+        ```python
+        # Usually not raised directly, but through subclasses:
+        bucket = TokenBucket(name="test", capacity=100, refill_rate=10)
+        bucket.get_tokens(200)  # Would raise TokenLimitError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+
+
+class TokenLimitError(BucketError):
+    """
+    Exception raised when a token request exceeds available limits.
+    
+    This exception occurs when attempting to request more tokens than
+    are currently available in the bucket or when exceeding rate limits.
+    
+    Examples:
+        ```python
+        bucket = TokenBucket(name="test", capacity=100, refill_rate=10)
+        bucket.get_tokens(200)  # Raises TokenLimitError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+
+
+class TokenBucketClientError(BucketError):
+    """
+    Exception raised when there's an error communicating with a remote token bucket.
+    
+    This exception occurs when the client cannot connect to the token bucket service,
+    receives an unexpected response, or encounters other client-related issues.
+    
+    Examples:
+        ```python
+        client = TokenBucketClient(url="invalid_url")
+        client.get_tokens(10)  # May raise TokenBucketClientError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"
+
+
+class BucketConfigurationError(BucketError):
+    """
+    Exception raised when there's an issue with bucket configuration.
+    
+    This exception occurs when bucket parameters are invalid, such as
+    negative capacity, invalid refill rates, or other configuration problems.
+    
+    Examples:
+        ```python
+        # Attempting to create a bucket with invalid parameters:
+        TokenBucket(name="test", capacity=-100, refill_rate=10)  # Would raise BucketConfigurationError
+        ```
+    """
+    relevant_doc = "https://docs.expectedparrot.com/"

edsl/buckets/model_buckets.py

@@ -6,8 +6,7 @@ and tokens-per-minute rate limits for language model API services. Each ModelBuc
 instance contains two TokenBucket instances - one for requests and one for tokens.
 """
 
-from typing import TYPE_CHECKING, Tuple, Optional, Any
-import matplotlib.pyplot as plt
+from typing import TYPE_CHECKING, Tuple
 from matplotlib.figure import Figure
 
 if TYPE_CHECKING: