1.1 Installation

The simplest way to install is using pip

pip install contactList

1.2 Getting Started

The structure of YAML file is very simple. Organise email addresses into arbitrarily named groups and then organise those groups into arbitrarily named “clusters”.

groups:
  g1:
    - 'u1@some.domain'

  g2:
    - 'u3@some.other.domain'

  g3:
    - 'u4@this.domain'
    - 'u2@some.domain'

clusters:
  c1: [ 'g1' ]

  c2: [ 'g1', 'g2' ]

  c3: [ 'g2', 'g3' ]

There is no requirement restricting an email address to only one group.

1.3 contact-list utility

Once the wheel package is installed the command line utility contact-list is available. This utility can be used to manage contact list data in a YAML file from the command line.

> contact-list --help
usage: contact-list [-h] [--file CONTACTSFILE] {cluster,email,group} ...

positional arguments:
  {cluster,email,group}

optional arguments:
  -h, --help            show this help message and exit
  --file CONTACTSFILE, -f CONTACTSFILE
                        Contacts file to manage (default contacts.yml)

Subcommands enable the modification of the respective entities in the file, cluster, email, group.

1.4 Using the framework

Using the contactList framework, your application can then use the clusters to build a list of the necessary emails. By default, the from_yamlFile classmethod tries to load YAML from contacts.yml in the current directory, otherwise the user specifies the file name to use.

from contactList import Contacts

myContacts = Contacts.from_yamlFile()

# A list of the groups loaded from YAML
assert isinstance( myContacts.groups, list )
# A list of the clusters loaded from YAML
assert isinstance( myContacts.clusters, list )

# Check that the groups and clusters are correctly specified.
myContacts.validate()

# Generate a Python set of email addresses for the chosen cluster.
emailList = myContacts.emails( 'c2' )

assert isinstance( emailList, set )