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

edsl/scenarios/{FileStore.py → file_store.py}

@@ -2,21 +2,61 @@ import base64
 import io
 import tempfile
 import mimetypes
+import asyncio
 import os
 from typing import Dict, Any, IO, Optional
-
-from edsl.scenarios.Scenario import Scenario
-from edsl.utilities.remove_edsl_version import remove_edsl_version
-
-from edsl.scenarios.file_methods import FileMethods
 from typing import Union
 from uuid import UUID
 import time
 from typing import Dict, Any, IO, Optional, List, Union, Literal
 
-
+from .scenario import Scenario
+from ..utilities import remove_edsl_version
+from .file_methods import FileMethods
 
 class FileStore(Scenario):
+    """
+    A specialized Scenario subclass for managing file content and metadata.
+    
+    FileStore provides functionality for working with files in EDSL, handling various
+    file formats with appropriate encoding, storage, and access methods. It extends
+    Scenario to allow files to be included in surveys, questions, and other EDSL components.
+    
+    FileStore supports multiple file formats including text, PDF, Word documents, images,
+    and more. It can load files from local paths or URLs, and provides methods for
+    accessing file content, extracting text, and managing file operations.
+    
+    Key features:
+    - Base64 encoding for portability and serialization
+    - Lazy loading through temporary files when needed
+    - Automatic MIME type detection
+    - Text extraction from various file formats
+    - Format-specific operations through specialized handlers
+    
+    Attributes:
+        _path (str): The original file path.
+        _temp_path (str): Path to any generated temporary file.
+        suffix (str): File extension.
+        binary (bool): Whether the file is binary.
+        mime_type (str): The file's MIME type.
+        base64_string (str): Base64-encoded file content.
+        external_locations (dict): Dictionary of external locations.
+        extracted_text (str): Text extracted from the file.
+    
+    Examples:
+        >>> import tempfile
+        >>> # Create a text file
+        >>> with tempfile.NamedTemporaryFile(suffix=".txt", mode="w") as f:
+        ...     _ = f.write("Hello World")
+        ...     _ = f.flush()
+        ...     fs = FileStore(f.name)
+        
+        # The following example works locally but is commented out for CI environments
+        # where dependencies like pandoc may not be available:
+        # >>> # FileStore supports various formats
+        # >>> formats = ["txt", "pdf", "docx", "pptx", "md", "py", "json", "csv", "html", "png", "db"]
+        # >>> _ = [FileStore.example(format) for format in formats]
+    """
     __documentation__ = "https://docs.expectedparrot.com/en/latest/filestore.html"
 
     def __init__(
@@ -30,6 +70,31 @@ class FileStore(Scenario):
         extracted_text: Optional[str] = None,
         **kwargs,
     ):
+        """
+        Initialize a new FileStore object.
+        
+        This constructor creates a FileStore object from either a file path or a base64-encoded
+        string representation of file content. It handles automatic detection of file properties
+        like MIME type, extracts text content when possible, and manages file encoding.
+        
+        Args:
+            path: Path to the file to load. Can be a local file path or URL.
+            mime_type: MIME type of the file. If not provided, will be auto-detected.
+            binary: Whether the file is binary. Defaults to False.
+            suffix: File extension. If not provided, will be extracted from the path.
+            base64_string: Base64-encoded file content. If provided, the file content
+                          will be loaded from this string instead of the path.
+            external_locations: Dictionary mapping location names to URLs or paths where
+                              the file can also be accessed.
+            extracted_text: Pre-extracted text content from the file. If not provided,
+                          text will be extracted automatically if possible.
+            **kwargs: Additional keyword arguments. 'filename' can be used as an
+                     alternative to 'path'.
+                     
+        Note:
+            If path is a URL (starts with http:// or https://), the file will be
+            downloaded automatically.
+        """
         if path is None and "filename" in kwargs:
             path = kwargs["filename"]
 
@@ -69,8 +134,32 @@ class FileStore(Scenario):
     @property
     def path(self) -> str:
         """
-        Property that returns a valid path to the file content.
-        If the original path doesn't exist, generates a temporary file from the base64 content.
+        Returns a valid path to the file content, creating a temporary file if needed.
+        
+        This property ensures that a valid file path is always available for the file
+        content, even if the original file is no longer accessible or if the FileStore
+        was created from a base64 string without a path. If the original path doesn't
+        exist, it automatically generates a temporary file from the base64 content.
+        
+        Returns:
+            A string containing a valid file path to access the file content.
+            
+        Examples:
+            >>> import tempfile, os
+            >>> with tempfile.NamedTemporaryFile(suffix=".txt", mode="w") as f:
+            ...     _ = f.write("Hello World")
+            ...     _ = f.flush()
+            ...     fs = FileStore(f.name)
+            ...     os.path.isfile(fs.path)
+            True
+            
+            
+        Notes:
+            - The path may point to a temporary file that will be cleaned up when the
+              Python process exits
+            - Accessing this property may create a new temporary file if needed
+            - This property provides a consistent interface regardless of how the
+              FileStore was created (from file or from base64 string)
         """
         # Check if original path exists and is accessible
         if self._path and os.path.isfile(self._path):
@@ -157,7 +246,7 @@ class FileStore(Scenario):
         Returns:
             ScenarioList containing FileStore objects with their corresponding URLs
         """
-        from edsl import ScenarioList
+        from .scenario_list import ScenarioList
 
         try:
             # Try using get_event_loop first (works in regular Python)
@@ -222,10 +311,14 @@ class FileStore(Scenario):
 
     def _repr_html_(self):
         parent_html = super()._repr_html_()
-        from edsl.scenarios.ConstructDownloadLink import ConstructDownloadLink
+        from .construct_download_link import ConstructDownloadLink
 
         link = ConstructDownloadLink(self).html_create_link(self.path, style=None)
         return f"{parent_html}<br>{link}"
+    
+    def download_link(self):
+        from .construct_download_link import ConstructDownloadLink
+        return ConstructDownloadLink(self).html_create_link(self.path, style=None)
 
     def encode_file_to_base64_string(self, file_path: str):
         try:
@@ -340,10 +433,15 @@ class FileStore(Scenario):
             file_like_object = self.base64_to_text_file(self.base64_string)
 
         # Create a named temporary file
-        mode = "wb" if self.binary else "w"
-        temp_file = tempfile.NamedTemporaryFile(
-            delete=False, suffix="." + suffix, mode=mode
-        )
+        # We need different parameters for binary vs text mode
+        if self.binary:
+            temp_file = tempfile.NamedTemporaryFile(
+                delete=False, suffix="." + suffix, mode="wb"
+            )
+        else:
+            temp_file = tempfile.NamedTemporaryFile(
+                delete=False, suffix="." + suffix, encoding="utf-8", mode="w"
+            )
 
         if self.binary:
             temp_file.write(file_like_object.read())
@@ -449,7 +547,7 @@ class FileStore(Scenario):
         return cls(download_path, mime_type=mime_type)
 
     def create_link(self, custom_filename=None, style=None):
-        from edsl.scenarios.ConstructDownloadLink import ConstructDownloadLink
+        from .construct_download_link import ConstructDownloadLink
 
         return ConstructDownloadLink(self).create_link(custom_filename, style)
 
@@ -486,184 +584,172 @@ class FileStore(Scenario):
         )
 
 
-class CSVFileStore(FileStore):
-    @classmethod
-    def example(cls):
-        from edsl.results.Results import Results
-
-        r = Results.example()
-        import tempfile
-
-        with tempfile.NamedTemporaryFile(suffix=".csv", delete=False) as f:
-            r.to_csv(filename=f.name)
-
-        return cls(f.name)
-
-    def view(self):
-        import pandas as pd
-
-        return pd.read_csv(self.to_tempfile())
-
-
-class PDFFileStore(FileStore):
-    def view(self):
-        pdf_path = self.to_tempfile()
-        print(f"PDF path: {pdf_path}")  # Print the path to ensure it exists
-        import os
-        import subprocess
-
-        if os.path.exists(pdf_path):
-            try:
-                if os.name == "posix":
-                    # for cool kids
-                    subprocess.run(["open", pdf_path], check=True)  # macOS
-                elif os.name == "nt":
-                    os.startfile(pdf_path)  # Windows
-                else:
-                    subprocess.run(["xdg-open", pdf_path], check=True)  # Linux
-            except Exception as e:
-                print(f"Error opening PDF: {e}")
-        else:
-            print("PDF file was not created successfully.")
-
-    @classmethod
-    def example(cls):
-        import textwrap
-
-        pdf_string = textwrap.dedent(
-            """\
-        %PDF-1.4
-        1 0 obj
-        << /Type /Catalog /Pages 2 0 R >>
-        endobj
-        2 0 obj
-        << /Type /Pages /Kids [3 0 R] /Count 1 >>
-        endobj
-        3 0 obj
-        << /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R >>
-        endobj
-        4 0 obj
-        << /Length 44 >>
-        stream
-        BT
-        /F1 24 Tf
-        100 700 Td
-        (Hello, World!) Tj
-        ET
-        endstream
-        endobj
-        5 0 obj
-        << /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
-        endobj
-        6 0 obj
-        << /ProcSet [/PDF /Text] /Font << /F1 5 0 R >> >>
-        endobj
-        xref
-        0 7
-        0000000000 65535 f 
-        0000000010 00000 n 
-        0000000053 00000 n 
-        0000000100 00000 n 
-        0000000173 00000 n 
-        0000000232 00000 n 
-        0000000272 00000 n 
-        trailer
-        << /Size 7 /Root 1 0 R >>
-        startxref
-        318
-        %%EOF"""
-        )
-        import tempfile
-
-        with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as f:
-            f.write(pdf_string.encode())
-
-        return cls(f.name)
-
-
-class PNGFileStore(FileStore):
-    @classmethod
-    def example(cls):
-        import textwrap
-
-        png_string = textwrap.dedent(
-            """\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x01\x00\x00\x00\x01\x00\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\x0cIDAT\x08\xd7c\x00\x01"""
-        )
-        import tempfile
-
-        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
-            f.write(png_string.encode())
-
-        return cls(f.name)
-
-    def view(self):
-        import matplotlib.pyplot as plt
-        import matplotlib.image as mpimg
-
-        img = mpimg.imread(self.to_tempfile())
-        plt.imshow(img)
-        plt.show()
-
-
-class SQLiteFileStore(FileStore):
-    @classmethod
-    def example(cls):
-        import sqlite3
-        import tempfile
-
-        with tempfile.NamedTemporaryFile(suffix=".sqlite", delete=False) as f:
-            conn = sqlite3.connect(f.name)
-            c = conn.cursor()
-            c.execute("""CREATE TABLE stocks (date text)""")
-            conn.commit()
-
-            return cls(f.name)
-
-    def view(self):
-        import subprocess
-        import os
-
-        sqlite_path = self.to_tempfile()
-        os.system(f"sqlite3 {sqlite_path}")
-
-
-class HTMLFileStore(FileStore):
-    @classmethod
-    def example(cls):
-        import tempfile
-
-        with tempfile.NamedTemporaryFile(suffix=".html", delete=False) as f:
-            f.write("<html><body><h1>Test</h1></body></html>".encode())
-
-        return cls(f.name)
-
-    def view(self):
-        import webbrowser
-
-        html_path = self.to_tempfile()
-        webbrowser.open("file://" + html_path)
+# class CSVFileStore(FileStore):
+#     @classmethod
+#     def example(cls):
+#         from ..results import Results
+
+#         r = Results.example()
+#         import tempfile
+
+#         with tempfile.NamedTemporaryFile(suffix=".csv", delete=False) as f:
+#             r.to_csv(filename=f.name)
+
+#         return cls(f.name)
+
+#     def view(self):
+#         import pandas as pd
+
+#         return pd.read_csv(self.to_tempfile())
+
+
+# class PDFFileStore(FileStore):
+#     def view(self):
+#         pdf_path = self.to_tempfile()
+#         print(f"PDF path: {pdf_path}")  # Print the path to ensure it exists
+#         import os
+#         import subprocess
+
+#         if os.path.exists(pdf_path):
+#             try:
+#                 if os.name == "posix":
+#                     # for cool kids
+#                     subprocess.run(["open", pdf_path], check=True)  # macOS
+#                 elif os.name == "nt":
+#                     os.startfile(pdf_path)  # Windows
+#                 else:
+#                     subprocess.run(["xdg-open", pdf_path], check=True)  # Linux
+#             except Exception as e:
+#                 print(f"Error opening PDF: {e}")
+#         else:
+#             print("PDF file was not created successfully.")
+
+#     @classmethod
+#     def example(cls):
+#         import textwrap
+
+#         pdf_string = textwrap.dedent(
+#             """\
+#         %PDF-1.4
+#         1 0 obj
+#         << /Type /Catalog /Pages 2 0 R >>
+#         endobj
+#         2 0 obj
+#         << /Type /Pages /Kids [3 0 R] /Count 1 >>
+#         endobj
+#         3 0 obj
+#         << /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R >>
+#         endobj
+#         4 0 obj
+#         << /Length 44 >>
+#         stream
+#         BT
+#         /F1 24 Tf
+#         100 700 Td
+#         (Hello, World!) Tj
+#         ET
+#         endstream
+#         endobj
+#         5 0 obj
+#         << /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+#         endobj
+#         6 0 obj
+#         << /ProcSet [/PDF /Text] /Font << /F1 5 0 R >> >>
+#         endobj
+#         xref
+#         0 7
+#         0000000000 65535 f 
+#         0000000010 00000 n 
+#         0000000053 00000 n 
+#         0000000100 00000 n 
+#         0000000173 00000 n 
+#         0000000232 00000 n 
+#         0000000272 00000 n 
+#         trailer
+#         << /Size 7 /Root 1 0 R >>
+#         startxref
+#         318
+#         %%EOF"""
+#         )
+#         import tempfile
+
+#         with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as f:
+#             f.write(pdf_string.encode())
+
+#         return cls(f.name)
+
+
+# class PNGFileStore(FileStore):
+#     @classmethod
+#     def example(cls):
+#         import textwrap
+
+#         png_string = textwrap.dedent(
+#             """\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x01\x00\x00\x00\x01\x00\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\x0cIDAT\x08\xd7c\x00\x01"""
+#         )
+#         import tempfile
+
+#         with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+#             f.write(png_string.encode())
+
+#         return cls(f.name)
+
+#     def view(self):
+#         import matplotlib.pyplot as plt
+#         import matplotlib.image as mpimg
+
+#         img = mpimg.imread(self.to_tempfile())
+#         plt.imshow(img)
+#         plt.show()
+
+
+# class SQLiteFileStore(FileStore):
+#     @classmethod
+#     def example(cls):
+#         import sqlite3
+#         import tempfile
+
+#         with tempfile.NamedTemporaryFile(suffix=".sqlite", delete=False) as f:
+#             conn = sqlite3.connect(f.name)
+#             c = conn.cursor()
+#             c.execute("""CREATE TABLE stocks (date text)""")
+#             conn.commit()
+
+#             return cls(f.name)
+
+#     def view(self):
+#         import subprocess
+#         import os
+
+#         sqlite_path = self.to_tempfile()
+#         os.system(f"sqlite3 {sqlite_path}")
+
+
+# class HTMLFileStore(FileStore):
+#     @classmethod
+#     def example(cls):
+#         import tempfile
+
+#         with tempfile.NamedTemporaryFile(suffix=".html", delete=False) as f:
+#             f.write("<html><body><h1>Test</h1></body></html>".encode())
+
+#         return cls(f.name)
+
+#     def view(self):
+#         import webbrowser
+
+#         html_path = self.to_tempfile()
+#         webbrowser.open("file://" + html_path)
 
 
 if __name__ == "__main__":
     import doctest
-
     doctest.testmod()
 
-    # fs = FileStore.example("pdf")
-    # fs.view()
-
-    formats = FileMethods.supported_file_types()
-    for file_type in formats:
-        print("Now testinging", file_type)
-        fs = FileStore.example(file_type)
-        fs.view()
-        input("Press Enter to continue...")
-
-    # pdf_example.view()
-    # FileStore(pdf_example).view()
-
-    # pdf_methods = methods.get("pdf")
-    # file = pdf_methods().example()
-    # pdf_methods(file).view()
+    # formats = FileMethods.supported_file_types()
+    # for file_type in formats:
+    #     print("Now testinging", file_type)
+    #     fs = FileStore.example(file_type)
+    #     fs.view()
+    #     input("Press Enter to continue...")
 
-    # print(FileMethods._handlers)

edsl/scenarios/handlers/__init__.py

@@ -1,14 +1,14 @@
-from .pdf import PdfMethods
-from .docx import DocxMethods
-from .png import PngMethods
-from .txt import TxtMethods
-from .html import HtmlMethods
-from .md import MarkdownMethods
-from .csv import CsvMethods
-from .json import JsonMethods
-from .sql import SqlMethods
-from .pptx import PptxMethods
-from .latex import LaTeXMethods
-from .py import PyMethods
-from .sqlite import SQLiteMethods
-from .jpeg import JpegMethods
+from .pdf_file_store import PdfMethods
+from .docx_file_store import DocxMethods
+from .png_file_store import PngMethods
+from .txt_file_store import TxtMethods
+from .html_file_store import HtmlMethods
+from .md_file_store import MarkdownMethods
+from .csv_file_store import CsvMethods
+from .json_file_store import JsonMethods
+from .sql_file_store import SqlMethods
+from .pptx_file_store import PptxMethods
+from .latex_file_store import LaTeXMethods
+from .py_file_store import PyMethods
+from .sqlite_file_store import SQLiteMethods
+from .jpeg_file_store import JpegMethods

edsl/scenarios/handlers/{csv.py → csv_file_store.py}

@@ -1,6 +1,5 @@
 import tempfile
-from edsl.scenarios.file_methods import FileMethods
-
+from ..file_methods import FileMethods
 
 class CsvMethods(FileMethods):
     suffix = "csv"

edsl/scenarios/handlers/{docx.py → docx_file_store.py}

@@ -1,7 +1,10 @@
-from edsl.scenarios.file_methods import FileMethods
 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"
@@ -56,8 +59,8 @@ class DocxMethods(FileMethods):
 
     def example(self):
         from docx import Document
-        from edsl.scenarios.Scenario import Scenario
-        from edsl.scenarios.ScenarioList import ScenarioList
+        from ..scenario import Scenario
+        from ..scenario_list import ScenarioList
 
         os.makedirs("test_dir", exist_ok=True)
         doc1 = Document()
@@ -74,7 +77,5 @@ class DocxMethods(FileMethods):
 
 
 if __name__ == "__main__":
-    docx_temp = DocxMethods.example()
-    from edsl.scenarios.FileStore import FileStore
-
-    fs = FileStore(docx_temp)
+    import doctest
+    doctest.testmod()

edsl/scenarios/handlers/{html.py → html_file_store.py}

@@ -1,6 +1,5 @@
-from edsl.scenarios.file_methods import FileMethods
 import tempfile
-
+from ..file_methods import FileMethods
 
 class HtmlMethods(FileMethods):
     suffix = "html"

edsl/scenarios/handlers/{jpeg.py → jpeg_file_store.py}

@@ -1,5 +1,5 @@
 import tempfile
-from edsl.scenarios.file_methods import FileMethods
+from ..file_methods import FileMethods
 
 
 class JpegMethods(FileMethods):

edsl/scenarios/handlers/{json.py → json_file_store.py}

@@ -1,8 +1,8 @@
-from edsl.scenarios.file_methods import FileMethods
 import tempfile
 import json
 from typing import Optional, Dict, Any
 
+from ..file_methods import FileMethods
 
 class JsonMethods(FileMethods):
     suffix = "json"

edsl/scenarios/handlers/latex_file_store.py

@@ -0,0 +1,5 @@
+from ..handlers.txt_file_store import TxtMethods
+
+
+class LaTeXMethods(TxtMethods):
+    pass

edsl/scenarios/handlers/{md.py → md_file_store.py}

@@ -1,5 +1,5 @@
-from edsl.scenarios.file_methods import FileMethods
 import tempfile
+from ..file_methods import FileMethods
 
 
 class MarkdownMethods(FileMethods):

edsl/scenarios/handlers/{pdf.py → pdf_file_store.py}

@@ -1,7 +1,7 @@
 import os
 import base64
 
-from edsl.scenarios.file_methods import FileMethods
+from ..file_methods import FileMethods
 
 
 class PdfMethods(FileMethods):
@@ -61,7 +61,7 @@ class PdfMethods(FileMethods):
         return
 
     def example(self):
-        from edsl.results.Results import Results
+        from ...results import Results
 
         return (
             Results.example().select("answer.how_feeling").first().pdf().to_tempfile()