Skip to main content

AssemblyLine.al_document

random_suffix​

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.

Arguments​

  • length int - The length of the random string to generate. Defaults to 8.

Returns​

  • str - A random string of lowercase letters and digits.

base_name​

def base_name(filename: str) -> str

Extracts the base name of a file without its extension.

Arguments​

  • filename str - The full name of the file.

Returns​

  • str - The base name of the file without its extension.

label​

def label(dictionary: dict) -> str

Return the value of the first dictionary item.

Given a dictionary like: {"some_attribute":"Some label"}, this function returns the value of the first dictionary item. Useful for working with the columns method of an ALAddendumField.

Arguments​

  • dictionary dict - The dictionary to extract the value from.

Returns​

  • str - The value of the first dictionary item or an empty string if not found.

key​

def key(dictionary: dict) -> str

Return the key of the first dictionary item.

Given a dictionary like: {"some_attribute":"Some label"}, this function returns the key of the first dictionary item. Useful for working with the columns method of an ALAddendumField.

Arguments​

  • dictionary dict - The dictionary to extract the key from.

Returns​

  • str - The key of the first dictionary item or an empty string if not found.

safeattr​

def safeattr(object: Any, key: str) -> str

Safely retrieve an attribute or key value from an object.

Arguments​

  • object Any - The object (which could be a dict, DADict, or DAObject) from which to retrieve the value.
  • key str - The key or attribute name.

Returns​

  • str - The retrieved value or an empty string if not found or if an error occurred.

Notes​

The location attribute of an Address object or any LatitudeLongitude attribute of a DAObject is always skipped.

html_safe_str​

def html_safe_str(the_string: str) -> str

Convert a string into a format that's safe for use as an HTML class or ID.

Arguments​

  • the_string str - The string to be converted.

Returns​

  • str - A string that's safe for use as an HTML class or ID.

table_row​

def table_row(title: str, button_htmls: List[str] = []) -> str

Generate an HTML row string for an AL document-styled table.

Arguments​

  • title str - The title to display in the row.
  • button_htmls List[str], optional - A list of HTML strings representing buttons. Defaults to an empty list.

Returns​

  • str - An HTML string representing a row in an AL document-styled table.

pdf_page_parity​

def pdf_page_parity(pdf_path: str) -> Literal["even", "odd"]

Count the number of pages in the PDF and return "even" if it is divisible by 2 and "odd" if it is not divisible by 2.

Arguments​

  • pdf_path str - Path to the PDF in the filesystem

Returns​

Literal["even", "odd"]: The parity of the number of pages in the PDF

add_blank_page​

def add_blank_page(pdf_path: str) -> None

Add a blank page to the end of a PDF.

Arguments​

  • pdf_path str - Path to the PDF in the filesystem

ALAddendumField Objects​

class ALAddendumField(DAObject)

Represents a field with attributes determining its display in an addendum, typically for PDF templates.

The field can manage items that are either strings or list-like structures. Handling of dictionary overflow is not currently supported.

Attributes​

  • field_name str - The name of a docassemble variable that this object represents.

  • overflow_trigger Union[int, bool] - Specifies the limit after which the text is truncated and moved to an addendum. If set to True, it will always overflow. If set to False, it will never overflow. An integer value represents the maximum character count before overflow.

  • headers Optional[Dict[str, str]] - Mapping of attributes to their display labels for a table representation. Planned for future implementation.

  • field_style Optional[str] - Style of the field, can be one of ["list", "table", "string"]. Defaults to "string". Planned for future implementation.

Notes​

The attributes headers and field_style are planned for future releases and are not currently implemented.

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

overflow_value​

def overflow_value(preserve_newlines: bool = False,
                   input_width: int = 80,
                   overflow_message: str = "",
                   preserve_words: bool = True) -> Any

Retrieve the overflow portion of a variable that exceeds the content of safe_value().

This function addresses both list-like objects and strings, ensuring that the returned overflow content adheres to whitespace preferences specified by the parameters.

Arguments​

  • preserve_newlines bool, optional - Determines the treatment of newline characters. If True, the returned string can contain single newline characters. Sequences of newline characters, including Windows-style "rn", will be reduced to a single "n". Double spaces will be replaced with a single space. If False, all whitespace, including newlines and tabs, will be replaced with a single space. Defaults to False.

  • input_width int, optional - The width of the input field or display area, used for determining overflow. Defaults to 80.

  • overflow_message str, optional - Message indicating overflow in the safe value. Defaults to "".

  • preserve_words bool, optional - If True, ensures words are not split between the main content and the overflow. Defaults to True.

Returns​

  • Any - The portion of the variable exceeding the content safe for display, considered as overflow.

max_lines​

def max_lines(input_width: int = 80) -> int

Compute the maximum number of lines that can fit in the input given the specified input width.

Arguments​

  • input_width int, optional - The width of the input or display area. Defaults to 80.

Returns​

  • int - The maximum number of lines accommodated by the input width.

value​

def value() -> Any

Retrieve the complete value without considering overflow constraints.

This can be especially helpful in appendices where there's a desire to showcase the entire value without the necessity of toggling between various sections or pages.

Returns​

  • Any - The whole value of the field, irrespective of overflow.

has_overflow​

def has_overflow(overflow_message: str = "",
                 input_width: int = 80,
                 preserve_newlines: bool = False,
                 _original_value: Optional[str] = None,
                 preserve_words: bool = True) -> bool

Return True only if the value's length exceeds the overflow trigger.

Arguments​

  • overflow_message str - A short message to go on the page where text is cutoff.
  • input_width int - The width, in characters, of the input box. Defaults to 80.
  • preserve_newlines bool - Determines whether newlines are preserved in the "safe" text. Defaults to False, which means all newlines are removed. This allows more text to appear before being sent to the addendum.
  • _original_value Any - for speed reasons, you can provide the full text and just use this method to determine if the overflow trigger is exceeded. If no _original_value is provided, this method will determine it using the value_if_defined() method.
  • preserve_words bool - If True, the algorithm will try to preserve whole words when truncating the text. If False, the algorithm will truncate the text at the overflow trigger, regardless of whether it is in the middle of a word.

Returns​

  • bool - True if the value's length exceeds the overflow trigger, False otherwise.

original_or_overflow_message​

def original_or_overflow_message(
        overflow_message: str = "",
        input_width: int = 80,
        preserve_newlines: bool = False,
        _original_value: Optional[str] = None,
        preserve_words: bool = True) -> Union[str, List[Any]]

Return the original value if it is less than the overflow trigger (once processed), otherwise return the overflow message.

Unlike safe_value(), this will never output a partial value.

Arguments​

  • overflow_message str - A short message to go on the page where text is cutoff.
  • input_width int - The width, in characters, of the input box. Defaults to 80.
  • preserve_newlines bool - Determines whether newlines are preserved in the "safe" text. Defaults to False, which means all newlines are removed. This allows more text to appear before being sent to the addendum.
  • _original_value Any - for speed reasons, you can provide the full text and just use this method to determine if the overflow trigger is exceeded. If no _original_value is provided, this method will determine it using the value_if_defined() method.
  • preserve_words bool - If True, the algorithm will try to preserve whole words when truncating the text. If False, the algorithm will truncate the text at the overflow trigger, regardless of whether it is in the middle of a word.

Returns​

Union[str, List[Any]]: Either a string representing the overflow message or the original value

safe_value​

def safe_value(overflow_message: str = "",
               input_width: int = 80,
               preserve_newlines: bool = False,
               _original_value: Optional[str] = None,
               preserve_words: bool = True) -> Union[str, List[Any]]

Return just the portion of the variable that heuristics suggest will fit in the specified overflow_trigger limit. If the value is not defined, return an empty string.

When preserve_newlines is True, the output will be limited to a number of lines, not a number of characters. The max number of lines will be calculated as floor(self.overflow_trigger/input_width). Therefore, it is important that input_width is a divisor of overflow_trigger.

Whitespace will be altered. If preserve_newlines is true, the return value may have newlines, but double newlines and Windows style (rn) will be replaced with n. Double spaces will be replaced with a single space.

If preserve_newlines is false, all whitespace, including newlines and tabs, will be replaced with a single space.

Arguments​

  • overflow_message str - A short message to go on the page where text is cutoff.
  • input_width int - The width, in characters, of the input box. Defaults to 80.
  • preserve_newlines bool - Determines whether newlines are preserved in the "safe" text. Defaults to False, which means all newlines are removed. This allows more text to appear before being sent to the addendum.
  • _original_value Optional[str] - For speed reasons, you can provide the full text and just use this method to determine if the overflow trigger is exceeded. If no _original_value is provided, this method will determine it using the value_if_defined() method.
  • preserve_words bool - Indicates whether words should be preserved in their entirety without being split.

Returns​

Union[str, List[Any]]: The portion of the variable that fits within the overflow trigger.

value_if_defined​

def value_if_defined() -> Any

Fetch the value of the designated field if it exists; otherwise, return an empty string.

This method ensures that the addendum does not inadvertently trigger docassemble's variable gathering.

Returns​

  • Any - The value of the field if it exists, otherwise an empty string.

__str__​

def __str__()

Represent the ALAddendumField instance as a string.

Returns​

  • str - The string representation of the value contained within the field.

columns​

def columns(skip_empty_attributes: bool = True,
            skip_attributes: Optional[set] = None) -> Optional[list]

Return a list of the attributes present within the object that would make sense to go in the table of an addendum.

If the headers attribute exists, this will be prioritized. Otherwise, the method will infer columns from the first value in the list. Empty attributes and the complete attribute are typically ignored.

Arguments​

  • skip_empty_attributes bool, optional - Determines whether empty attributes are included in the list. Defaults to True.
  • skip_attributes Optional[set], optional - A set of attributes to ignore. Defaults to {"complete"}.

Returns​

  • Optional[list] - A list of columns or None if no meaningful columns can be determined.

Notes​

The "location" attribute of an Address object is always skipped in the column list.

type​

def type() -> str

Determine the data type of the contained value.

Categories:

  • 'list': A simple list.
  • 'object_list': A list containing dictionaries or objects.
  • 'other': Any other type.

Returns​

  • str - The type category of the value.

is_list​

def is_list() -> bool

Check if the field contains a list value, whether it consists of objects, dictionaries, or standard values.

Returns​

  • bool - True if the field contains a list, otherwise False.

is_object_list​

def is_object_list() -> bool

Determine if the field contains a list of dictionaries or objects.

Returns​

  • bool - True if the field contains a list of dictionaries or objects, otherwise False.

overflow_markdown​

def overflow_markdown() -> str

Generate a markdown representation of the overflow values.

The method returns either a markdown table or a bulleted list based on the structure of the values. This utility offers a standardized way to represent overflow content, though users might prefer to manually control the output's format.

Returns​

  • str - A markdown representation of the overflow values.

overflow_docx​

def overflow_docx(
    path: str = "docassemble.ALDocumentDict:data/templates/addendum_table.docx"
) -> Any

Insert a formatted table into a docx file, representing the overflow values.

This method provides a convenient way to add overflow content into a docx file, although it doesn't offer formatting control. If more formatting flexibility is required, consider directly fetching the overflow values using the overflow_value() method.

Arguments​

  • path str, optional - Path to the template docx file to be used. Defaults to a predetermined path.

Returns​

A docx template with the inserted table.

ALAddendumFieldDict Objects​

class ALAddendumFieldDict(DAOrderedDict)

A specialized dictionary for managing fields that may overflow in a document.

This class assists in organizing and controlling fields that might exceed a specified character limit in a document. It provides utilities to determine if an overflow condition exists and to correctly display fields in various contexts, ensuring only the necessary text is shown.

Adding a new entry will implicitly set the field_name attribute of the field

Attributes​

  • style str - Determines the display behavior. If set to "overflow_only", only the overflow text will be displayed.

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

initializeObject​

def initializeObject(*pargs, **kwargs) -> Any

Initializes a new dictionary entry and sets its field_name attribute.

When an entry is implicitly created, this method ensures the item knows its own field name by setting the field_name attribute.

Arguments​

  • *pargs - List of arguments to use to create the dict entry. The 0th arg is also used to set the field_name attribute.
  • **kwargs - List of keyword arguments used to create the dict entry

Returns​

The new dictionary entry created

from_list​

def from_list(data: List[Dict]) -> None

Populate the dictionary using a list of field data.

Arguments​

  • data list - List of dictionaries containing ield data with keys "field_name" and "overflow_trigger".

defined_fields​

def defined_fields(style: str = "overflow_only") -> list

Fetch a list of fields that are defined.

Arguments​

  • style str, optional - If set to "overflow_only", only the fields with overflow values will be returned. Defaults to "overflow_only".

Returns​

  • list - List of defined fields based on the specified style.

overflow​

def overflow() -> list

Retrieve fields that have overflowed their character limits.

Returns​

  • list - A list of fields with overflow values.

has_overflow​

def has_overflow() -> bool

Determine if any field within the dictionary exceeds its overflow limit.

Returns​

  • bool - True if at least one field overflows, False otherwise.

DALazyAttribute Objects​

class DALazyAttribute(DAObject)

Extends the DAObject to support attributes that are re-evaluated with every page load.

This is particularly helpful when there's a need to cache information on a per-page basis. The implementation leverages Docassemble's object pickling process by customizing the __getstate__ method that Pickle uses for serialization.

Attributes​

  • instanceName str - A unique identifier for the object instance, if available.

__getstate__​

def __getstate__() -> dict

Overrides the default method used by Pickle for object serialization.

If the object has an instanceName attribute, it is retained during serialization. Otherwise, an empty dictionary is returned, ensuring that other attributes are not persisted across page loads.

Returns​

  • dict - A dictionary containing only the instanceName if it exists, or empty otherwise.

ALDocument Objects​

class ALDocument(DADict)

A dictionary of attachments, either created by a DAFile or an attachment block. Typically there are three:

  1. The final version of a document with a signature. E.g., my_doc['final'].
  2. The preview version of a document with no signature. E.g., my_doc['preview'].
  3. An addendum of a document contained in the attribute addendum. E.g. my_doc.addendum.

There is no limit to the number of keys, but the ALDocumentBundle class expects at least a "final" key to exist, and the addendum attribute is required if you desire to use PDF documents with text overflow. It is best practice to use exactly the two keys "final" and "preview" and the attribute "addendum". The "final" and "preview" documents will normally be the same template, but with logic controlling the display of a particular section, such as the signature.

Each form that an interview generates should get its own ALDocument object.

The "addendum" attribute can be handled in a generic object block. Multiple documents can use the same addendum template, with just the case caption varying.

ALDocuments are designed to be used contingently as part of ALDocumentBundle objects. Each ALDocument is considered to be "enabled" or "disabled" for a particular interview user's session. This allows you to always work with a single object representing all of the possible documents an interview can generate, and use encapsulated logic to trigger individual documents inclusion on the final download screen.

Attributes​

  • filename str - name used for output PDF
  • title str - display name for the output PDF
  • enabled bool - if this document should be created. See examples.
  • addendum DAFile | DAFileCollection - (optional) an attachment block
  • overflow_fields ALAddendumField - (optional) ALAddendumFieldDict instance. These values will be used to detect and handle overflow.
  • has_addendum bool - (optional) Defaults to False. Set to True if the document could have overflow, like for a PDF template.

Notes​

The enabled attribute should always be defined by a code block or the objects block, because by default it is considered fresh on each page load. If your interview logic requires that you directly ask the user whether or not to include a document, you can use a single intermediate variable that is posed to the interview user to work around this limitation.

  • Examples - # TODO: the code blocks aren't working right yet on the Docusaurus page.

    Simple use where the document is always enabled and will have no addendum​

    ---
    objects:
      - my_doc: ALDocument.using(filename="myDoc.pdf", title="myDoc", enabled=True)
    ---
    attachment:
      variable name: my_doc[i]  # This same template will be used for the `preview` and `final` keys
      content: |
        Here is some content

        % if i == 'final':
        ${ users[0].signature }
        % elif i == 'preview':
        [ Your signature here ]
        % endif

    Enable a document conditionally​

    ---
    # See that `enabled` is not defined here
    objects:
      - affidavit_of_indigency: ALDocument.using(filename="affidavit-of-indigency.pdf", title="Affidavit of Indigency")
    ---
    code: |
      affidavit_of_indigency.enabled = ask_indigency_questions and is_indigent

    An example enabling with a question posed to the interview user​

    You should always use a code block or an object block to set the "enabled" status; Use an intermediate variable if you want to ask the user directly whether or not to include a document.

    ---
    question: |
      Do you want the extra document included?
    fields:
      - no label: include_extra_document
        datatype: yesnoradio
    ---
    code: |
      extra_document.enabled = include_extra_document
    ---
    attachment:
        variable name: extra_document[i] # This same template will be used for `final` and `preview`
        docx template file: extra_document.docx

    For a document that may need an addendum, you must specify this when the object is created or in a mandatory code block. The addendum will only be triggered if the document has "overflow" in one of the fields that you specify.

    ---
    objects:
      - my_doc: ALDocument.using(filename="myDoc.pdf", title="myDoc", enabled=True, has_addendum=True)
    ---
    attachment:
        variable name: my_doc[i]
        ...
    ---
    generic object: ALDocument
    attachment:
      variable name: x.addendum
      docx template file: docx_addendum.docx
    ---
    code: |
      my_doc.overflow_fields['big_text_variable'].overflow_trigger = 640 # Characters
      my_doc.overflow_fields['big_text_variable'].label = "Big text label" # Optional - you may use in your addendum
      my_doc.overflow_fields['list_of_objects_variable'].overflow_trigger = 4 # Items in the list
      my_doc.overflow_fields.gathered = True

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

as_pdf​

def as_pdf(key: str = "final",
           refresh: bool = True,
           pdfa: bool = False,
           append_matching_suffix: bool = True) -> DAFile

Generates a PDF version of the assembled document.

Arguments​

  • key str - Document version key. Defaults to "final".
  • refresh bool - If True, generates the attachment anew each time. Defaults to True.
  • pdfa bool - If True, generates a PDF/A compliant document. Defaults to False.
  • append_matching_suffix bool - If True, appends the key as a suffix to the filename when it matches the suffix to append. Defaults to True.

Returns​

  • DAFile - Assembled document in PDF format, possibly combined with addendum.

as_docx​

def as_docx(key: str = "final",
            refresh: bool = True,
            append_matching_suffix: bool = True) -> DAFile

Generates a DOCX version of the assembled document, if possible. Falls back to PDF if not.

Arguments​

  • key str - Document version key. Defaults to "final".
  • refresh bool - If True, generates the attachment anew each time. Defaults to True.
  • append_matching_suffix bool - If True, appends the key as a suffix to the filename when it matches the suffix to append. Defaults to True.

Returns​

  • DAFile - Assembled document in DOCX or PDF format.

as_list​

def as_list(key: str = "final", refresh: bool = True) -> List[DAFile]

Generates a list containing the main document and its addendum, if applicable.

Arguments​

  • key str - Document version key. Defaults to "final".
  • refresh bool - If True, generates the attachments anew each time. Defaults to True.

Returns​

  • List[DAFile] - List containing the main document and possibly its addendum.

need_addendum​

def need_addendum() -> bool

Determines if there's a need for an addendum in the document. First checks if the addendum is enabled, and then checks if there's overflow.

Returns​

  • bool - True if an addendum is needed, False otherwise.

has_overflow​

def has_overflow() -> bool

Checks if the document has fields that exceed their character limits.

Returns​

  • bool - True if there are overflow fields, False otherwise.

overflow​

def overflow() -> list

Retrieves a list of fields that have overflowed their character limits.

Returns​

  • list - List of overflow fields.

original_or_overflow_message​

def original_or_overflow_message(
        field_name: str,
        overflow_message: str = "",
        input_width: int = 80,
        preserve_newlines: bool = False,
        _original_value: Optional[str] = None,
        preserve_words: bool = True) -> Union[str, List[Any]]

Helper syntax to access a member field.

Return the original value if it is less than the overflow trigger (once processed), otherwise return the overflow message.

Unlike safe_value(), this will never output a partial value.

Arguments​

  • field_name str - The name of the field to check.
  • overflow_message str - A short message to go on the page where text is cutoff.
  • input_width int - The width, in characters, of the input box. Defaults to 80.
  • preserve_newlines bool - Determines whether newlines are preserved in the "safe" text. Defaults to False, which means all newlines are removed. This allows more text to appear before being sent to the addendum.
  • _original_value Any - for speed reasons, you can provide the full text and just use this method to determine if the overflow trigger is exceeded. If no _original_value is provided, this method will determine it using the value_if_defined() method.
  • preserve_words bool - If True, the algorithm will try to preserve whole words when truncating the text. If False, the algorithm will truncate the text at the overflow trigger, regardless of whether it is in the middle of a word.

Returns​

Union[str, List[Any]]: Either the original value or the overflow message, never a truncated value.

safe_value​

def safe_value(field_name: str,
               overflow_message: Optional[str] = None,
               preserve_newlines: bool = False,
               input_width: int = 80,
               preserve_words: bool = True) -> str

Retrieve the "safe" value of a specified field, which is shorter than the overflow trigger.

Arguments​

  • field_name str - The name of the field to retrieve the safe value from.
  • overflow_message Optional[str] - Message to display when the field value overflows. Defaults to the class's default overflow message.
  • preserve_newlines bool - Whether to maintain newlines in the output. Defaults to False.
  • input_width int - The expected input width, used for formatting. Defaults to 80.
  • preserve_words bool - Whether to avoid splitting words during formatting. Defaults to True.

Returns​

  • str - The "safe" value of the specified field.

overflow_value​

def overflow_value(field_name: str,
                   overflow_message: Optional[str] = None,
                   preserve_newlines: bool = False,
                   input_width: int = 80,
                   preserve_words: bool = True) -> str

Retrieve the "overflow" value of a specified field, which is the amount exceeding the overflow trigger.

Arguments​

  • field_name str - The name of the field to retrieve the overflow value from.
  • overflow_message Optional[str] - Message to display when the field value overflows. Defaults to the object's default overflow message.
  • preserve_newlines bool - Whether to maintain newlines in the output. Defaults to False.
  • input_width int - The expected input width, used for formatting. Defaults to 80.
  • preserve_words bool - Whether to avoid splitting words during formatting. Defaults to True.

Returns​

  • str - The "overflow" value of the specified field.

is_enabled​

def is_enabled(refresh: bool = True) -> bool

Determine if a document is considered "enabled" based on various conditions.

A document is "enabled" if:

  1. The .always_enabled attribute is set to true (i.e., enabled at initialization).
  2. The .enabled attribute is set to true (calculated fresh once per page load).
  3. The cache.enabled attribute is set to true.

Arguments​

  • refresh bool - If True, refreshes the enabled status of the document. Defaults to True.

Returns​

  • bool - True if the document is enabled, otherwise False.

ALStaticDocument Objects​

class ALStaticDocument(DAStaticFile)

A class for initializing static documents for inclusion in an ALDocumentBundle with a one-liner.

Notes​

Static files should always be placed in the /data/static folder of a package. The /data/templates folder is private and the ALDocumentBundle requires publicly accessible files.

Attributes​

  • filename str - Path to the file within /data/static/.
  • title str - Title displayed as a row when invoking download_list_html() method from ALDocumentBundle.

Examples:

Add a static PDF file to a document bundle. .. code-block:: yaml​

objects:

  • static_test: ALStaticDocument.using(title="Static Test", filename="static.pdf", enabled=True)

objects:

  • bundle: ALDocumentBundle.using(elements=[static_test], filename="bundle", title="Documents to download now")

Todo:

Consider handling files in /data/templates if deemed useful, potentially by copying into a DAFile using pdf_concatenate().

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

__getitem__​

def __getitem__(key)

Override to ensure 'final' and 'private' keys always exist and reference the same file.

Returns​

  • ALStaticDocument - Returns self.

as_list​

def as_list(key: str = "final", refresh: bool = True) -> List[DAStaticFile]

Get the document as a list.

Arguments​

  • key str - Key to access the document. Defaults to "final".
  • refresh bool - Whether to refresh the document. Defaults to True.

Returns​

  • List[DAStaticFile] - A list containing this document.

as_pdf​

def as_pdf(key: str = "final",
           pdfa: bool = False,
           filename: str = "",
           append_matching_suffix: bool = True,
           refresh: bool = False) -> Union[DAStaticFile, DAFile]

Convert the document into PDF format.

Arguments​

  • key str - Key to access the document. Defaults to "final".
  • pdfa bool - Whether to return the document in PDF/A format. Defaults to False.
  • filename str - Name for the converted file. Defaults to the original filename.
  • append_matching_suffix bool - Whether to append a matching suffix to the filename. Defaults to True.
  • refresh bool - Whether to refresh the document. Defaults to False.

Returns​

Union[DAStaticFile, DAFile]: The document in PDF format.

as_docx​

def as_docx(
        key: str = "final",
        refresh: bool = True,
        append_matching_suffix: bool = False) -> Union[DAStaticFile, DAFile]

Convert the document into DOCX format, if possible. If not, return as PDF.

Arguments​

  • key str - Key to access the document. Defaults to "final".
  • refresh bool - Whether to refresh the document. Defaults to True.
  • append_matching_suffix bool - Not used for static documents. They remain unchanged.

Returns​

Union[DAStaticFile, DAFile]: The document in DOCX or PDF format.

show​

def show(**kwargs) -> DAFile

Display the document.

This method provides a workaround for problems generating thumbnails.

Arguments​

  • **kwargs - Args to pass to DAFile's show function

Returns​

  • DAFile - Displayable version of the document.

is_enabled​

def is_enabled(**kwargs) -> bool

Check if the document is enabled.

Arguments​

  • **kwargs - Unused (for signature compatibility only)

Returns​

  • bool - True if the document is enabled, otherwise False.

ALDocumentBundle Objects​

class ALDocumentBundle(DAList)

A collection of ALDocuments or nested ALDocumentBundles, represented as a DAList.

This class provides functionalities for grouping multiple documents or nested bundles in a specific order. For instance, you might want to bundle documents differently for the court, the user, and the opposing party. Each ALDocument within this bundle can be individually "enabled" or "disabled", which will determine its inclusion in the generated bundle.

A bundle can be output as a single merged PDF or as a list of individual documents. For nested bundles, each can be rendered as a merged PDF or a list of documents.

Attributes​

  • filename str - The name of the output file (without extension).
  • title str - The title of the bundle.
  • enabled bool, optional - Determines if the bundle is active. Defaults to True.
  • auto_gather bool, optional - Automatically gathers attributes. Defaults to False.
  • gathered bool, optional - Specifies if attributes have been gathered. Defaults to True.
  • default_parity Optional[Literal["even", "odd"]] - Default parity to enforce on the PDF. Defaults to None.

Examples:

Given three documents: Cover page, Main motion form, and Notice of Interpreter Request, bundle them as follows:

bundle = ALDocumentBundle(elements=[cover_page, main_motion, notice_of_request],
                          filename="documents_bundle", title="Document Set")

Convert the bundle to a PDF:

combined_pdf = bundle.as_pdf()

Convert the bundle to a zip archive containing individual PDFs:

zipped_files = bundle.as_zip()

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

as_pdf​

def as_pdf(
    key: str = "final",
    refresh: bool = True,
    pdfa: bool = False,
    append_matching_suffix: bool = True,
    ensure_parity: Optional[Literal["even",
                                    "odd"]] = None) -> Optional[DAFile]

Returns a consolidated PDF of all enabled documents in the bundle.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • refresh bool - Flag to return a newly assembled version, default is True.
  • pdfa bool - If True, generates a PDF/A compliant document, defaults to False.
  • append_matching_suffix bool - Flag to determine if matching suffix should be appended to file name, default is True. Used primarily to enhance automated tests.
  • ensure_parity Optional[Literal["even", "odd"]] - Ensures the number of pages in the PDF is even or odd. If omitted, no parity is enforced. Defaults to None.

Returns​

  • Optional[DAFile] - Combined PDF file or None if no documents are enabled.

__str__​

def __str__() -> str

Produces a string representation of the PDF in a compatible method with the DAFile class. In an interview, this will show a thumbnail of the PDF by default.

Returns​

  • str - String representation of the PDF.

as_zip​

def as_zip(key: str = "final",
           refresh: bool = True,
           pdfa: bool = False,
           title: str = "",
           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.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.
  • pdfa bool - If True, all PDFs in the zip will be PDF/A compliant, defaults to False.
  • title str - Title of the zip file, shown next to the button to download the zip. Defaults to the bundle's title.
  • format str - Format of the documents in the zip file (e.g., "pdf", "docx", "original"), default is "pdf".
  • include_pdf bool - Flag to include a PDF version of the document if it's originally in docx format, default is True.

Returns​

  • DAFile - A zip file containing the enabled documents.

preview​

def preview(refresh: bool = True) -> Optional[DAFile]

Returns a preview version of the bundle as a PDF.

Arguments​

  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.

Returns​

  • Optional[DAFile] - Preview PDF file or None if no documents are enabled.

has_enabled_documents​

def has_enabled_documents(refresh=False) -> bool

Checks if there is at least one enabled document in the bundle.

Arguments​

  • refresh bool - Flag to reconsider the 'enabled' attribute, default is False.

Returns​

  • bool - True if there's at least one enabled document, otherwise False.

enabled_documents​

def enabled_documents(refresh: bool = True) -> List[Any]

Retrieves all enabled documents within the bundle.

Arguments​

  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.

Returns​

  • List[Any] - List of enabled documents.

as_flat_list​

def as_flat_list(key: str = "final", refresh: bool = True) -> List[DAFile]

Flattens and returns all enabled documents in the bundle, even from nested bundles.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.

Returns​

  • List[DAFile] - Flattened list of enabled documents.

get_titles​

def get_titles(key: str = "final", refresh: bool = True) -> List[str]

Retrieves the titles of all enabled documents in the bundle.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.

Returns​

  • List[str] - Titles of the enabled documents.

as_pdf_list​

def as_pdf_list(key: str = "final",
                refresh: bool = True,
                pdfa: bool = False) -> List[DAFile]

Returns all enabled documents in the bundle as individual PDFs, even from nested bundles.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • refresh bool - Flag to reconsider the 'enabled' attribute and regenerate the enabled documents, default is True.
  • pdfa bool - Flag to return the documents in PDF/A format, default is False.

Returns​

  • List[DAFile] - List of enabled documents as individual PDFs.

as_docx_list​

def as_docx_list(key: str = "final", refresh: bool = True) -> List[DAFile]

Generates a list of enabled documents from the bundle represented as DOCX files.

If a particular document can't be represented as a DOCX, its original format or a PDF is returned.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.

Returns​

  • List[DAFile] - List of documents represented as DOCX files or in their original format.

as_editable_list​

def as_editable_list(key: str = "final", refresh: bool = True) -> List[DAFile]

Generates a list of editable (DOCX or RTF) versions of the documents in the bundle.

For documents that are not in DOCX or RTF formats, the original file format is returned.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.

Returns​

  • List[DAFile] - Flat list of documents in DOCX or RTF formats or their original format.

get_cacheable_documents​

def get_cacheable_documents(
    key: str = "final",
    pdf: bool = True,
    docx: bool = False,
    original: bool = False,
    refresh: bool = True,
    pdfa: bool = False,
    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 and returned for use in a background process.

The result looks like this:

[ {"title": "Document 1", "pdf": DAFile, "docx": DAFile, download_filename: str}, ], DAFile, # Zip of whole bundle DAFile # PDF of whole bundle

Arguments​

  • key str - Identifier for the document version, default is "final".
  • pdf bool - Flag to include a PDF version of each file, default is True.
  • docx bool - Flag to include a DOCX version of each file, default is False.
  • original bool - Flag to include the original version of each file, default is False.
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.
  • pdfa bool - Flag to return documents in PDF/A format, default is False.
  • 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

download_list_html​

def download_list_html(key: str = "final",
                       format: str = "pdf",
                       view: bool = True,
                       refresh: bool = True,
                       pdfa: bool = False,
                       include_zip: bool = True,
                       view_label="View",
                       view_icon: str = "eye",
                       download_label: str = "Download",
                       download_icon: str = "download",
                       send_label: str = "Send",
                       send_icon: str = "envelope",
                       zip_label: Optional[str] = None,
                       zip_icon: str = "file-archive",
                       zip_row_label: Optional[str] = "",
                       append_matching_suffix: bool = True,
                       include_email: bool = False,
                       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.

Arguments​

  • key str - Identifier for the document version, default is "final".
  • format str - Specifies the format of the files in the list. Can be "pdf", "docx", or "original". Default is "pdf".
  • view bool - Flag to include a 'view' button, default is True.
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.
  • pdfa bool - Flag to return documents in PDF/A format, default is False.
  • include_zip bool - Flag to include a zip option, default is True.
  • view_label str - Label for the 'view' button, default is "View".
  • view_icon str - Icon for the 'view' button, default is "eye".
  • download_label str - Label for the 'download' button, default is "Download".
  • download_icon str - Icon for the 'download' button, default is "download".
  • send_label str - Label for the 'send' button. Default is "Send".
  • send_icon str - Fontawesome icon for the 'send' button. Default is "envelope".
  • zip_label Optional[str] - Label for the zip option. If not provided, uses the generic template for self.zip_label ("Download all").
  • zip_icon str - Icon for the zip option, default is "file-archive".
  • zip_row_label str, optional - Text to go in the left-most column of the table's zip row. Will default to the value of self.title.
  • append_matching_suffix bool - Flag to determine if matching suffix should be appended to file name, default is True.
  • include_email bool - Flag to include an option, default is False.
  • 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.

download_html​

def download_html(key: str = "final",
                  format: str = "pdf",
                  pdfa: bool = False,
                  view: bool = True,
                  refresh: bool = True,
                  view_label: str = "View",
                  view_icon: str = "eye",
                  download_label: str = "Download",
                  download_icon: str = "download") -> str

Returns an HTML string of a table to display all the docs combined into one pdf with 'view' and 'download' buttons.

Deprecated; use download_list_html instead

Arguments​

  • key str - Identifier for the document version, default is "final".
  • format str - Specifies the format of the files in the list. Can be "pdf", "docx", or "original". Default is "pdf".
  • pdfa bool - Flag to return the documents in PDF/A format, default is False.
  • view bool - Flag to include a 'view' button, default is True.
  • refresh bool - Flag to reconsider the 'enabled' attribute, default is True.
  • view_label str - Label for the 'view' button, default is "View".
  • view_icon str - Icon for the 'view' button, default is "eye".
  • download_label str - Label for the 'download' button, default is "Download".
  • download_icon str - Icon for the 'download' button, default is "download".

Returns​

  • str - HTML representation of a table with documents and their associated actions.

send_email_table_row​

def send_email_table_row(key: str = "final",
                         send_label: str = "Send",
                         send_icon: str = "envelope") -> str

Generate HTML doc table row for an input box and button that allows someone to send the bundle to the specified email address.

Arguments​

  • key str - A key used to identify which version of the ALDocument to send. Defaults to "final".
  • send_label str - Label for the 'send' button. Default is "Send".
  • send_icon str - Icon for the 'send' button. Default is "envelope".

Returns​

  • str - The generated HTML string for the table row.

send_button_to_html​

def send_button_to_html(
        email: str,
        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 specific email address. The email address is not editable by the end user in contrast to send_button_html.

Arguments​

  • email str - The recipient's email address.
  • 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.

send_button_html​

def send_button_html(
        key: str = "final",
        show_editable_checkbox: bool = True,
        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 to the specified email address.

Optionally, display a checkbox that allows someone to decide whether or not to include an editable (Word) copy of the file, if and only if it is available.

Arguments​

  • 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. 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.

send_email​

def send_email(to: Any = None,
               key: str = "final",
               editable: Optional[bool] = None,
               template: Optional[Any] = None,
               preferred_formats: Optional[Union[str, List[str]]] = "pdf",
               **kwargs) -> bool

Send an email with the current bundle as a series of flat pdfs (one per bundle entry) or as editable documents. This function is similar to https://docassemble.org/docs/functions.html#send_email with additional parameters.

Arguments​

  • 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. (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.

is_enabled​

def is_enabled(refresh=True) -> bool

Check if the bundle itself is enabled, and if it has at least one enabled child document.

Arguments​

  • refresh bool - Whether to refresh the enabled status. Defaults to True.

Returns​

  • bool - Indicates if the bundle and its child documents are enabled.

as_docx​

def as_docx(key: str = "final",
            refresh: bool = True,
            append_matching_suffix: bool = True) -> DAFile

Convert the enabled documents to a single DOCX file or PDF file if conversion fails.

Arguments​

  • key str, optional - The key to identify enabled documents. Defaults to "final".
  • refresh bool, optional - Refresh the enabled documents before conversion. Defaults to True.
  • append_matching_suffix bool, optional - Append a matching suffix to the output filename. Defaults to True.

Returns​

  • DAFile - A DAFile object containing the concatenated DOCX or PDF file.

as_list​

def as_list(key: str = "final", refresh: bool = True) -> List[DAFile]

Return a list of enabled documents.

Arguments​

  • key str, optional - The key to identify enabled documents. Defaults to "final".
  • refresh bool, optional - Refresh the enabled documents before returning the list. Defaults to True.

Returns​

  • List[DAFile] - A list of enabled DAFile objects.

ALExhibit Objects​

class ALExhibit(DAObject)

Class to represent a single exhibit, with cover page, which may contain multiple documents representing pages.

Attributes​

  • pages list - List of individual DAFiles representing uploaded images or documents.
  • cover_page DAFile | DAFileCollection - (optional) A DAFile or DAFileCollection object created by an attachment: block Will typically say something like "Exhibit 1"
  • label str - A label, like "A" or "1" for this exhibit in the cover page and table of contents
  • starting_page int - first page number to use in table of contents

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

ocr_ready​

def ocr_ready() -> bool

Returns True if the OCR process is complete. OCR is non-blocking, and assembly will work even if OCR is not complete. Check this status if you want to wait to deliver a document until OCR is complete.

Will return true (but log a warning) if OCR was never started on the documents. That situation is likely a developer error, as you shouldn't wait for OCR if it never started

Returns​

  • bool - True iff OCR process has finished on all pages.

ocr_pages​

def ocr_pages() -> List[DAFile]

Retrieve the OCR-processed version of pages if available, else return the original pages.

Returns​

  • List[DAFile] - List of pages, either OCR-processed or original.

as_pdf​

def as_pdf(*,
           refresh: bool = False,
           prefix: str = "",
           pdfa: bool = False,
           add_page_numbers: bool = True,
           add_cover_page: bool = True,
           filename: Optional[str] = None,
           append_matching_suffix: bool = True) -> DAFile

Generates a PDF version of the exhibit, with optional features like Bates numbering or a cover page.

Note that these are keyword only parameters, not positional.

Arguments​

  • refresh bool - If True, forces the exhibit to refresh before generating the PDF. (unused, provided for signature compatibility)
  • prefix str - Prefix for Bates numbering if 'add_page_numbers' is True.
  • pdfa bool - If True, the generated PDF will be in PDF/A format.
  • add_page_numbers bool - If True, apply Bates numbering starting from 'self.start_page'.
  • add_cover_page bool - If True, prepend the exhibit with a cover page.
  • filename Optional[str] - Custom filename for the generated PDF. Default is "exhibits.pdf".
  • append_matching_suffix bool - If True, appends a suffix to the filename based on certain matching criteria.

Returns​

  • DAFile - PDF representation of the exhibit.

num_pages​

def num_pages() -> int

Calculate the total number of pages in the exhibit.

Returns​

  • int - Total page count.

complete​

@property
def complete() -> bool

For purposes of list gathering, trigger the attributes in the order necessary to gather a complete exhibit object.

Indicates if the exhibit is complete.

NOTE: This property always returns True after triggering the required attributes.

__str__​

def __str__() -> str

Return the title of the exhibit.

Returns​

  • str - Title of the exhibit.

ocrmypdf_task​

def ocrmypdf_task(from_file: Union[DAFile, DAFileList],
                  to_pdf: DAFile) -> Optional[str]

Processes the provided files using the 'ocrmypdf' utility to apply Optical Character Recognition (OCR).

If the source file is an image (e.g., png, jpg, jpeg, gif), this function sets the image DPI to 300. For non-image files, the text in the file is skipped during OCR.

This function is designed to be executed as a background task (id: al_exhibit_ocr_pages_bg).

Arguments​

  • from_file Union[DAFile, DAFileList] - The source file or list of files to be OCR-processed.
  • to_pdf DAFile - The destination file where the OCR-processed output will be saved.

Returns​

  • Optional[str] - The path of the OCR-processed file if successful; None otherwise.

Raises​

  • subprocess.TimeoutExpired - If the ocrmypdf process takes longer than an hour.

ALExhibitList Objects​

class ALExhibitList(DAList)

A list representation of ALExhibit objects. Provides utility functions for managing exhibits and rendering them into a single PDF file.

Attributes​

  • maximum_size int - The maximum allowed size in bytes of the entire document.
  • auto_label bool - If True, automatically numbers exhibits for cover page and table of contents. Defaults to True.
  • auto_labeler Callable - An optional function or lambda to transform the exhibit's index to a label. Uses A..Z labels by default.
  • auto_ocr bool - If True, automatically starts OCR processing for uploaded exhibits. Defaults to True.

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

as_pdf​

def as_pdf(filename="file.pdf",
           pdfa: bool = False,
           add_page_numbers: bool = False,
           toc_pages: int = 0,
           append_matching_suffix: bool = True) -> DAFile

Compiles all exhibits in the list into a single PDF.

Arguments​

  • filename str - Desired filename for the generated PDF.
  • pdfa bool - If True, generates the PDF in PDF/A format.
  • add_page_numbers bool - If True, adds page numbers to the generated PDF.
  • toc_pages int - Expected number of pages in the table of contents.
  • append_matching_suffix bool - If True, appends matching suffix to the filename.

Returns​

  • DAFile - A single PDF containing all exhibits.

size_in_bytes​

def size_in_bytes() -> int

Calculates the total size in bytes of all exhibits in the list.

Returns​

  • int - Total size of all exhibits in bytes.

ocr_ready​

def ocr_ready() -> bool

Checks if all exhibits in the list have completed the OCR process.

Returns​

  • bool - True if all exhibits are OCRed or if OCR hasn't started. False otherwise.

hook_after_gather​

def hook_after_gather() -> None

Callback function executed after the entire list of exhibits is collected. Manages auto-labeling and initiates OCR if necessary.

ALExhibitDocument Objects​

class ALExhibitDocument(ALDocument)

Represents a collection of uploaded documents, formatted like a record appendix or an exhibit list, complete with an optional table of contents and page numbering.

Attributes​

  • exhibits ALExhibitList - A list of ALExhibit documents. Each item represents a distinct exhibit, which can span multiple pages.
  • table_of_contents DAFile or DAFileCollection - Generated by an attachment: block.
  • _cache DAFile - A cached version of the exhibit list. Caching is used due to potential long processing times.
  • include_table_of_contents bool - Indicates if a table of contents should be generated.
  • include_exhibit_cover_pages bool - Determines if cover pages should accompany each exhibit.
  • add_page_numbers bool - If True, the as_pdf() method will add page numbers and labels.
  • auto_labeler Callable - A function or lambda for labeling exhibits.

Todo:

  • Implement a method for a safe link in place of the attachment (considering potential filesize constraints on emails).

Examples:

code: |
  # This block is not needed, but you can provide and customize for your needs.
  # This mirrors the fallback block in ql_baseline.yml
  exhibit_attachment.enabled = exhibit_attachment.exhibits.has_exhibits
objects:
  - exhibit_attachment: ALExhibitDocument.using(title="Exhibits", filename="exhibits" , auto_labeler=item_label)

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

has_overflow​

def has_overflow() -> bool

Check if there is any overflow in the document.

This is for compatibility with ALDocument; Exhibits inherently don't have overflow.

Returns​

  • bool - Always False for this implementation.

ocr_ready​

def ocr_ready() -> bool

Determine if all exhibits within the document have undergone OCR processing.

Returns​

  • bool - True if all exhibits have been OCRed or if the OCR process hasn't been initiated.

__getitem__​

def __getitem__(key)

Overridden method to ensure 'final' and 'private' keys always reference the same file.

Arguments​

  • key - The key to fetch the item.

Returns​

  • ALExhibitDocument - Returns the current instance of the class.

as_list​

def as_list(key: str = "final", refresh: bool = True) -> List[DAFile]

Retrieve the document as a list.

Arguments​

  • key str - Identifier key for the document. Default is "final".
  • refresh bool - If True, the document list will be refreshed. Default is True.

Returns​

  • List[DAFile] - A list containing the document.

as_pdf​

def as_pdf(key: str = "final",
           refresh: bool = True,
           pdfa: bool = False,
           append_matching_suffix: bool = True) -> DAFile

Render the document as a PDF.

Arguments​

  • key str - Identifier key for the document. Default is "final". For compatibility with ALDocument.
  • refresh bool - If True, refreshes the PDF document. Default is True. For compatibility with ALDocument.
  • pdfa bool - If True, the output PDF will be in PDF/A format. Default is False.
  • append_matching_suffix bool - If True, appends a matching suffix to the filename.

Returns​

  • DAFile - The document rendered as a PDF.

as_docx​

def as_docx(key: str = "final",
            refresh: bool = True,
            append_matching_suffix: bool = True) -> DAFile

Despite the name, renders the document as a PDF. Provided for signature compatibility.

Arguments​

  • key str, optional - Identifier key for the document. Default is "final".
  • refresh bool, optional - If True, refreshes the DOCX document. Default is True.
  • append_matching_suffix bool, optional - If True, appends a matching suffix to the filename (for automated tests).

Returns​

  • DAFile - The document rendered as a PDF.

ALTableDocument Objects​

class ALTableDocument(ALDocument)

Represents a document tailored for table-like data presentation. This class provides functionality to export data as a table in various formats such as PDF and DOCX.

Attributes​

  • has_addendum bool - A flag indicating the presence of an addendum in the document.
  • suffix_to_append str - Suffix that can be appended to file names, defaulting to "preview".
  • file DAFile, optional - Reference to the generated file (can be PDF, DOCX, etc.).
  • table ??? - Represents the actual table data. Type and attributes need more context to document.

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

has_overflow​

def has_overflow() -> bool

Check for overflow in the document.

For compatibility with ALDocument; Tables inherently don't have overflow.

Returns​

  • bool - Always False for this implementation.

__getitem__​

def __getitem__(key)

Allows for index-based retrieval of a document.

Overridden to ensure 'final' and 'private' keys always return the same document.

Arguments​

  • key - The key to fetch the item.

Returns​

  • DAFile - The document in its PDF format.

as_list​

def as_list(key: str = "final",
            refresh: bool = True,
            **kwargs) -> List[DAFile]

Retrieve the document as a list.

Arguments​

  • key str - Identifier key for the document. Default is "final".
  • refresh bool - If True, the document list will be refreshed. Default is True.

Returns​

  • List[DAFile] - A list containing the document.

as_pdf​

def as_pdf(key: str = "final",
           refresh: bool = True,
           pdfa: bool = False,
           append_matching_suffix: bool = True,
           **kwargs) -> DAFile

Despite the name, returns the document as an Excel Spreadsheet (XLSX file). Name retained for signature compatibility.

Arguments​

  • key str - Identifier key for the document, mainly for compatibility with ALDocument.
  • refresh bool - For signature compatibility
  • pdfa bool - For signature compatibility
  • append_matching_suffix bool - For signature compatibility

Returns​

  • DAFile - The table rendered as an XLSX spreadsheet

as_docx​

def as_docx(key: str = "bool",
            refresh: bool = True,
            append_matching_suffix: bool = True) -> DAFile

Despite the name, returns the document as an Excel Spreadsheet (XLSX file). Name retained for signature compatibility.

Arguments​

  • key str - Identifier key for the document, mainly for compatibility with ALDocument.
  • refresh bool - For signature compatibility
  • pdfa bool - For signature compatibility
  • append_matching_suffix bool - For signature compatibility

Returns​

  • DAFile - The table rendered as an XLSX spreadsheet

ALUntransformedDocument Objects​

class ALUntransformedDocument(ALDocument)

Represents an untransformed document. The class provides methods to access the document without making any modifications to it. The provided methods are mainly for duck-typing compatibility with ALDocument.

Attributes​

  • has_addendum bool - A flag indicating the presence of an addendum in the document.
  • suffix_to_append str - Suffix that can be appended to file names, defaulting to "preview".

init​

def init(*pargs, **kwargs) -> None

Standard DAObject init method.

Arguments​

  • *pargs - Positional arguments
  • **kwargs - Keyword arguments

has_overflow​

def has_overflow() -> bool

Check for overflow in the document.

For compatibility with ALDocument. Untransformed documents inherently don't have overflow.

Returns​

  • bool - Always False for this implementation.

as_list​

def as_list(key: str = "final",
            refresh: bool = True,
            **kwargs) -> List[DAFile]

Retrieve the document as a list.

Arguments​

  • key str - Identifier key for the document. Default is "final".
  • refresh bool - If True, the document list will be refreshed. Default is True.

Returns​

  • List[DAFile] - A list containing the document.

as_pdf​

def as_pdf(key: str = "final",
           refresh: bool = True,
           pdfa: bool = False,
           append_matching_suffix: bool = True,
           **kwargs) -> DAFile

Fetch the document in its original form, without any transformations.

This method is primarily for duck-typing compatibility with ALDocument.

Arguments​

  • key str - Identifier key for the document. Unused, but included for compatibility.
  • refresh bool - If True, fetches the latest version of the document. Default is True.
  • pdfa bool - Unused argument for compatibility.
  • append_matching_suffix bool - Unused argument for compatibility.

Returns​

  • DAFile - The original, untransformed document.

as_docx​

def as_docx(key: str = "final",
            refresh: bool = True,
            append_matching_suffix: bool = True) -> DAFile

Fetch the document in its original form, without any transformations.

This method is primarily for duck-typing compatibility with ALDocument.

Arguments​

  • key str - Identifier key for the document. Default is "final".
  • refresh bool - If True, fetches the latest version of the document. Default is True.
  • append_matching_suffix bool - Unused argument for compatibility.

Returns​

  • DAFile - The original, untransformed document.

ALDocumentUpload Objects​

class ALDocumentUpload(ALUntransformedDocument)

Simplified class to handle uploaded documents, without any of the complexity of the ALExhibitDocument class.

unpack_dafilelist​

def unpack_dafilelist(the_file: DAFileList) -> DAFile

Creates a plain DAFile out of the first item in a DAFileList

Arguments​

  • the_file DAFileList - an item representing an uploaded document in a Docassemble interview

Returns​

A DAFile representing the first item in the DAFileList, with a fixed instanceName attribute.