Skip to main content

AssemblyLine.al_general

deepcopy​

Callable​

Dict​

List​

Literal​

Union​

Optional​

Any​

Address​

as_datetime​

capitalize​

comma_and_list​

comma_list​

country_name​

DADateTime​

DADict​

DAFile​

DAList​

date_difference​

DAWeb​

ensure_definition​

get_config​

get_country​

her​

his​

Individual​

IndividualName​

its​

phone_number_formatted​

phone_number_is_valid​

showifdef​

state_name​

states_list​

subdivision_type​

their​

url_action​

validation_error​

word​

your​

log​

value​

functions​

random​

re​

pycountry​

__all__​

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.

Example​

The value of address_region_label for a US address:

Input (interview YAML)

code: |
  address_region_label = safe_subdivision_type("US")

Output

State

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.

Example​

With assembly_line.yml included, users is an ALPeopleList, users[0] is an ALIndividual, and users[0].address is an ALAddress. For a custom list, declare it with an objects block as shown below. Use these question blocks in your interview flow:

objects:
  - users: ALPeopleList
question: |
  Where do you live?
fields:
  - code: users[0].address.address_fields()
question: |
  What is your name?
fields:
  - code: users[0].name_fields()
question: |
  Check your information
subquestion: |
  ${ users[0].familiar() } lives at ${ users[0].address.on_one_line() }.

init​

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

Standard DAObject init method.

Arguments​

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

Example​

Docassemble calls init() automatically during object creation. See the class example for the rest of the setup.

objects:
  - users: ALPeopleList

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.

Example​

In question or Markdown attachment text (Mako):

${ users.names_and_addresses_on_one_line() }

In a DOCX template (Jinja2):

{{ users.names_and_addresses_on_one_line() }}

familiar​

def familiar(unique_names: Optional[list] = None,
             default: Optional[str] = None) -> str

Provide a list of familiar forms of names of individuals, in the most familiar way possible while preserving uniqueness. When possible, it will return just the first name of each individual.

See ALIndividual.familiar for how the familiar form of each individual is determined.

Arguments​

  • unique_names list - A list of unique names to check input against.
  • default str - The default name to use if a unique name is not available.

Returns​

  • str - Formatted string of familiar names.

Example​

With a gathered users list containing Alex Morgan Rivera, Jordan Chen, and Taylor Brooks, in that order, with no suffixes or preferred names, and the interview language set to English:

Input (Mako)

${ users.familiar() }

Input (Jinja2)

{{ users.familiar() }}

Output

Alex, Jordan, and Taylor

familiar_or​

def familiar_or(unique_names: Optional[list] = None,
                default: Optional[str] = None) -> str

Provide a list of familiar forms of names of individuals separated by 'or', using the most familiar form possible while preserving uniqueness. When possible, it will return just the first name of each individual.

See ALIndividual.familiar for how the familiar form of each individual is determined.

Arguments​

  • unique_names list - A list of unique names to check input against.
  • default str - The default name to use if a unique name is not available.

Returns​

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

Example​

With a gathered users list containing Alex Morgan Rivera, Jordan Chen, and Taylor Brooks, in that order, with no suffixes or preferred names, and the interview language set to English:

Input (Mako)

${ users.familiar_or() }

Input (Jinja2)

{{ users.familiar_or() }}

Output

Alex, Jordan, or Taylor

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.

Example​

With a gathered users list containing Alex Morgan Rivera, Jordan Chen, and Taylor Brooks, in that order, with no suffixes or preferred names, and the interview language set to English:

Input (Mako)

${ users.short_list(limit=2) }

Input (Jinja2)

{{ users.short_list(limit=2) }}

Output

Alex M. Rivera and Jordan Chen, et al.

full_names​

def full_names(comma_string: str = ", ",
               and_string: Optional[str] = None) -> 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.

Example​

With a gathered users list containing Alex Morgan Rivera, Jordan Chen, and Taylor Brooks, in that order, with no suffixes or preferred names, and the interview language set to English:

Input (Mako)

${ users.full_names() }

Input (Jinja2)

{{ users.full_names() }}

Output

Alex Morgan Rivera, Jordan Chen, and Taylor Brooks

pronoun_reflexive​

def pronoun_reflexive(**kwargs) -> str

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.

Example​

With a gathered users list containing Alex Morgan Rivera, Jordan Chen, and Taylor Brooks, in that order, with no suffixes or preferred names, and the interview language set to English:

Input (Mako)

${ users.pronoun_reflexive(person=3) }

Input (Jinja2)

{{ users.pronoun_reflexive(person=3) }}

Output

themselves

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.

Example​

With assembly_line.yml included, users is an ALPeopleList, users[0] is an ALIndividual, and users[0].address is an ALAddress. For a custom list, declare it with an objects block as shown below. Use these question blocks in your interview flow:

objects:
  - users: ALPeopleList
question: |
  Where do you live?
fields:
  - code: users[0].address.address_fields()
question: |
  Check the name
subquestion: |
  ${ landlords[0].name_full() }

Tenant Objects​

class Tenant(ALIndividual)

Tenant is a compatibility or role-specific subclass of ALIndividual.

Example​

This ALIndividual subclass uses the same name and address methods. After gathering the list entry:

objects:
  - tenants: DAList.using(object_type=Tenant)
question: |
  Check the name
subquestion: |
  ${ housing_authorities[0].name_full() }

Applicant Objects​

class Applicant(Tenant)

Applicant is a compatibility or role-specific subclass of Tenant.

Example​

This ALIndividual subclass uses the same name and address methods. After gathering the list entry:

objects:
  - applicants: DAList.using(object_type=Applicant)
question: |
  Check the name
subquestion: |
  ${ other_parties[0].name_full() }

Survivor Objects​

class Survivor(ALIndividual)

Survivor is a compatibility or role-specific subclass of ALIndividual.

Example​

This ALIndividual subclass uses the same name and address methods. After gathering the list entry:

objects:
  - survivors: ALPeopleList.using(object_type=Survivor)
question: |
  Check the name
subquestion: |
  ${ victims[0].name_full() }

AddressList Objects​

class AddressList(ALAddressList)

AddressList is a compatibility or role-specific subclass of ALAddressList.

Example​

Compatibility name for ALAddressList. Prefer ALAddressList in new interviews.

objects:
  - previous_addresses: AddressList

PeopleList Objects​

class PeopleList(ALPeopleList)

PeopleList is a compatibility or role-specific subclass of ALPeopleList.

Example​

Compatibility name for ALPeopleList. Prefer ALPeopleList in new interviews.

objects:
  - users: PeopleList

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.

Example​

In an interview code block:

code: |
  send_to_court = will_send_to_real_court()

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.

Example​

Import filter_letters explicitly from docassemble.AssemblyLine.al_general before using this example. In an interview code block:

code: |
  selected_letters = filter_letters(["ab", "bc"])

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.

Example​

In an interview code block:

code: |
  offer_text_message = is_sms_enabled()

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.

Example​

The value of valid_contact for an email address:

Input (interview YAML)

code: |
  valid_contact = is_phone_or_email("alex@example.com")

Output

True

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.

Example​

In an interview code block:

code: |
  last_updated = github_modified_date("SuffolkLITLab", "docassemble-AssemblyLine")

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.

Example​

With users[0].language = "es":

Input (Mako)

${ language_name(users[0].language) }

Input (Jinja2)

{{ language_name(users[0].language) }}

Output

Spanish

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.

Example​

Import safe_states_list explicitly from docassemble.AssemblyLine.al_general before using this example. In an interview code block:

code: |
  state_choices = safe_states_list("US")

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

Example​

The value of valid_pronouns for a custom pronoun string:

Input (interview YAML)

code: |
  valid_pronouns = has_parsable_pronouns("them/they/their")

Output

True

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

Example​

The value of pronoun_parts uses objective, subjective, and possessive pronouns in that order:

Input (interview YAML)

code: |
  pronoun_parts = parse_custom_pronouns("them/they/their")

Output

{'o': 'them', 's': 'they', 'p': 'their'}

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

Example​

Build navigation sections from interview answers in a code block:

code: |
  al_nav_sections = [
      {"about_you": "About you"},
      {"about_children": "Children", "hidden": not has_children},
      {"review": "Review your answers"},
  ]
  nav.set_sections(get_visible_al_nav_items(al_nav_sections))