Helpers Module

class plurals.helpers.SmartString(content)

Bases: str

A custom string class with several nice features for this package.

Features

1. Safe String Formatting

Overrides the format method to use safe_substitute from string.Template.

Problem it fixes:

Users often have JSON-like strings in their tasks, which can cause errors with normal string formatting.

Explanation:

Python’s standard string formatting uses curly braces, which can break when the string contains curly braces NOT meant for replacement. SmartString uses string.Template.safe_substitute() to safely replace variables, avoiding these problems.

2. Avoid Double Periods

Prevents double periods at the end of formatted strings.

Problem it fixes:

When a replacement value ends with a period and the original string also ends with a period, it results in an undesired double period.

Example

>>> task = SmartString("Complete the following task: {task}.")
>>> task.format(task="Do the thing.")
'Complete the following task: Do the thing.'

Without this feature, the output would be: ‘Complete the following task: Do the thing..’

3. None Replacement

Replaces ‘None’ with an empty string during string creation.

Problem it fixes:

str(None) returns the string ‘None’, but for the Agent.process function, it’s preferable to replace ‘None’ with an empty string.

Example

>>> SmartString(None)
''
>>> str(None)
'None'

Notes

• The format method uses string.Template.safe_substitute() internally.

• Double periods are automatically avoided unless specified otherwise.

• ‘None’ is replaced with an empty string during string creation.

format(avoid_double_period=True, **kwargs)

Override the format method to use string.Template for string formatting.

Also, if avoid_double_period is True, then we will remove the trailing period from the formatted string if it is already present. This happens if the string is like Complete the following task: {task}. and the user passes task=Do the thing. In this case, the default output would have an extra period: Complete the following task: Do the thing..

Double-period algorithm:

Foreach key, value in kwargs:

1. Construct a placeholder-plus-period like “{task}.” (assuming {task} is placeholder here)

2. Check if the placeholder-plus-period is in the string AND the replacement ends with a period.

3. If both conditions are met, replace the replacement-plus-period with just the replacement.

Parameters:

• avoid_double_period (bool) – Whether to avoid double periods in the final string. (Default: True)

• **kwargs – Key-value pairs to replace in the string.

Returns:

The formatted string.

Return type:

str

Notes

• In edge case where the value for a key is None, we replace it with an empty string. Example of this:

>>> task = SmartString("Complete the following task: {task}.")
>>> task.format(task=None)
'Complete the following task: .'

plurals.helpers.format_previous_responses(responses: List[str]) → str

Format the previous responses for inclusion in the next task description.

Parameters:

responses (List[str]) – A list of previous responses.

Returns:

A formatted string of the previous responses.

Return type:

str

Example

>>> responses = ["First response", "Second response"]
>>> format_previous_responses(responses)
'Response 0: First response\nResponse 1: Second response'

plurals.helpers.load_yaml(file_path: str) → Dict[str, Any]

Load a YAML file and return its content as a dictionary. We first get the directory of the current path and then construct the full path by combining the base_path with the file_path. Hence, the file_path should be relative to this script’s location.

Parameters:

file_path – The path to the YAML file to load.

Returns:

A dictionary containing the contents of the YAML file.

plurals.helpers.print_anes_mapping()

Prints the values of ANES mapping in a human-readable format.

The purpose of this function is that in some cases users will want to conduct their own query on the ANES dataset, but it is difficult to know what the values are without consulting a codebook.

Note that when generating personas we recode certain values but you should use original values for filtering data, as they are printed here.

Here are the cases we recode values:

• child18 asks participants if they have children under 18 living in their household. We recode Yes to do have children under 18 living in your household and No to do not have children under 18 living in your household.

• Several questions have multiple choice options (A, B, C) and then an Other option. We recode Other as neither A nor B nor C to be more explicit.

plurals.helpers.strip_nested_dict(d: Dict[str, Any]) → Dict[str, Any]

Strip whitespace from all strings in a nested dictionary.

Parameters:

d – The dictionary to strip whitespace from.

Returns:

The dictionary with all strings stripped of whitespace.