acronymmaker

AcronymMaker in Python

Description

AcronymMaker creates awesome acronyms for your projects. Let us briefly describe how it works with some vocabulary.

A token is a set of words from which one word must appear in the acronym built by AcronymMaker. Said differently, there must be a letter in common between a word from the set and the built acronym. This letter may be either the first letter of a word in the token or any letter, depending on the letter selection strategy that is given to AcronymMaker.

Additionally, tokens may be optional. In this case, AcronymMaker will try to match a letter from the words in the optional token to a letter in the acronym, but the acronym will still be accepted if it fails to do so.

To find an acronym for a given sequence of tokens, AcronymMaker uses a dictionary, i.e., a set of known words, in which it looks for acronyms. A word in the dictionary is said to be explained (as an acronym) by the sequence of tokens if there is a letter in the word for each word in each (non-optional) token. In this case, we say that the letter is explained by the corresponding word.

Moreover, there are two ways to explain a word as an acronym: either by following the order of the tokens in the specified sequence, or without considering this order. AcronymMaker supports both of them (independently).

Finally, note that there may be unexplained letters in the acronym. Their number may be limited, by limiting both the number of consecutive unused letters and the number of overall unused letters in a word. If one of these limits is exceeded, then the word will not be considered as explained.

Requirements

This project provides a Python implementation of AcronymMaker, you thus need Python 3 on your computer to run it.

You may install AcronymMaker on your computer along with all its dependencies thanks to pip with the following command line:

python3 -m pip install acronymmaker

How to use AcronymMaker

There are two ways to use the Python implementation of AcronymMaker. This section describes both of them.

Command-Line Interface

AcronymMaker comes with a command-line interface that has the following usage:

acronymmaker [-l {all,first}] [-m {ordered,ordered-greedy,unordered}] [-c <nb>] [-u <nb>] -d <dict> [<dict> ...]

Let us now describe the parameters of the command line above.

• The parameter -l (--select-letters) allows specifying whether only the first letter or all the letters of a word from a token may be used to explain a letter of the acronym.

• The parameter -m (--matching-strategy) allows specifying whether the tokens must be considered ordered or unordered. The strategy ordered-greedy also considers the tokens in order, but using a more efficient algorithm that may however miss matching acronyms which would have been found by the ordered strategy.

• The parameters -c (--max-consecutive-unused) and -u (--max-total-unused) allow specifying the maximum numbers of unused letters in the acronym, by limiting the number of consecutive and overall unexplained letters, respectively.

• The parameter -d (--dictionary) allows specifying the path to the dictionary file(s) from which AcronymMaker will look for acronyms. You may find such dictionaries here. This is the only required parameter.

Once the command-line application has started, a prompt asks you to enter your tokens, separated by blank spaces. Each token defines a set of words separated with slashes (/), and may end with a question mark (?) to specify that the token is optional. When you press Enter, the matching acronyms are displayed in the console. You may then enter new sequences of tokens if you wish to find other acronyms, or you may exit the application with either Ctrl-C or Ctrl-D.

Python API

You may also want to directly interact with the Python API of AcronymMaker. The acronymmaker package provides the function and classes to programmatically set up an instance of AcronymMaker similarly to what is proposed for the command-line interface.

First, there are two functions corresponding to the letter selection strategies. Both of them are in the acronymmaker.selection module.

from acronymmaker.selection import select_all_letters, select_first_letter

There are also three classes corresponding to the matching strategies. They are defined in the acronymmaker.matching module.

from acronymmaker.matching import GreedyOrderedMatchingStrategy
from acronymmaker.matching import RegexBasedOrderedMatchingStrategy
from acronymmaker.matching import UnorderedMatchingStrategy

All these strategies define a constructor that takes as parameters the maximum number of consecutive unused letters and the maximum number of overall unused letters, as this can be seen in the example below.

matching_strategy = UnorderedMatchingStrategy(max_consecutive_unused=3, max_total_unused=5)

It is now possible to instantiate an AcronymMaker to create your acronyms. First, you need to import AcronymMaker.

from acronymmaker.maker import AcronymMaker

Then, you may instantiate an AcronymMaker as follows.

my_acronyms = []
maker = AcronymMaker(select_all_letters, matching_strategy, my_acronyms.append)

The maker initialized above will append to my_acronyms all the acronyms it will identify. You may of course provide any callback function as third parameter to the constructor of AcronymMaker. The only requirement for this function is that it must take as parameter an instance of Acronym (from the acronymmaker.matching module). You can for instance print it, display it on a GUI, etc.

Then, you need to tell to the instance of AcronymMaker what are the words that are authorized as acronyms (a.k.a. the "dictionary"). We provide a set of dictionary as text files, but you can of course use your own set of words.

To add new words, you can either add them one at a time, or all of them at once.

maker.add_known_word('foo')
maker.add_known_words(['bar', 'baz'])

Then, you need to provide the list of the tokens for which to find an acronym. To this end, the TokenBuilder, defined in acronymmaker.token, makes easier the creation of a Token.

builder = TokenBuilder(select_all_letters)
builder.add_word('foo')
builder.add_word('bar')
builder.set_optional(True)
token = builder.build()

Once you have built all your tokens, put them in a list, say tokens. Finally, pass this list as parameter to the find_acronym method of maker. It will try to explain each word of the dictionary, and will invoke the callback function specified when creating the instance of AcronymMaker each time it successfully explains a word with the corresponding Acronym instance.

maker.find_acronyms(tokens)

To deal with the instances of Acronym that are produced by this method and stored in the list my_acronyms (in this example), you may be particularly interested in the following methods:

• get_word() gives the word that is explained as an acronym, with each explained letter upper-cased.

• get_explanations() gives the list of explanations of the acronym, i.e., all the possible combinations of words in the tokens that explain the word as an acronym. Moreover, each letter corresponding to an explained letter of the acronym are upper-cased.