docassemble.AssemblyLine 3.5.1__tar.gz → 4.1.0__tar.gz

{docassemble_assemblyline-3.5.1/docassemble.AssemblyLine.egg-info → docassemble_assemblyline-4.1.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: docassemble.AssemblyLine
-Version: 3.5.1
+Version: 4.1.0
 Home-page: https://courtformsonline.org
 Author: Suffolk Legal Innovation and Technology Lab
 Author-email: qsteenhuis@suffolk.edu
 License: The MIT License (MIT)
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: docassemble.ALToolbox>=0.11.1
+Requires-Dist: docassemble.ALToolbox>=0.12.0
 Requires-Dist: docassemble.GithubFeedbackForm>=0.4.1.1
 Dynamic: author
 Dynamic: author-email

docassemble_assemblyline-4.1.0/docassemble/AssemblyLine/__init__.py

@@ -0,0 +1 @@
+__version__ = '4.1.0'

{docassemble_assemblyline-3.5.1 → docassemble_assemblyline-4.1.0}/docassemble/AssemblyLine/al_document.py

@@ -36,6 +36,9 @@ import subprocess
 from collections import ChainMap
 import pikepdf
 from typing import Tuple
+import secrets
+import string
+
 
 __all__ = [
     "ALAddendumField",
@@ -59,6 +62,22 @@ __all__ = [
 DEBUG_MODE = get_config("debug")
 
 
+def random_suffix(length: int = 8) -> str:
+    """Return a random string for use in unique IDs.
+
+    Note: this is powerful enough for the expected usecase of distinguishing a few
+    HTML elements from each other, but not cryptographically secure or as strong as
+    a true GUID.
+
+    Args:
+        length (int): The length of the random string to generate. Defaults to 8.
+    Returns:
+        str: A random string of lowercase letters and digits.
+    """
+    alphabet = string.ascii_lowercase + string.digits
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
 def base_name(filename: str) -> str:
     """
     Extracts the base name of a file without its extension.
@@ -1653,8 +1672,8 @@ class ALDocumentBundle(DAList):
         refresh: bool = True,
         pdfa: bool = False,
         title: str = "",
-        format="pdf",
-        include_pdf=True,
+        format: Optional[str] = "pdf",
+        include_pdf: Optional[bool] = True,
     ) -> DAFile:
         """
         Returns a zip file containing all enabled documents in the bundle in the specified format.
@@ -1670,6 +1689,11 @@ class ALDocumentBundle(DAList):
         Returns:
             DAFile: A zip file containing the enabled documents.
         """
+        if format is None:
+            format = "pdf"
+
+        if include_pdf is None:
+            include_pdf = True
 
         zip_key = f"{ space_to_underscore( key )}_zip"
 
@@ -1679,6 +1703,7 @@ class ALDocumentBundle(DAList):
 
         # strip out a possible '.pdf' ending then add '.zip'
         zipname = os.path.splitext(self.filename)[0]
+
         if format == "docx":
             docs = []
             for doc in self.enabled_documents(refresh=refresh):
@@ -1864,6 +1889,8 @@ class ALDocumentBundle(DAList):
         include_zip: bool = True,
         include_full_pdf: bool = False,
         append_matching_suffix: bool = True,
+        zip_include_pdf: Optional[bool] = None,
+        zip_format: Optional[str] = None,
     ) -> Tuple[List[Dict[str, DAFile]], Optional[DAFile], Optional[DAFile]]:
         """
         Generates a cache of all enabled documents in the bundle, and returns it in a structure that can be cached
@@ -1887,6 +1914,8 @@ class ALDocumentBundle(DAList):
             include_zip (bool): Flag to include a zip option, default is True.
             include_full_pdf (bool): Flag to include a PDF version of the whole bundle, default is False.
             append_matching_suffix (bool): Flag to determine if matching suffix should be appended to file name, default is True.
+            zip_include_pdf (Optional[bool]): If True, includes a PDF version in the zip file even if original is in DOCX format.
+            zip_format (Optional[str]): Format of the primary version of each document.
 
         Returns:
             Tuple[List[Dict[str, DAFile]], Optional[DAFile], Optional[DAFile]]: A list of dictionaries containing the enabled documents, a zip file of the whole bundle, and a PDF of the whole
@@ -1940,9 +1969,14 @@ class ALDocumentBundle(DAList):
                 pass
             results.append(result)
 
+        if zip_format is None:
+            zip_format = "original" if original else "docx" if docx else "pdf"
+
         if len(enabled_docs) > 1 and include_zip:
             bundled_zip = self.as_zip(
-                key=key, format="original" if original else "docx" if docx else "pdf"
+                key=key,
+                format=zip_format,
+                include_pdf=zip_include_pdf,
             )
         else:
             bundled_zip = None
@@ -1976,6 +2010,8 @@ class ALDocumentBundle(DAList):
         use_previously_cached_files: bool = False,
         include_full_pdf: bool = False,
         full_pdf_label: Optional[str] = None,
+        zip_include_pdf: Optional[bool] = True,
+        zip_format: Optional[str] = None,
     ) -> str:
         """
         Constructs an HTML table displaying a list of documents with 'view' and 'download' buttons.
@@ -2002,6 +2038,8 @@ class ALDocumentBundle(DAList):
             use_previously_cached_files (bool): Flag to use previously cached files (e.g., made in background) if defined. default is False.
             include_full_pdf (bool): Flag to include a full PDF option, default is False.
             full_pdf_label (Optional[str]): Label for the full PDF option. If not provided, uses the generic template for `self.full_pdf_label` ("Download all").
+            zip_include_pdf (Optional[bool]): Flag to include PDF files in the zip archive, default is True. If `None` value of `view` will be used.
+            zip_format (Optional[str]): Format of the files in the zip archive. If None, defaults to value of "format" parameter.
 
         Returns:
             str: HTML representation of a table with documents and their associated actions.
@@ -2012,6 +2050,12 @@ class ALDocumentBundle(DAList):
         if not hasattr(self, "_cached_full_pdf_label"):
             self._cached_full_pdf_label = str(self.full_pdf_label)
 
+        if zip_format is None:
+            zip_format = format
+
+        if zip_include_pdf is None:
+            zip_include_pdf = view
+
         if use_previously_cached_files and hasattr(self, "_downloadable_files"):
             downloadable_files, bundled_zip, bundled_pdf = self._downloadable_files
         else:
@@ -2025,6 +2069,8 @@ class ALDocumentBundle(DAList):
                 include_zip=include_zip,
                 include_full_pdf=include_full_pdf,
                 append_matching_suffix=append_matching_suffix,
+                zip_include_pdf=zip_include_pdf,
+                zip_format=zip_format,
             )
 
         html = f'<div class="container al_table al_doc_table" id="{ html_safe_str(self.instanceName) }">'
@@ -2215,7 +2261,7 @@ class ALDocumentBundle(DAList):
             self._cached_include_editable_documents = str(
                 self.include_editable_documents
             )
-        name = html_safe_str(self.instanceName)
+        name = html_safe_str(self.instanceName) + random_suffix()
         al_wants_editable_input_id = "_ignore_al_wants_editable_" + name
         al_email_input_id = "_ignore_al_doc_email_" + name
         al_send_button_id = "al_send_email_button_" + name
@@ -2250,12 +2296,13 @@ class ALDocumentBundle(DAList):
     def send_button_to_html(
         self,
         email: str,
-        editable: bool = False,
+        editable: Optional[bool] = None,
         template_name: str = "",
         label: str = "Send",
         icon: str = "envelope",
         color: str = "primary",
         key: str = "final",
+        preferred_formats: Optional[Union[str, List[str]]] = None,
     ) -> str:
         """
         Generate HTML for a button that allows someone to send the bundle to a
@@ -2264,12 +2311,13 @@ class ALDocumentBundle(DAList):
 
         Args:
             email (str): The recipient's email address.
-            editable (bool, optional): Flag indicating if the bundle is editable. Defaults to False.
+            editable (bool, optional): Flag indicating if the bundle is editable. Defaults to False. (deprecated; use preferred_formats instead)
             template_name (str, optional): The name of the template to be used. Defaults to an empty string.
             label (str, optional): The label for the button. Defaults to "Send".
             icon (str, optional): The Fontawesome icon for the button. Defaults to "envelope".
             color (str, optional): The Bootstrap color of the button. Defaults to "primary".
             key (str, optional): A key used to identify which version of the ALDocument to send. Defaults to "final".
+            preferred_formats (Optional[Union[str,List[str]]], optional): A list of allowed formats for the document. Defaults to "pdf" if not specified.
 
         Returns:
             str: The generated HTML string for the button.
@@ -2278,9 +2326,16 @@ class ALDocumentBundle(DAList):
             return ""  # Don't let people email an empty set of documents
         if not hasattr(self, "_cached_get_email_copy"):
             self._cached_get_email_copy = str(self.get_email_copy)
-        name = html_safe_str(self.instanceName)
+        name = html_safe_str(self.instanceName) + random_suffix()
         al_send_button_id = "al_send_email_to_button_" + name
 
+        if isinstance(preferred_formats, (list, tuple)):
+            formats_js = "[" + ",".join(f"'{fmt}'" for fmt in preferred_formats) + "]"
+        elif preferred_formats:
+            formats_js = f"'{preferred_formats}'"
+        else:
+            formats_js = "null"
+
         javascript_string = (
             f"javascript:aldocument_send_to_action("
             f"'{self.attr_name('send_email_to_action_event')}',"
@@ -2288,7 +2343,9 @@ class ALDocumentBundle(DAList):
             f"'{email}',"
             f"'{al_send_button_id}',"
             f"'{template_name}',"
-            f"'{key}')"
+            f"'{key}',"
+            f"{formats_js}"
+            f")"
         )
         send_button = action_button_html(
             javascript_string,
@@ -2309,6 +2366,7 @@ class ALDocumentBundle(DAList):
         template_name: str = "",
         label: str = "Send",
         icon: str = "envelope",
+        preferred_formats: Optional[Union[str, List[str]]] = None,
     ) -> str:
         """
         Generate HTML for an input box and button that allows someone to send the bundle
@@ -2321,12 +2379,13 @@ class ALDocumentBundle(DAList):
             key (str, optional): A key used to identify which version of the ALDocument to send. Defaults to "final".
             show_editable_checkbox (bool, optional): Flag indicating if the checkbox
                 for deciding the inclusion of an editable (Word) copy should be displayed.
-                Defaults to True.
+                Defaults to True. If preferred_formats = ["pdf"], this will be ignored and no checkbox will be shown.
             template_name (str, optional): Name of the template variable that is used to fill
                 the email contents. By default, the `x.send_email_template` template will be used.
             label (str, optional): The label for the button. Defaults to "Send".
             icon (str, optional): The Fontawesome icon for the button. Defaults
                 to "envelope".
+            preferred_formats (Optional[Union[str,List[str]]], optional): A list of allowed formats for the document. Defaults to "pdf" if not specified.
 
         Returns:
             str: The generated HTML string for the input box and button.
@@ -2339,31 +2398,52 @@ class ALDocumentBundle(DAList):
             self._cached_include_editable_documents = str(
                 self.include_editable_documents
             )
-        name = html_safe_str(self.instanceName)
+
+        if isinstance(preferred_formats, str):
+            preferred_formats = [preferred_formats]
+
+        if not preferred_formats:
+            preferred_formats = ["pdf", "docx"] if show_editable_checkbox else ["pdf"]
+
+        name = html_safe_str(self.instanceName) + random_suffix()
         al_wants_editable_input_id = "_ignore_al_wants_editable_" + name
         al_email_input_id = "_ignore_al_doc_email_" + name
         al_send_button_id = "al_send_email_button_" + name
 
+        if isinstance(preferred_formats, (list, tuple)):
+            formats_js = "[" + ",".join(f"'{fmt}'" for fmt in preferred_formats) + "]"
+        elif preferred_formats:
+            formats_js = f"'{preferred_formats}'"
+        else:
+            formats_js = "null"
+
         javascript_string = (
             f"javascript:aldocument_send_action("
             f"'{self.attr_name('send_email_action_event')}',"
             f"'{al_wants_editable_input_id}',"
             f"'{al_email_input_id}',"
             f"'{template_name}',"
-            f"'{key}')"
+            f"'{key}',"
+            f"{formats_js}"
+            ")"
         )
 
         # Container of whole email section with header
         return_str = f"""
-  <fieldset class="al_send_bundle al_send_section_alone {name}" id="al_send_bundle_{name}" name="al_send_bundle_{name}">
+  <fieldset class="al_send_bundle al_send_section_alone {html_safe_str(self.instanceName)}" id="al_send_bundle_{name}" name="al_send_bundle_{name}">
     <legend class="h4 al_doc_email_header">{self._cached_get_email_copy}</legend> 
     """
         # "Editable" checkbox
-        if show_editable_checkbox:
+        if (
+            show_editable_checkbox
+            and preferred_formats
+            and isinstance(preferred_formats, list)
+            and len(preferred_formats) > 1
+        ):  # Do not need to show if only one valid format allowed
             return_str += f"""
     <div class="form-check-container">
       <div class="form-check">
-        <input class="form-check-input" type="checkbox" class="al_wants_editable" id="{al_wants_editable_input_id}">
+        <input class="form-check-input al_wants_editable" type="checkbox" id="{al_wants_editable_input_id}">
         <label class="al_wants_editable form-check-label" for="{al_wants_editable_input_id}">{self._cached_include_editable_documents}
         </label>
       </div>
@@ -2373,7 +2453,7 @@ class ALDocumentBundle(DAList):
         return_str += f"""
   <div class="al_email_container">
   
-    <span class="al_email_address {name} container form-group row da-field-container da-field-container-datatype-email">
+    <span class="al_email_address {html_safe_str(self.instanceName)} container form-group row da-field-container da-field-container-datatype-email">
       <label for="{al_email_input_id}" class="col-form-label da-form-label datext-right">Email</label>
       <input value="{user_info().email if user_logged_in() else ''}" alt="Email address for document" class="form-control" type="email" size="35" name="{al_email_input_id}" id="{al_email_input_id}">
     </span>
@@ -2389,8 +2469,9 @@ class ALDocumentBundle(DAList):
         self,
         to: Any = None,
         key: str = "final",
-        editable: bool = False,
-        template: Any = None,
+        editable: Optional[bool] = None,
+        template: Optional[Any] = None,
+        preferred_formats: Optional[Union[str, List[str]]] = "pdf",
         **kwargs,
     ) -> bool:
         """
@@ -2399,39 +2480,54 @@ class ALDocumentBundle(DAList):
         https://docassemble.org/docs/functions.html#send_email with additional parameters.
 
         Args:
-            to (Any): The email address or list of addresses to send to. It can be a string
-                or objects with such. Similar to da send_email `to`.
+            to (Any): The email address, list of email addresses, or list of Individuals with a .email attribute to send to.
             key (str, optional): Specifies which version of the document to send. Defaults to "final".
-            editable (bool, optional): If True, sends the editable documents. Defaults to False.
-            template (Any): The template variable, similar to da `send_email` `template` variable.
+            editable (bool, optional): If True, sends the editable documents. Defaults to False. (Deprecated)
+            template (Any): The template variable for the subject and body of the email, similar to da `send_email` `template` variable.
+            preferred_formats (str): Specifies the format of the files to send. Can be "pdf" or "docx", or a list of these formats. Overrides deprecated `editable` keyword.
             **kwargs: Additional parameters to pass to the da `send_email` function.
 
         Returns:
             bool: Indicates if the email was sent successfully.
         """
-        if not template:
+        if editable is not None:
+            log(
+                "The 'editable' parameter is deprecated; use 'preferred_formats' instead."
+            )
+
+        if template is None:
             template = self.send_email_template
 
-        if editable:
-            return send_email(
-                to=to,
-                template=template,
-                # Add both DOCX and PDF versions, but if it's not possible to be a DOCX don't add the PDF
-                # twice
-                attachments=list(
-                    dict.fromkeys(
-                        self.as_editable_list(key=key) + self.as_pdf_list(key=key)
-                    )
-                ),
-                **kwargs,
-            )
-        else:
-            return send_email(
-                to=to,
-                template=template,
-                attachments=self.as_pdf_list(key=key),
-                **kwargs,
-            )
+        if preferred_formats is None:
+            preferred_formats = ["docx", "pdf"] if editable else ["pdf"]
+
+        if isinstance(preferred_formats, str):
+            preferred_formats = [preferred_formats]
+
+        allowed = {fmt.lower() for fmt in preferred_formats}
+        attachments = []
+
+        for item in self.enabled_documents():
+            primary = None
+
+            if "docx" in allowed:
+                primary = item.as_docx(key=key)
+                attachments.append(primary)
+
+            if "pdf" in allowed:
+                if not (
+                    primary
+                    and hasattr(primary, "extension")
+                    and primary.extension == "pdf"
+                ):
+                    attachments.append(item.as_pdf(key=key))
+
+        return send_email(
+            to=to,
+            template=template,
+            attachments=attachments,
+            **kwargs,
+        )
 
     def _is_self_enabled(self, refresh=True) -> bool:
         """