Utilities

Utilities module. Almost all goldfinchsong logic is handled by the functions in this module. It’s the workhorse of the package.

goldfinchsong.utils.access_api(credentials)
Parameters:credentials (dict) – Authentication and access credentials.
Returns:A tweepy API instance.
goldfinchsong.utils.apply_abbreviations(text, abbreviations, maximum_length=117)

Abbreviates words until status text does not exceed the maximum length.

Not all abbreviations are necessarily applied; the function iterates abbreviation-by-abbreviation, checking length after each substitution.

Parameters:
  • text (str) – A tweet’s status text.
  • abbreviations (OrderedDict) – An OrderedDict keyed to a word with its abbreviation as the value.
  • maximum_length (int) – Maximum character length.
Returns:

New status text
Return type:

str
goldfinchsong.utils.apply_vowel_elision(text, maximum_length=117)

Removes a strings non-boundary vowels until it does not exceed the maximum character length.

Parameters:
  • text (str) – A twitter status text.
  • maximum_length (int) – Maximum character length.
Returns:

Status text with whatever vowel elisions were necessary to meet length constraint.
Return type:

str
goldfinchsong.utils.assemble_elided_status(complete_words, elided_words)

Remixes the complete and elided words of a status text to match word original order.

Parameters:
  • complete_words (list) – List of complete words in reverse order from original status text.
  • elided_words (list) – List of elided words in reverse order from original status text.
Returns:

The properly-ordered status.
Return type:

str
goldfinchsong.utils.chop_words(text, maximum_length=117)

Deletes last word in a string until it does not exceed maximum length.

Parameters:
  • text (str) – Status text.
  • maximum_length (int) – Maximum character length.
Returns:

str or None
goldfinchsong.utils.extract_status_text(file_name, text_conversions=None, maximum_length=117)

Provides a tweet’s text status based on a file name.

As part of generating the status, the function transforms underscores _ into blank spaces. Use underscores to create white space in your text status.

An image link consumes 23 characters, leaving 117 for text.

Parameters:
  • file_name (str) – An image file name. For example: selected_image.png.
  • text_conversions (dict) – Keys represent full-length versions of a word. If the string value paired with the key is an abbreviated form that may be used by the function in an attempt to reduce the length of the candidate text.
  • maximum_length (int) – The maximum character length for the text.
Returns:

text – A string of text based on the file name.
Return type:

str
goldfinchsong.utils.get_posted_files(db)

Extracts a set of image file names for persisted tweets.

The application’s expected image file format is an-image-name-without-the-path.png. So, it does not include the path to the image file in the saved string.

Parameters:db – TinyDB instance.
Returns:set
goldfinchsong.utils.get_unused_files(db, available_files)

Determines image files that can be used for new image posts by taking out used images from available images. If all images have been used, the database is purged, allowing for repetition of past images.

The application’s expected image file format for available files is an-image-name-without-the-path.png. It should not include the path to the image file in the saved string.

Parameters:
  • db – TinyDB instance.
  • available_files (list) – All of the existing files in the image directory.
Returns:

list
goldfinchsong.utils.is_image_file(file_name)

Checks for .png, .jpg, .jgpeg, .gif file extensions.

Parameters:file_name (str) – Image file name.
Returns:Returns True if the file name has image extension. False otherwise.
Return type:bool
goldfinchsong.utils.load_content(db, image_directory, text_conversions=None)

Generates content tuple after selecting random image from image directory.

Parameters:
  • db – A TinyDB instance.
  • image_directory (str) – File path to image directory.
  • text_conversions (dict) – Keys represent full-length versions of a word. If the string value paired with the key is an abbreviated form that may be used by the function in an attempt to reduce the length of the candidate text.
Returns:

A content tuple with full image path, status text, and image file, if an image file is available in image directory. None otherwise.
Return type:

tuple or None
goldfinchsong.utils.to_compact_text(candidate_text, maximum_length=117, text_conversions=None)

Transforms a text string so that its length is equal to or less than a designated maximum length.

This is the sequence of transformations deployed:

  • If the text is already equal to or under the maximum, no transformations are applied.
  • Each text conversion is attempted; after each attempt, the length of the resulting text is checked and immediately returned if the transformed text does not exceed the maximum length.
  • Non-boundary (i.e. internal to the word, so not the first or last letter) vowels are removed sequentially from the last word until the first. A length check occurs after each word transformation and the text is immediately returned if does not exceed the maximum.
  • If the text is still too long, then words are deleted from last to first until the resulting text does not exceed the maximum length.
Parameters:
  • candidate_text (str) – Original text before function processing.
  • maximum_length (int) – The maximum character length for the text.
  • text_conversions (dict) – Keys represent full-length versions of a word. The string value paired with the key is an abbreviated form of the keyed word that may be used by the function in an attempt to reduce the length of the candidate text.
Returns:

A text string that shorter than the passed maximum length argument.
Return type:

str
goldfinchsong.utils.trim_file_extension(file_name)

Removes .png, .jpg, .jgpeg, .gif file extensions.

Parameters:file_name (str) – Image file name.
Returns:File name string without the image type extension.
Return type:str