'Add a new roster item entry.
Arguments:
jid         -- The JID for the roster item.
name        -- An alias for the JID.
groups      -- A list of group names.
afrom       -- Indicates if the JID has a subscription state
of \'from\'. Defaults to False.
ato         -- Indicates if the JID has a subscription state
of \'to\'. Defaults to False.
pending_in  -- Indicates if the JID has sent a subscription
request to this connection\'s JID.
Defaults to False.
pending_out -- Indicates if a subscription request has been sent
to this JID.
Defaults to False.
whitelisted -- Indicates if a subscription request from this JID
should be automatically authorized.
Defaults to False.
save        -- Indicates if the item should be persisted
immediately to an external datastore,
if one is used.
Defaults to False.'

def add(self, jid, name='', groups=None, afrom=False, ato=False, pending_in=False, pending_out=False, whitelisted=False, save=False):

    if isinstance(jid, JID):
        key = jid.bare
    else:
        key = jid
    state = {'name': name, 'groups': (groups or []), 'from': afrom, 'to': ato, 'pending_in': pending_in, 'pending_out': pending_out, 'whitelisted': whitelisted, 'subscription': 'none'}
    self._jids[key] = RosterItem(self.xmpp, jid, self.jid, state=state, db=self.db, roster=self)
    if save:
        self._jids[key].save()
