slackmentions 0.1.2
Some functions for dealing with mentions in slack messages
License: MIT
Requires Python: >=3
Keywords: slack,text,messages,mentions

slackmentions
=============
Provides functions for dealing with mentions in slack messages.

Installation
============
``$ pip install slackmentions``

You will also need the `slackclient
<https://github.com/slackapi/python-slackclient>`_ package for this to be
useful.

Usage
=====
Available functions:

findpeople:
    Finds username mentions in slack text and creates `SlackPerson
    <https://github.com/rickh94/slackperson>`_ objects
    for those people. Returns a list of those SlackPerson objects.
    This can be used to get more information about users or if the same text
    will be processed multiple times.

    Arguments:

    text: text to find @ mentions in.

    userlist: output of slack api users.list

    silent: slackperson.SlackDataError will be raised if a mention is found
    in the text but not in the userlist. Setting to True will swallow this
    error and ignore that mention.

    Returns: List of SlackPerson objects or empty list.

mention_text:
    Replaces username mentions in text with user id mentions for tagging by
    slack api message sending.

    Arguments:

    text: The text containing @ mentions

    people: A list of SlackPerson objects for people found in the text. If not
    specified, one will be generated by passing text and userlist to
    findpeople. Required if userlist is not provided.

    userlist: The json from slack api users.list. Required if people is not
    provided.

    silent: slackperson.SlackDataError will be raised if a mention is found
    in the text but not in the userlist. Setting to True will swallow this
    error and ignore that mention. Only applies if userlist is specified, not
    people.

clean_text:
    Deletes @ mentions from text
    Arguments:

    text: The text containing @ mentions

    people: A list of SlackPerson objects for people found in the text. If not
    specified, one will be generated by passing text and userlist to
    findpeople. Required if userlist is not provided.

    userlist: The json from slack api users.list. Required if people is not
    provided.

    silent: slackperson.SlackDataError will be raised if a mention is found
    in the text but not in the userlist. Setting to True will swallow this
    error and ignore that mention. Only applies if userlist is specified, not
    people.

    clean_all: set to true to ignore the user lists and people and just nuke
    all the mentions


.. code::

  import slackmentions
  from slackclient import SlackClient

  sc = SlackClient(os.environ['SLACK_API_TOKEN'])
  userlist = sc.api_call('users.list')
  text = 'hi @joe, could you tell @kathy to call me?'

  people = slackmentions.findpeople(text, userlist)
  # people = [SlackPerson(userid='U0000001', username='joe'),
              SlackPerson(userid='U0000002', username='kathy')]
  withmentions = slackmentions.mention_text(text, people=people)
  # withmentions = 'hi <@U0000001>, could you please tell <@U0000002> to call
  me?'
  withmentions2 = slackmentions.mention_text(text, userlist=userlist)
  assert withmentions = withmentions2

  cleantext = slackmentions.clean_text(text, people=people)
  # cleantext = 'hi, could you please tell to call me?'

Tests
=====
There are tests for each method with successes, errors raised, errors
swallowed, and missing keyword arguments. They can be run with ``pytest``.