AssemblyLine.al_general

safe_subdivision_type

def safe_subdivision_type(country_code: str) -> Optional[str]

Returns the subdivision type for the country with the given country code. If no subdivision type is found, returns None.

Arguments:

• country_code str - The ISO-3166-1 alpha-2 code for the country.

Returns:

• Optional[str] - The subdivision type for the country with the given country code.

ALAddress Objects

class ALAddress(Address)

This class is used to store addresses. The ALAddress class extends the Address class with the address_fields() method and "smarter" handling of the unit attribute when printing a formatted address.

Attributes:

• address str - The street where the person lives.
• unit str - The unit number where the person lives.
• city str - The city where the person lives.
• state str - The state where the person lives.
• zip str - The zip code where the person lives.
• country str - The country where the person lives.
• impounded Optional[bool] - Whether the address is impounded.

address_fields

def address_fields(
        country_code: Optional[str] = None,
        default_state: Optional[str] = None,
        show_country: bool = False,
        show_county: bool = False,
        show_if: Union[str, Dict[str, str], None] = None,
        allow_no_address: bool = False,
        ask_if_impounded: Optional[bool] = False) -> List[Dict[str, Any]]

Return a YAML structure representing the list of fields for the object's address.

Optionally, allow the user to specify they do not have an address. When using allow_no_address=True, ensure to trigger the question with users[0].address.has_no_address rather than users[0].address.address. If show_if is used, it will not be applied when allow_no_address is also used. Ensure country_code adheres to ISO-3166-1 alpha-2 code standard.

NOTE: This function is stateful under specific conditions. Refer to the conditions mentioned below.

Arguments:

• country_code Optional[str] - ISO-3166-1 alpha-2 code of the country. Defaults to None.
• default_state Optional[str] - Default state to set. Defaults to None.
• show_country bool - Whether to display the country field. Defaults to False.
• show_county bool - Whether to display the county field. Defaults to False.
• show_if Union[str, Dict[str, str], None] - Condition to display each field. Defaults to None.
• allow_no_address bool - Allow users to specify they don't have an address. Defaults to False.
• ask_if_impounded Optional[bool] - Whether to ask if the address is impounded. Defaults to False.

Returns:

• list - A list of YAML structure representing address fields.

Notes:

• The function will set the country attribute of the Address to country_code under these circumstances:

1. The country_code parameter is used.
2. The show_country parameter is not used.
3. country_code differs from the value returned by get_country().

• Link to ISO-3166-1 alpha-2 codes: Officially assigned code elements.

formatted_unit

def formatted_unit(language: Optional[str] = None,
                   require: bool = False,
                   bare: bool = False) -> str

Returns the unit, formatted appropriately.

Arguments:

• language str, optional - The language in which to format the unit. Defaults to None (which uses system language).
• require bool, optional - A flag indicating whether the unit is required. If set to True, the function will raise an error if the unit attribute does not exist. Defaults to False.
• bare bool, optional - A flag indicating whether to add the word 'Unit' before the unit number. If set to True, the function will not add 'Unit' regardless of other conditions. Defaults to False.

Returns:

• str - The formatted unit. If the unit attribute does not exist and require is set to False, this will be an empty string. If the unit attribute exists and is not None or an empty string, the function will return the unit number, possibly prefixed with 'Unit'. If the unit attribute exists and is None or an empty string, the function will return an empty string.

block

def block(language: Optional[str] = None,
          international: bool = False,
          show_country: Optional[bool] = None,
          bare: bool = False,
          long_state: bool = False,
          show_impounded: bool = False) -> str

Returns a one-line formatted address, primarily for geocoding.

Arguments:

• language str, optional - Language for the address format.
• international bool - If True, formats the address as an international address. Defaults to False.
• show_country bool, optional - If True, includes the country in the formatted address. If None, decides based on the country attribute.
• bare bool - If True, excludes certain formatting elements. Defaults to False.
• long_state bool - If True, uses the full state name. Defaults to False.
• show_impounded bool - If True, shows the address even if impounded. Defaults to False.

Returns:

• str - The one-line formatted address.

line_one

def line_one(language: Optional[str] = None,
             bare: bool = False,
             show_impounded: bool = False) -> str

Returns the first line of the address, including the unit number if it exists.

Arguments:

• language str, optional - Language for the address format.
• bare bool - If True, excludes certain formatting elements. Defaults to False.
• show_impounded bool - If True, shows the address even if impounded. Defaults to False.

Returns:

• str - The first line of the address.

line_two

def line_two(language: Optional[str] = None,
             long_state: bool = False,
             show_impounded: bool = False) -> str

Returns the second line of the address, including city, state, and postal code.

Arguments:

• language str, optional - Language for the address format.
• long_state bool - If True, uses the full state name. Defaults to False.
• show_impounded bool - If True, shows the address even if impounded. Defaults to False.

Returns:

• str - The second line of the address.

on_one_line

def on_one_line(include_unit: bool = True,
                omit_default_country: bool = True,
                language: Optional[str] = None,
                show_country: Optional[bool] = None,
                bare: bool = False,
                long_state: bool = False,
                show_impounded: bool = False) -> str

Returns a one-line formatted address.

Arguments:

• include_unit bool - If True, includes the unit in the formatted address. Defaults to True.
• omit_default_country bool - If True, doesn't show the Docassemble default country in the formatted address. Defaults to True.
• language str, optional - Language for the address format.
• show_country bool, optional - If True, includes the country in the formatted address. If None, decides based on the country attribute.
• bare bool - If True, excludes certain formatting elements. Defaults to False.
• long_state bool - If True, uses the full state name. Defaults to False.
• show_impounded bool - If True, shows the address even if impounded. Defaults to False.

Returns:

• str - The one-line formatted address.

normalized_address

def normalized_address() -> Union[Address, "ALAddress"]

Try geocoding the address, returning the normalized version if successful.

If geocoding is successful, the method returns the "long" normalized version of the address. All methods, such as my_address.normalized_address().block(), are still available on the returned object. However, note that the returned object will be a standard Address object, not an ALAddress object. If geocoding fails, it returns the version of the address as entered by the user.

Warning: currently the normalized address will not be redacted if the address is impounded.

Returns:

Union[Address, "ALAddress"]: Normalized address if geocoding is successful, otherwise the original address.

state_name

def state_name(country_code: Optional[str] = None) -> str

Returns the full state name based on the state abbreviation.

If a country_code is provided, it will override the country attribute of the Address object. Otherwise, the method uses, in order:

1. The country code associated with the Address object, and then
2. The country set in the global config for the server.

Arguments:

• country_code str, optional - ISO-3166-1 alpha-2 code to override the country attribute of the Address object. For valid codes, refer to: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements

Returns:

• str - The full state name corresponding to the state abbreviation. If an error occurs or the full name cannot be determined, returns the state abbreviation.

ALAddressList Objects

class ALAddressList(DAList)

A class to store a list of ALAddress objects.

Extends the DAList class and specifically caters to ALAddress objects. It provides methods to initialize the list and get a string representation of the list in a formatted manner.

__str__

def __str__() -> str

Provide a string representation of the ALAddressList.

This method returns the addresses in the list formatted in a comma-separated manner using the on_one_line method of ALAddress.

Returns:

• str - Formatted string of all addresses in the list.

ALNameList Objects

class ALNameList(DAList)

A class to store a list of IndividualName objects.

Extends the DAList class and is tailored for IndividualName objects.

__str__

def __str__() -> str

Provide a string representation of the ALNameList.

Returns:

• str - Formatted string of all names in the list.

ALPeopleList Objects

class ALPeopleList(DAList)

Class to store a list of ALIndividual objects, representing people.

For example, defendants, plaintiffs, or children.

names_and_addresses_on_one_line

def names_and_addresses_on_one_line(comma_string: str = "; ",
                                    bare=False) -> str

Provide names and addresses of individuals on one line.

Arguments:

• comma_string str, optional - The string to use between name-address pairs. Defaults to '; '.
• bare bool, optional - If True, prevents appending the word "Unit" to the unit attribute. Defaults to False.

Returns:

• str - Formatted string of names followed by addresses.

familiar

def familiar() -> str

Provide a list of familiar forms of names of individuals.

Returns:

• str - Formatted string of familiar names.

familiar_or

def familiar_or() -> str

Provide a list of familiar forms of names of individuals separated by 'or'.

Returns:

• str - Formatted string of familiar names separated by 'or'.

short_list

def short_list(limit: int, truncate_string: str = ", et. al.") -> str

Return a subset of the list, truncated with 'et. al.' if it exceeds a given limit.

Arguments:

• limit int - The maximum number of items to display before truncating.
• truncate_string str, optional - The string to append when truncating. Defaults to ', et. al.'.

Returns:

• str - Formatted string of names, truncated if needed.

full_names

def full_names(comma_string=", ", and_string=word("and")) -> str

Return a formatted list of full names of individuals.

Arguments:

• comma_string str, optional - The string to use between names. Defaults to ','.
• and_string str, optional - The string to use before the last name in the list. Defaults to 'and'.

Returns:

• str - Formatted string of full names.

ALIndividual Objects

class ALIndividual(Individual)

Used to represent an Individual on the assembly line project.

This class extends the Individual class and adds more tailored attributes and methods relevant for the assembly line project. Specifically, it has attributes for previous addresses, other addresses, mailing addresses, previous names, aliases, and a preferred name.

Attributes:

• previous_addresses ALAddressList - List of previous addresses.
• other_addresses ALAddressList - List of other addresses.
• mailing_address ALAddress - Current mailing address.
• service_address ALAddress - Service address.
• previous_names ALNameList - List of previous names.
• aliases ALNameList - List of aliases.
• preferred_name IndividualName - The preferred name.

Notes:

Objects as attributes should not be passed directly to the constructor due to initialization requirements in the Docassemble framework. See the init method.

signature_if_final

def signature_if_final(i: str) -> Union[DAFile, str]

Returns the individual's signature if i is "final", which usually means we are assembling the final version of the document (as opposed to a preview).

Arguments:

• i str - The condition which, if set to "final", returns the signature.

Returns:

Union[DAFile, str]: The signature if the condition is met, otherwise an empty string.

phone_numbers

def phone_numbers(country: Optional[str] = None,
                  show_impounded: bool = False) -> str

Fetches and formats the phone numbers of the individual.

Arguments:

• country str, optional - The country for phone number formatting. Defaults to the country of the docassemble server.
• show_impounded bool - If True, shows the phone numbers even if impounded. Defaults to False.

Returns:

• str - Formatted string of phone numbers.

contact_methods

def contact_methods() -> str

Generates a formatted string of all provided contact methods.

Returns:

• str - A formatted string indicating the available methods to contact the individual.

merge_letters

def merge_letters(new_letters: str) -> None

If the Individual has a child_letters attribute, add the new letters to the existing list

Avoid using. Only used in 209A.

Arguments:

• new_letters str - The new letters to add to the existing list of letters

formatted_age

def formatted_age() -> str

Calculates and formats the age of the individual based on their birthdate.

Returns:

• str - Formatted age string that shows the most relevant time unit; for example, if under 2 years, it will return "X months".

normalized_address

def normalized_address() -> Union[Address, ALAddress]

Fetches the normalized version of the address.

Returns:

Union[Address, ALAddress]: The normalized address object.

name_fields

def name_fields(
        person_or_business: str = "person",
        show_suffix: bool = True,
        show_title: bool = False,
        title_options: Optional[List[str]] = None,
        show_if: Union[str, Dict[str, str],
                       None] = None) -> List[Dict[str, str]]

Generates suitable field prompts for a name based on the type of entity (person or business) and other provided parameters.

Arguments:

• person_or_business str, optional - Specifies the entity type. It can either be "person" or "business". Default is "person".
• show_suffix bool, optional - Determines if the name's suffix (e.g., Jr., Sr.) should be included in the prompts. Default is True.
• show_title - (bool, optional): Determines if the name's title (e.g., Mr., Ms.) should be included in the prompts. Default is False.
• title_options List[str], optional - A list of title options to use in the prompts. Default is defined as a list of common titles in English-speaking countries.
• show_if Union[str, Dict[str, str], None], optional - Condition to determine which fields to show. It can be a string, a dictionary with conditions, or None. Default is None.

Returns:

List[Dict[str, str]]: A list of dictionaries where each dictionary contains field prompt details.

Notes:

If person_or_business is set to None, the method will offer the end user a choice and will set appropriate "show ifs" conditions for each type.

address_fields

def address_fields(country_code: str = "US",
                   default_state: Optional[str] = None,
                   show_country: bool = False,
                   show_county: bool = False,
                   show_if: Union[str, Dict[str, str], None] = None,
                   allow_no_address: bool = False,
                   ask_if_impounded: bool = False) -> List[Dict[str, str]]

Generate field prompts for capturing an address.

Arguments:

• country_code str - The default country for the address. Defaults to "US".
• default_state Optional[str] - Default state if applicable. Defaults to None.
• show_country bool - Whether to display the country field. Defaults to False.
• show_county bool - Whether to display the county field. Defaults to False.
• show_if Union[str, Dict[str, str], None] - Condition to determine if the field should be shown. Defaults to None.
• allow_no_address bool - Whether to permit entries with no address. Defaults to False.
• ask_if_impounded bool - Whether to ask if the address is impounded. Defaults to False.

Returns:

List[Dict[str, str]]: A list of dictionaries with field prompts for addresses.

gender_fields

def gender_fields(
        show_help=False,
        show_if: Union[str, Dict[str, str],
                       None] = None) -> List[Dict[str, str]]

Generate fields for capturing gender information, including a self-described option.

Arguments:

• show_help bool - Whether to show additional help text. Defaults to False.
• show_if Union[str, Dict[str, str], None] - Condition to determine if the field should be shown. Defaults to None.

Returns:

List[Dict[str, str]]: A list of dictionaries with field prompts for gender.

pronoun_fields

def pronoun_fields(
    show_help=False,
    show_if: Union[str, Dict[str, str], None] = None,
    required: bool = False,
    shuffle: bool = False,
    show_unknown: Optional[Union[Literal["guess"], bool]] = "guess"
) -> List[Dict[str, str]]

Generate fields for capturing pronoun information.

Arguments:

• show_help bool - Whether to show additional help text. Defaults to False.
• show_if Union[str, Dict[str, str], None] - Condition to determine if the field should be shown. Defaults to None.
• required bool - Whether the field is required. Defaults to False.
• shuffle bool - Whether to shuffle the order of pronouns. Defaults to False.
• show_unknown Union[Literal["guess"], bool] - Whether to show an "unknown" option. Can be "guess", True, or False. Defaults to "guess".

Returns:

List[Dict[str, str]]: A list of dictionaries with field prompts for pronouns.

get_pronouns

def get_pronouns() -> set

Retrieve a set of the individual's pronouns.

If the individual has selected the "self-described" option, it will use their custom input.

Returns:

• set - A set of strings representing the individual's pronouns.

language_fields

def language_fields(
        choices: Optional[List[Dict[str, str]]] = None,
        style: str = "radio",
        show_if: Union[str, Dict[str, str],
                       None] = None) -> List[Dict[str, str]]

Generate fields for capturing language preferences.

Arguments:

• choices Optional[List[Dict[str, str]]] - A list of language choices. Defaults to None.
• style str - The display style of choices. Defaults to "radio".
• show_if Union[str, Dict[str, str], None] - Condition to determine if the field should be shown. Defaults to None.

Returns:

List[Dict[str, str]]: A list of dictionaries with field prompts for language preferences.

language_name

def language_name() -> str

Get the human-readable version of the individual's selected language.

Returns:

• str - The human-readable version of the language. If 'other' is selected, it returns the value in language_other. Otherwise, it uses the language_name function.

gender_male

@property
def gender_male() -> bool

Returns True only if the gender is male.

Used to assist with checkbox filling in PDFs with "skip undefined" turned on.

gender_female

@property
def gender_female() -> bool

Returns True only if the gender is female.

Used to assist with checkbox filling in PDFs with "skip undefined" turned on.

gender_other

@property
def gender_other() -> bool

Returns True only if the gender is not male or female.

Used to assist with checkbox filling in PDFs with "skip undefined" turned on.

gender_nonbinary

@property
def gender_nonbinary() -> bool

Returns True only if the gender is nonbinary.

Used to assist with checkbox filling in PDFs with "skip undefined" turned on.

gender_unknown

@property
def gender_unknown() -> bool

Returns True only if the gender is unknown.

Used to assist with checkbox filling in PDFs with "skip undefined" turned on.

gender_undisclosed

@property
def gender_undisclosed() -> bool

Returns True only if the gender is not disclosed ("prefer-not-to-say")

Used to assist with checkbox filling in PDFs with "skip undefined" turned on.

gender_self_described

@property
def gender_self_described() -> bool

Returns True only if the gender is self described.

Used to assist with checkbox filling in PDFs with "skip undefined" turned on.

contact_fields

def contact_fields() -> None

Return field prompts for other contact info

initials

@property
def initials() -> str

Returns the initials of the individual as a string.

For example, "Quinten K Steenhuis" would return "QKS".

address_block

def address_block(language=None,
                  international=False,
                  show_country=False,
                  bare=False,
                  show_impounded=False) -> str

Generate a formatted address block for mailings.

Arguments:

• language Optional - The language in which the address is written.
• international bool - If True, format for international mailing. Defaults to False.
• show_country bool - If True, include the country in the address. Defaults to False.
• bare bool - If True, produce the address without additional formatting. Defaults to False.
• show_impounded bool - If True, show the address even if it is impounded. Defaults to False.

Returns:

• str - The formatted address block.

pronoun

def pronoun(**kwargs) -> str

Returns an objective pronoun as appropriate, based on attributes.

The pronoun could be "you," "her," "him," "it," or "them". It depends on the gender and person_type attributes and whether the individual is the current user.

If the user selected specific pronouns, they take priority over gender (only if they chose a pronoun from the list)

Arguments:

• **kwargs - Additional keyword arguments.

Returns:

• str - The appropriate pronoun.

pronoun_objective

def pronoun_objective(**kwargs) -> str

Returns the same pronoun as the pronoun() method.

Arguments:

• **kwargs - Additional keyword arguments.

Returns:

• str - The appropriate objective pronoun.

pronoun_possessive

def pronoun_possessive(target, **kwargs) -> str

Returns a possessive pronoun and a target word, based on attributes.

Given a target word, the function returns "{pronoun} {target}". The pronoun could be "her," "his," "its," or "their". It depends on the gender and person_type attributes and whether the individual is the current user.

Arguments:

• target str - The target word to follow the pronoun.
• **kwargs - Additional keyword arguments.

Returns:

• str - The appropriate possessive phrase.

pronoun_subjective

def pronoun_subjective(**kwargs) -> str

Returns a subjective pronoun, based on attributes.

The pronoun could be "you," "she," "he," "it," or "they". It depends on the gender and person_type attributes and whether the individual is the current user.

Arguments:

• **kwargs - Additional keyword arguments.

Returns:

• str - The appropriate subjective pronoun.

name_full

def name_full() -> str

Returns the individual's full name.

Returns:

• str - The individual's full name.

name_initials

def name_initials() -> str

Returns the individual's name with the middle name as an initial. Equivalent to name.full(middle="initial"), which is also the default. Defined only to make it possible to be explicit about the name form.

Returns:

• str - The individual's name with the middle name as an initial.

name_short

def name_short() -> str

Returns the individual's name without any middle name.

Equivalent to self.name.firstlast()

Returns:

• str - The individual'

section_links

def section_links(nav) -> List[str]

Returns a list of clickable navigation links without animation.

Arguments:

• nav - The navigation object.

Returns:

• List[str] - A list of clickable navigation links without animation.

will_send_to_real_court

def will_send_to_real_court() -> bool

For legacy email to court forms, this checks to see if the form is being run on the dev, test, or production server.

The text "dev" or "test" needs to be in the URL root in the DA config: can change in /config.

Returns:

• bool - True if the form is being run on the dev, test, or production server.

filter_letters

def filter_letters(letter_strings: Union[List[str], str]) -> str

Used to take a list of letters like ["A","ABC","AB"] and filter out any duplicate letters.

Avoid using, this is created for 209A.

Arguments:

• letter_strings Union[List[str], str] - A list of letters.

Returns:

• str - A string of unique letters.

fa_icon

def fa_icon(icon: str,
            color: str = "primary",
            color_css: Optional[str] = None,
            size: str = "sm") -> str

Return HTML for a font-awesome icon of the specified size and color. You can reference a CSS variable (such as Bootstrap theme color) or a true CSS color reference, such as 'blue' or 'DDDDDD'. Defaults to Bootstrap theme color "primary".

Arguments:

• icon str - The name of the icon to use. See https://fontawesome.com/icons for a list of icons.
• color str - The color of the icon. Defaults to "primary".
• color_css Optional[str] - A CSS variable or color reference. Defaults to None.
• size str - The size of the icon. Defaults to "sm".

Returns:

• str - HTML for the icon.

is_sms_enabled

def is_sms_enabled() -> bool

Checks if SMS (Twilio) is enabled on the server. Does not verify that it works.

See https://docassemble.org/docs/config.html#twilio for more info.

Returns:

• bool - True if there is a non-empty Twilio config on the server, False otherwise

is_phone_or_email

def is_phone_or_email(text: str) -> bool

Returns True if the string is either a valid phone number or a valid email address. If SMS is not enabled on the server (through the Twilio config), only accepts emails. Email validation is extremely minimal--just checks for an @ sign between two non-zero length strings.

Arguments:

• text str - The string to check.

Returns:

• bool - True if the string is either a valid phone number or a valid email address.

Raises:

DAValidationError if the string is neither a valid phone number nor a valid email address.

github_modified_date

def github_modified_date(github_user: str,
                         github_repo_name: str,
                         auth=None) -> Union[DADateTime, None]

Returns the date that the given GitHub repository was modified or None if API call fails.

Will check for the presence of credentials in the configuration labeled "github issues" in this format:

github issues: username: YOUR_GITHUB_USERNAME token: YOUR_GITHUB_PRIVATE_TOKEN

If those credentials aren't found, it will then search for credentials in this format (deprecated):

github readonly: username: YOUR_GITHUB_USERNAME password: YOUR_GITHUB_PRIVATE_TOKEN type: basic

If no valid auth information is in the configuration, it will fall back to anonymous authentication. The GitHub API is rate-limited to 60 anonymous API queries/hour.

Arguments:

• github_user str - The GitHub username of the repository owner.
• github_repo_name str - The name of the repository.
• auth Optional[dict] - A dictionary containing authentication information. Defaults to None.

Returns:

Union[DADateTime, None]: The date that the given GitHub repository was modified or None if API call fails.

language_name

def language_name(language_code: str) -> str

Given a 2 digit language code abbreviation, returns the full name of the language. The language name will be passed through the word() function.

Arguments:

• language_code str - A 2 digit language code abbreviation.

Returns:

• str - The full name of the language.

safe_states_list

def safe_states_list(country_code: str) -> List[Dict[str, str]]

Wrapper around states_list that doesn't error if passed an invalid country_code (e.g., a country name spelled out)

Arguments:

• country_code str - A 2 digit country code abbreviation.

Returns:

List[Dict[str, str]]: A list of dictionaries with field prompts for states.

has_parsable_pronouns

def has_parsable_pronouns(pronouns: str) -> bool

Returns True if the pronouns string can be parsed into a dictionary of pronouns.

Arguments:

• pronouns - a string of pronouns in the format "objective/subjective/possessive"

Returns:

True if the pronouns string can be parsed into a dictionary of pronouns, False otherwise

parse_custom_pronouns

def parse_custom_pronouns(pronouns: str) -> Dict[str, str]

Parses a custom pronoun string into a dictionary of pronouns.

Arguments:

• pronouns - a string of pronouns in the format "objective/subjective/possessive"

Returns:

a dictionary of pronouns in the format {"o": objective, "s": subjective, "p": possessive}

get_visible_al_nav_items

def get_visible_al_nav_items(
        nav_items: List[Union[str, dict]]) -> List[Union[str, dict]]

Processes a list of nav items and returns only the ones that are not hidden. Can be used to control the visible nav items in a more declarative way while keeping the navigation dynamic.

Expects a list like this:

data = [ {"key": "value", "hidden": True}, "top level item", {"key2": [{"subkey": "subvalue", "hidden": False}, {"subkey": "subvalue2", "hidden": True}]}, ]

Arguments:

• nav_items - a list of nav items

Returns:

a list of nav items with hidden items removed