Metadata-Version: 2.0
Name: itch
Version: 0.2.1
Summary: Twitch APIs client
Home-page: https://github.com/bibby/itch
Author: bibby
Author-email: bibby@bbby.org
License: UNKNOWN
Keywords: twitch
Platform: UNKNOWN
Requires-Dist: requests
Requires-Dist: dateutils
Requires-Dist: argparse

itch
====

A python module for pulling data from the Twitch.tv APIs (kraken, tmi, rechat).

Install
-------

::

    pip install itch

Config
------

Starting in August 2016, the kraken API will `require an application client id <https://discuss.dev.twitch.tv/t/client-id-will-be-required-in-august/6032/9>`_.
If the environment variable ``TWITCH_CLIENT_ID`` is set, itch will use this. There is no default value, but you can use the APIs without one until August;
after which you will have to supply your own.


Models
------

itch models wrap their own API endpoints, so most items can be loaded by name using the static ``get`` method, and used as dictionaries.
It'd be wise to familiarize yourself with the return values from the `kraken v3 resources <https://github.com/justintv/Twitch-API/tree/master/v3_resources>`_,
as most keys (like ``id`` and ``name``) are not explicitly mentioned in the module, but read from json and made into a ``dict``.

::

    >>> from itch.models import Channel
    >>> c = Channel.get('itmejp')
    >>> c.followers
    248650
    >>> c.created_at
    datetime.datetime(2010, 2, 28, 9, 30, 51)


All dates are made into timezone-absent ``datetime`` instances. Nested objects are usually rolled into specialized classes of their own.


Generators
----------

Lists of objects, where API paging is involved is done through generators, allowing you to seamlessly iterate over every item of a collection.

::
    >>> for follow in c.list_following():
    ...     print follow.created_at, follow.channel.name
    ...
    2011-03-04 03:16:19 giantbomb
    2012-10-17 02:36:20 day9tv
    2014-01-18 02:14:50 greenspeak
    2014-01-20 00:50:58 towelliee
    2014-07-16 05:42:50 camiwins
    2014-07-28 23:31:00 incontroltv
    ... <snip>


Rechat
------

Video objects can reprint chat, if the VOD is still available on twitch.tv .

::

    >>> for video in c.past_streams():
    ...     for chatline in video.chat_replay():
    ...         print "[%s] %s: %s" % (video.id, chatline['from'], chatline.message)
    ...         break
    ...     break
    ...
    [v80935574] mwthecool: Hey everyone!

TMI
---

``Channel`` method ``get_chatters`` can pull real-time chatters, moderators, and admins.

::

  >>> map(str, c.get_chatters().moderators)
  ['crosseye_jack', 'gray_mask', 'itmebot', 'itmejp', 'reginaldxiv', 'strippin', 'tahkai11', 'zodiacviii']


Caching
-------

Currently, only a file-based cache adapter is ready. Adapters for ``redis`` and ``memcached`` are planned for future releases.
Cache keys are the ``sha256`` of URLs with query parameters, and the values are compressed responses.
To add a cache adapter, plug a ``CacheInterface`` compliant subclass directly to the ``itch.TwitchAPI`` before making requests.

::

    from cache.filetree import FileTreeCache
    from itch import TwitchAPI

    TwitchAPI.set_caching(FileTreeCache())


FileTreeCache
~~~~~~~~~~~~~

The ``FileTreeCache`` accepts the optional environment variable ``TWITCH_CACHE_TEMP`` to set the cache path on disk.


RedisCache
~~~~~~~~~~

``rcache.RedisCache`` requires the pip module ``redis``, which is not installed by itch.
This cache makes use the following environment variables:

::

    REDIS_HOST (default: localhost)
    REDIS_PORT (default: 6379)
    REDIS_PASSWORD (default: '')
    REDIS_DB (default: 1)


MemcacheCache
~~~~~~~~~~~~~

``mcache.MemcacheCache`` requires the pip module ``python-memcached``, which is not installed by itch.
This cache makes use the ``MEMCACHE_SERVERS`` environment variable, which should be a comma separated list
of ``<host>:<port>`` items. The default value is ``127.0.0.1:11211``.


CLI
---

The command line tool prints tab-separated reports that are suitable for the plotter.

::

    itch -h
    usage: itch [-h] [-d {asc,desc}] [-l LIMIT] [-c {file,redis,memcache}]
            [{followers,following,loots_streams}] [channel]

    Twitch.tv APIs module

    positional arguments:
      {followers,following,loots_streams}
                            command
      channel               channel

    optional arguments:
      -h, --help            show this help message and exit
      -d {asc,desc}, --direction {asc,desc}
                            sorting direction
      -l LIMIT, --limit LIMIT
                            number of items to pull
      -c {file,redis,memcache}, --cache {file,redis,memcache}
                            cache type. See README for required env vars


Plotter
-------

The cli tool ``itch-plot`` renders charts with data extracted from the ``itch`` CLI or other custom tools. The
module requires the pip module ``matplotlib``, which is not installed by itch (because ``numpy``).

::

    itch-plot -h
    usage: itch-plot [-h] [-x XFIELD] [-y YFIELD] [-m XMIN] [-M XMAX] [-n YMIN]
                     [-N YMAX] [-d DELIMITER] [-r] [-s] [-Y] [-S STREAMS]
                     [-t {scatter,line,mixed}] [-l LABEL] [-T TITLE]
                     [infile] [outfile]

    plot generator

    positional arguments:
      infile                InFile
      outfile               OutFile

    optional arguments:
      -h, --help            show this help message and exit
      -x XFIELD             X axis field name
      -y YFIELD             Y axis field name
      -m XMIN, --xmin XMIN  min x value
      -M XMAX, --xmax XMAX  maz x value
      -n YMIN, --ymin YMIN  yin x value
      -N YMAX, --ymax YMAX  max y value
      -d DELIMITER, --delimiter DELIMITER
                            field delimiter
      -r, --record          print whole record (for saving subsets)
      -s, --silent          skip printouts
      -Y, --summary         print a summary
      -S STREAMS, --streams STREAMS
                            streams json
      -t {scatter,line,mixed}, --type {scatter,line,mixed}
                            graph type
      -l LABEL, --label LABEL
                            x label
      -T TITLE, --title TITLE
                            chart title


Example data pull and chart render:

::

    # dump the last 1K followers to a file
    itch -l 1000 -c file followers burkeblack > followers.csv

    # dump the last 20 streams to a file
    itch -l 20 -c file loots_streams burkeblack > streams.csv

    # plot the followers while overlaying the streams,
    # trimming the viewport and setting a title.
    itch-plot -sS streams.csv -m '2016-07-25' -M '2016-08-01' \
    -T 'BurkeBlack - last 1K' followers.csv plot.png

Here is the `resulting graph <https://scannersweep.com/misc/4e5f315e76ceac2f256a28c53b8144ea.png>`_


Todo
----

Focused on my own use-cases, kraken v3 resources are not completely covered.
This initial release of itch does not currently work with subscribers or subscriptions, games, or top stream lists.


