Metadata-Version: 1.1
Name: charcoal
Version: 0.1.0
Summary: Opionionated high level StatsD client
Home-page: https://github.com/cknv/charcoal
Author: Esben Sonne
Author-email: esbensonne+code@gmail.com
License: MIT
Description: Charcoal
        ========
        
        A simple library for sending `StatsD metrics <https://github.com/etsy/statsd/blob/master/docs/metric_types.md>`_ in python. It aims to provide a high level API for the user, however that also means that much of the lower level functionality found in most other StatsD clients are not exposed, frankly because I do not find that I need it. So no manually timing things and etc.
        
        Installing
        ----------
        
        .. code-block:: shell
        
            $ pip install charcoal
        
        
        Use it like so:
        
        .. code-block:: python
        
            import charcoal
        
            my_client = charcoal.StatsClient(prefix, host, port)
        
        For development, the client also provides a ``disabled`` kwarg, so you do not have change anything in the code when you want to not send stats:
        
        .. code-block:: python
        
            my_client = charcoal.StatsClient(prefix, host, port, disabled=True)
        
        By itself, the client does not provide much use, but it does provide easy ways to get specific sub-clients, such as timers, counters, etc.
        
        Timing
        ------
        
        .. code-block:: python
        
            timer = my_client.timer('my-timer-name').start()
        
            this_takes_a_while()
            timer.intermediate('first-pass')
        
            this_takes_a_while()
            timer.intermediate('second-pass')
            timer.stop()
        
        Counting
        --------
        
        .. code-block:: python
        
            counter = my_client.counter('my-counter-name')
        
            counter.increment('some-value', 10)
            counter.decrement('some-other-value', 10)
        
        The counter can even be fed a dict like object, such as the Counter from the standard library and send the stats as a single message.
        
        .. code-block:: python
        
            pre_counted = {
                'a-name': 5,
                'another-name': 10,
            }
        
            counter.from_mapping(pre_counted)
        
        Gauges
        ------
        
        For setting the current value.
        
        .. code-block:: python
        
            gauge = my_client.gauge('my-gauge')
        
            gauge.set('a-name', 10)
            gauge.update('a-name', 10)
        
        Sets
        ----
        
        For counting unique events, such as unique users on a page.
        
        .. code-block:: python
        
            visitors = my_client.set('visitors')
            visitors.add('ids', user.id)
        
        Custom
        ------
        
        In case the server you are using supports more metric types than this library, you can send custom metrics:
        
        .. code-block:: python
        
            metric_to_send = 'metric.name:{value}|{type_suffix}'.format(
                value=str(value),
                type_suffix=type_suffix,
            )
        
            my_client.send(metric_to_send)
        
        The ``prefix`` given to the client when creating it, is then prepended to the metric name, encoded, and sent to the server.
        
        Currently it can even accept multiple metrics in one go:
        
        .. code-block:: python
        
            my_client.send(metric_to_send, other_metric_to_send)
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
