AssemblyLine.al_general

safe_subdivision_type

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

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.
• maxlengths Optional[Dict[str, int]] - A dictionary of field names and their maximum lengths. Defaults to None.

Returns:

List[Dict[str, Any]]: A list of dictionaries 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

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

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

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

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

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

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

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__

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__

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

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

Provide a list of familiar forms of names of individuals.

Arguments:

• **kwargs - Keyword arguments to pass to the familiar method.

Returns:

• str - Formatted string of familiar names.

familiar_or

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

Arguments:

• **kwargs - Keyword arguments to pass to the familiar method.

Returns:

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

short_list

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

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.

pronoun_reflexive

Returns the appropriate reflexive pronoun for the list of people, depending on the person keyword argument and the number of items in the list.

If the list is singular, return the reflexive pronoun for the first item in the list. If it is plural, return the appropriate plural reflexive pronoun (e.g., "themselves")

Arguments:

• **kwargs - Additional keyword arguments that are defined upstream.
  • person (Optional[[Union[str,int]]): Whether to use a first, second, or third person pronoun. Can be one of 1/"1p", 2/"2p", or 3/"3p" (default is 3). See upstream documentation for more information.
  • default (Optional[str]): The default word to use if the pronoun is not defined, e.g. "the agent". If not defined, the default term is the user's name.

Returns:

• str - The reflexive pronoun for the list.

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

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

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

Generates a formatted string of all provided contact methods.

Returns:

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

merge_letters

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

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

Fetches the normalized version of the address.

Returns:

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

name_fields

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.
• maxlengths Dict[str, int], optional - A dictionary of field names and their maximum lengths. 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

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.
• maxlengths Dict[str, int], optional - A dictionary of field names and their maximum lengths. Default is None.

Returns:

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

gender_fields

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.
• maxlengths Dict[str, int], optional - A dictionary of field names and their maximum lengths. Default is None.

Returns:

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

pronoun_fields

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".
• maxlengths Dict[str, int], optional - A dictionary of field names and their maximum lengths. Default is None.

Returns:

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

get_pronouns

Retrieve a set of the individual's pronouns.

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

Can be formatted however the author likes.

Returns:

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

list_pronouns

Retrieve a formatted string of the individual's pronouns, arranged with the comma_list() function.

Returns:

• str - A formatted string of the individual's pronouns.

language_fields

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.
• maxlengths Dict[str, int], optional - A dictionary of field names and their maximum lengths. Default is None.

Returns:

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

language_name

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

Returns True only if the gender is male.

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

gender_female

Returns True only if the gender is female.

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

gender_other

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

Returns True only if the gender is nonbinary.

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

gender_unknown

Returns True only if the gender is unknown.

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

gender_undisclosed

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

Returns True only if the gender is self described.

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

contact_fields

Return field prompts for other contact info

initials

Returns the initials of the individual as a string.

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

address_block

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

Returns an objective pronoun as appropriate, based on the user's pronouns attribute or gender attribute.

The pronoun could be "I", "you," "her," "him," "it," or "them", or a user-provided pronoun. If the user has selected multiple pronouns, each will appear, separated by a "/".

This method will not trigger the definition of gender or pronouns, but it will use them if they are defined, with pronouns taking precedence. As a default, it will either use the value of default or the individual's full name.

Arguments:

• **kwargs - Additional keyword arguments that are defined upstream.
  • person (Optional[[Union[str,int]]): Whether to use a first, second, or third person pronoun. Can be one of 1/"1p", 2/"2p", or 3/"3p" (default is 3). See upstream documentation for more information.
  • default (Optional[str]): The default word to use if the pronoun is not defined, e.g. "the agent". If not defined, the default term is the user's name.

Returns:

• str - The appropriate pronoun.

pronoun_objective

Returns the same pronoun as the pronoun() method.

Arguments:

• **kwargs - Additional keyword arguments.

Returns:

• str - The appropriate objective pronoun.

pronoun_possessive

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

This method will not trigger the definition of gender or pronouns, but it will use them if they are defined, with pronouns taking precedence. As a default, it will either use the value of default or the individual's full name.

Given a target word, the function returns "{pronoun} {target}". The pronoun could be "my", "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 that can be passed to modify the behavior. These might include:
  • default (Optional[str]): The default word to use if the pronoun is not defined, e.g., "the agent". If not defined, the default term is the user's name.
  • person (Optional[Union[str, int]]): Whether to use a first, second, or third person pronoun. Can be one of 1/"1p", 2/"2p", or 3/"3p" (default is 3). See upstream documentation for more information.

Returns:

• str - The appropriate possessive phrase, e.g., "her book", "their document".

pronoun_subjective

Returns a subjective pronoun, based on attributes.

The pronoun could be "you," "we", "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 that are defined upstream.
  • person (Optional[[Union[str,int]]): Whether to use a first, second, or third person pronoun. Can be one of 1/"1p", 2/"2p", or 3/"3p" (default is 3). See upstream documentation for more information.
  • default (Optional[str]): The default word to use if the pronoun is not defined, e.g. "the agent". If not defined, the default term is the user's name.

Returns:

• str - The appropriate subjective pronoun.

pronoun_reflexive

Returns the appropriate reflexive pronoun ("herself", "themself", "myself"), based on the user's pronouns or gender and whether we are asked to return a 1st, 2nd, or 3rd person pronoun.

Note that if the person has pronouns of they/them/theirs or a nonbinary gender, we return "themself" as the singular non-gendered reflexive pronoun and not "themselves". This has growing acceptance although some consider it nonstandard. See: https://www.merriam-webster.com/wordplay/themself

Arguments:

• **kwargs - Additional keyword arguments that are defined upstream.
  • person (Optional[[Union[str,int]]): Whether to use a first, second, or third person pronoun. Can be one of 1/"1p", 2/"2p", or 3/"3p" (default is 3). See upstream documentation for more information.
  • default (Optional[str]): The default word to use if the pronoun is not defined, e.g. "the agent". If not defined, the default term is the user's name.

Returns:

• str - The appropriate reflexive pronoun.

name_full

Returns the individual's full name.

Returns:

• str - The individual's full name.

name_initials

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

Returns the individual's name without any middle name.

Equivalent to self.name.firstlast()

Returns:

• str - The individual'

familiar

Returns the individual's name in the most familiar form possible.

The purpose is to allow using a short version of the individual's name in an unambiguous way in the interview. For example: referring to the child in a guardianship petition by first name instead of "the minor". But there may be a problem if context doesn't make it clear if you are talking about the child or their parent when they share a name.

In order, it will try to use:

• just the first name
• the first name and suffix
• the first and middle name
• the first and last name
• the full name
• the default value, e.g., "the minor", if provided
• the full name

Arguments:

• unique_names Optional[List[Any]] - A list of unique names to compare against. Defaults to None.
• default Optional[str] - The default name to return if no unique name is found. Defaults to None.

Returns:

• str - The individual's name in the most familiar form possible.

Example:

Who do you want to take care of $\{ children.familiar(unique_names=parents + petitioners, default="the minor") \}

section_links

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

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

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

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

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

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

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

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

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

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

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

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