x_ray 1.0.1
Chat parser discovering mentions, emoticons, and tags
License: MIT

####
XRay
####
XRay 1.0.0

Released: 29-May-2015

.. image:: https://travis-ci.org/MarkMarine/XRay.svg?branch=master
    :target: https://travis-ci.org/MarkMarine/XRay
    

========================================================================
XRay: A Python message inspector for mentions, emoticons, and url links.
========================================================================

XRay is a message inspection tool that finds @mentions, (emoticons) and urls
inside a string message, and provides string JSON for further processing by a
chat client.

XRay will follow links and get their url title, and find @mentions and emoticons
of the format ASCII < 15 char, surrounded by parenthesis.

Installation
------------

XRay can be installed from pip by typing in the terminal::

    $ pip install xray

After installation you can verify that XRay is installed properly by opening a
python prompt and importing XRay::

    >>> import xray

If there are no errors, everything worked properly and you can now use the XRay
library. If you see a traceback or get an import error, you may need to run pip
under ``sudo`` or create a `virtual environment <https://virtualenv.pypa.io/en/latest/>`_
for your project.


Getting Started
---------------

After installation, the XRay library can be called to parse messages by using
the convenience method ``xray.get_all()`` or by instantiating class objects of
the ``xray.raygun.MessageParser`` class. Class objects for each of the special
parsing items are available for subclassing or extension as well.

The response with be a JSON string with the contents of the special objects
found inside the message::

    Input: "@chris you around?"
    Return (string):
    {
      "mentions": [
        "chris"
      ]
    }

    Input: "Good morning! (megusta) (coffee)"
    Return (string):
    {
      "emoticons": [
        "megusta",
        "coffee"
      ]
    }


    Input: "Olympics are starting soon; http://www.nbcolympics.com"
    Return (string):
    {
      "links": [
        {
          "url": "http://www.nbcolympics.com",
          "title": "NBC Olympics | Home of the 2016 Olympic Games in Rio"
        }
      ]
    }


    Input: "@bob @john (success) such a cool feature; https://twitter.com/jdorfman/status/430511497475670016"
    Return (string):
    {
      "mentions": [
        "bob",
        "john"
      ],
      "emoticons": [
        "success"
      ]
      "links": [
        {
          "url": "https://twitter.com/jdorfman/status/430511497475670016",
          "title": "Justin Dorfman on Twitter: \\"nice @littlebigdetail from @HipChat (shows hex colors when pasted in chat). http://t.co/7cI6Gjy5pq\\""
        }
      ]
    }

@Mentions
---------

@mentions - A way to mention a user. Always starts with an '@' and ends when
hitting a non-word character.

`How mentions work <https://help.hipchat.com/knowledgebase/articles/64429-how-do-mentions-work>`_

Emoticons
---------

Emoticons - XRay parses for 'custom' emoticons which are ASCII strings, no
longer than 15 characters, contained in parenthesis. Here is a listing of them,
but XRay will find anything matching this pattern and return it as an emoticon.
Checking the current list of emoticons supported is left to the implementation.

`Emoticons <https://www.hipchat.com/emoticons>`_


URL Title Parsing
-----------------

Parsing a url link for it's title is a respectively slow process, because the
whole html page is downloaded by all of the libraries that python uses for http
requests before the page is parsed for the title tags. Because a library can not
know how many requests are coming in at one time, multi-processing these
requests in parallel is left to the implementation of this library. A reference
design that handles message requests for parsing with threading and a ZeroMQ
lister and client is included in the repo under the multithreader folder.

Full Documentation
------------------

`http://markmarine.github.io/XRay/ <http://markmarine.github.io/XRay/>`_