Rename mixins module to tornado.

Tried to make it clear that tornado is an optional requirement.
This commit is contained in:
Dave Shawley 2021-03-24 06:48:25 -04:00
parent 7ee536e99f
commit 2aeddc8bc3
No known key found for this signature in database
GPG key ID: 44A9C9992CCFAB82
8 changed files with 49 additions and 41 deletions

View file

@ -4,3 +4,4 @@ graft tests
include CHANGELOG.rst include CHANGELOG.rst
include example.py include example.py
include LICENSE include LICENSE
include tox.ini

View file

@ -33,8 +33,9 @@ data to send and the task consumes the internal queue when it is connected.
Tornado helpers Tornado helpers
=============== ===============
The ``sprockets_statsd.mixins`` module contains mix-in classes that make reporting metrics from your tornado_ web The ``sprockets_statsd.tornado`` module contains mix-in classes that make reporting metrics from your tornado_ web
application simple. application simple. You will need to install the ``sprockets_statsd[tornado]`` mix-in to ensure that the Tornado
requirements for this library are met.
.. code-block:: python .. code-block:: python
@ -43,10 +44,10 @@ application simple.
from tornado import ioloop, web from tornado import ioloop, web
import sprockets_statsd.mixins import sprockets_statsd.tornado
class MyHandler(sprockets_statsd.mixins.RequestHandler, class MyHandler(sprockets_statsd.tornado.RequestHandler,
web.RequestHandler): web.RequestHandler):
async def get(self): async def get(self):
with self.execution_timer('some-operation'): with self.execution_timer('some-operation'):
@ -57,8 +58,12 @@ application simple.
await asyncio.sleep(1) await asyncio.sleep(1)
class Application(sprockets_statsd.mixins.Application, web.Application): class Application(sprockets_statsd.tornado.Application, web.Application):
def __init__(self, **settings): def __init__(self, **settings):
settings['statsd'] = {
'host': os.environ['STATSD_HOST'],
'prefix': 'applications.my-service',
}
super().__init__([web.url('/', MyHandler)], **settings) super().__init__([web.url('/', MyHandler)], **settings)
async def on_start(self): async def on_start(self):
@ -83,8 +88,8 @@ application simple.
This application will emit two timing metrics each time that the endpoint is invoked:: This application will emit two timing metrics each time that the endpoint is invoked::
applications.timers.some-operation:1001.3449192047119|ms applications.my-service.timers.some-operation:1001.3449192047119|ms
applications.timers.MyHandler.GET.204:1002.4960041046143|ms applications.my-service.timers.MyHandler.GET.204:1002.4960041046143|ms
You will need to set the ``$STATSD_HOST`` environment variable to enable the statsd processing inside of the You will need to set the ``$STATSD_HOST`` environment variable to enable the statsd processing inside of the
application. The ``RequestHandler`` class exposes methods that send counter and timing metrics to a statsd server. application. The ``RequestHandler`` class exposes methods that send counter and timing metrics to a statsd server.

View file

@ -19,17 +19,17 @@ the following environment variables.
.. envvar:: STATSD_PREFIX .. envvar:: STATSD_PREFIX
Optional prefix to use for metric paths. See the documentation for :class:`~sprockets_statsd.mixins.Application` Optional prefix to use for metric paths. See the documentation for :class:`~sprockets_statsd.tornado.Application`
for addition notes on setting the path prefix. for addition notes on setting the path prefix when using the Tornado helpers.
.. envvar:: STATSD_PROTOCOL .. envvar:: STATSD_PROTOCOL
The IP protocol to use when connecting to the StatsD server. You can specify either "tcp" or "udp". The The IP protocol to use when connecting to the StatsD server. You can specify either "tcp" or "udp". The
default is "tcp" if it not not configured. default is "tcp" if it not not configured.
You can fine tune the metric payloads and the connector by setting additional values in the ``statsd`` key of If you are using the Tornado helper clases, then you can fine tune the metric payloads and the connector by
:attr:`tornado.web.Application.settings`. See the :class:`sprockets_statsd.mixins.Application` class setting additional values in the ``statsd`` key of :attr:`tornado.web.Application.settings`. See the
documentation for a description of the supported settings. :class:`sprockets_statsd.tornado.Application` class documentation for a description of the supported settings.
Reference Reference
========= =========
@ -37,12 +37,12 @@ Reference
.. autoclass:: sprockets_statsd.statsd.Connector .. autoclass:: sprockets_statsd.statsd.Connector
:members: :members:
Mixin classes Tornado helpers
------------- ---------------
.. autoclass:: sprockets_statsd.mixins.Application .. autoclass:: sprockets_statsd.tornado.Application
:members: :members:
.. autoclass:: sprockets_statsd.mixins.RequestHandler .. autoclass:: sprockets_statsd.tornado.RequestHandler
:members: :members:
Internals Internals

View file

@ -3,10 +3,10 @@ import logging
from tornado import ioloop, web from tornado import ioloop, web
import sprockets_statsd.mixins import sprockets_statsd.tornado
class MyHandler(sprockets_statsd.mixins.RequestHandler, class MyHandler(sprockets_statsd.tornado.RequestHandler,
web.RequestHandler): web.RequestHandler):
async def get(self): async def get(self):
with self.execution_timer('some-operation'): with self.execution_timer('some-operation'):
@ -17,7 +17,7 @@ class MyHandler(sprockets_statsd.mixins.RequestHandler,
await asyncio.sleep(1) await asyncio.sleep(1)
class Application(sprockets_statsd.mixins.Application, web.Application): class Application(sprockets_statsd.tornado.Application, web.Application):
def __init__(self, **settings): def __init__(self, **settings):
super().__init__([web.url('/', MyHandler)], **settings) super().__init__([web.url('/', MyHandler)], **settings)

View file

@ -29,9 +29,10 @@ classifiers =
[options] [options]
packages = find: packages = find:
install_requires = install_requires =
tornado>=5
[options.extras_require] [options.extras_require]
tornado =
tornado>=5
dev = dev =
asynctest==0.13.0 asynctest==0.13.0
coverage==5.5 coverage==5.5
@ -39,6 +40,7 @@ dev =
flake8-import-order==0.18.1 flake8-import-order==0.18.1
sphinx==3.5.2 sphinx==3.5.2
sphinx-autodoc-typehints==1.11.1 sphinx-autodoc-typehints==1.11.1
tornado>=5
yapf==0.30.0 yapf==0.30.0
[options.packages.find] [options.packages.find]

View file

@ -6,13 +6,13 @@ import typing
from tornado import testing, web from tornado import testing, web
import sprockets_statsd.mixins import sprockets_statsd.tornado
from tests import helpers from tests import helpers
ParsedMetric = typing.Tuple[str, float, str] ParsedMetric = typing.Tuple[str, float, str]
class Handler(sprockets_statsd.mixins.RequestHandler, web.RequestHandler): class Handler(sprockets_statsd.tornado.RequestHandler, web.RequestHandler):
async def get(self): async def get(self):
with self.execution_timer('execution-timer'): with self.execution_timer('execution-timer'):
await asyncio.sleep(0.1) await asyncio.sleep(0.1)
@ -20,7 +20,7 @@ class Handler(sprockets_statsd.mixins.RequestHandler, web.RequestHandler):
self.write('true') self.write('true')
class Application(sprockets_statsd.mixins.Application, web.Application): class Application(sprockets_statsd.tornado.Application, web.Application):
def __init__(self, **settings): def __init__(self, **settings):
super().__init__([web.url('/', Handler)], **settings) super().__init__([web.url('/', Handler)], **settings)
@ -62,7 +62,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.unsetenv('STATSD_PREFIX') self.unsetenv('STATSD_PREFIX')
self.unsetenv('STATSD_PROTOCOL') self.unsetenv('STATSD_PROTOCOL')
app = sprockets_statsd.mixins.Application() app = sprockets_statsd.tornado.Application()
self.assertIn('statsd', app.settings) self.assertIn('statsd', app.settings)
self.assertIsNone(app.settings['statsd']['host'], self.assertIsNone(app.settings['statsd']['host'],
'default host value should be None') 'default host value should be None')
@ -76,7 +76,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.setenv('STATSD_PREFIX', 'my-service') self.setenv('STATSD_PREFIX', 'my-service')
self.setenv('STATSD_PROTOCOL', 'udp') self.setenv('STATSD_PROTOCOL', 'udp')
app = sprockets_statsd.mixins.Application() app = sprockets_statsd.tornado.Application()
self.assertIn('statsd', app.settings) self.assertIn('statsd', app.settings)
self.assertEqual('statsd', app.settings['statsd']['host']) self.assertEqual('statsd', app.settings['statsd']['host'])
self.assertEqual(5218, app.settings['statsd']['port']) self.assertEqual(5218, app.settings['statsd']['port'])
@ -84,17 +84,17 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.assertEqual('udp', app.settings['statsd']['protocol']) self.assertEqual('udp', app.settings['statsd']['protocol'])
def test_prefix_when_only_service_is_set(self): def test_prefix_when_only_service_is_set(self):
app = sprockets_statsd.mixins.Application(service='blah') app = sprockets_statsd.tornado.Application(service='blah')
self.assertIn('statsd', app.settings) self.assertIn('statsd', app.settings)
self.assertEqual(None, app.settings['statsd']['prefix']) self.assertEqual(None, app.settings['statsd']['prefix'])
def test_prefix_when_only_environment_is_set(self): def test_prefix_when_only_environment_is_set(self):
app = sprockets_statsd.mixins.Application(environment='whatever') app = sprockets_statsd.tornado.Application(environment='whatever')
self.assertIn('statsd', app.settings) self.assertIn('statsd', app.settings)
self.assertEqual(None, app.settings['statsd']['prefix']) self.assertEqual(None, app.settings['statsd']['prefix'])
def test_prefix_default_when_service_and_environment_are_set(self): def test_prefix_default_when_service_and_environment_are_set(self):
app = sprockets_statsd.mixins.Application(environment='development', app = sprockets_statsd.tornado.Application(environment='development',
service='my-service') service='my-service')
self.assertIn('statsd', app.settings) self.assertIn('statsd', app.settings)
self.assertEqual('applications.my-service.development', self.assertEqual('applications.my-service.development',
@ -105,7 +105,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.setenv('STATSD_PORT', '9999') self.setenv('STATSD_PORT', '9999')
self.setenv('STATSD_PREFIX', 'service') self.setenv('STATSD_PREFIX', 'service')
self.setenv('STATSD_PROTOCOL', 'tcp') self.setenv('STATSD_PROTOCOL', 'tcp')
app = sprockets_statsd.mixins.Application( app = sprockets_statsd.tornado.Application(
statsd={ statsd={
'host': 'statsd.example.com', 'host': 'statsd.example.com',
'port': 5218, 'port': 5218,
@ -119,13 +119,13 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
def test_that_starting_without_configuration_fails(self): def test_that_starting_without_configuration_fails(self):
self.unsetenv('STATSD_HOST') self.unsetenv('STATSD_HOST')
app = sprockets_statsd.mixins.Application() app = sprockets_statsd.tornado.Application()
with self.assertRaises(RuntimeError): with self.assertRaises(RuntimeError):
self.run_coroutine(app.start_statsd()) self.run_coroutine(app.start_statsd())
def test_that_starting_without_prefix_fails_by_default(self): def test_that_starting_without_prefix_fails_by_default(self):
self.unsetenv('STATSD_PREFIX') self.unsetenv('STATSD_PREFIX')
app = sprockets_statsd.mixins.Application(statsd={ app = sprockets_statsd.tornado.Application(statsd={
'host': 'statsd.example.com', 'host': 'statsd.example.com',
'protocol': 'udp', 'protocol': 'udp',
}) })
@ -136,7 +136,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
def test_starting_without_prefix_on_purpose(self): def test_starting_without_prefix_on_purpose(self):
self.unsetenv('STATSD_PREFIX') self.unsetenv('STATSD_PREFIX')
app = sprockets_statsd.mixins.Application( app = sprockets_statsd.tornado.Application(
statsd={ statsd={
'allow_no_prefix': True, 'allow_no_prefix': True,
'host': 'statsd.example.com', 'host': 'statsd.example.com',
@ -149,7 +149,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
def test_starting_with_calculated_prefix(self): def test_starting_with_calculated_prefix(self):
self.unsetenv('STATSD_PREFIX') self.unsetenv('STATSD_PREFIX')
app = sprockets_statsd.mixins.Application( app = sprockets_statsd.tornado.Application(
environment='development', environment='development',
service='my-service', service='my-service',
statsd={ statsd={
@ -164,7 +164,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.run_coroutine(app.stop_statsd()) self.run_coroutine(app.stop_statsd())
def test_starting_twice(self): def test_starting_twice(self):
app = sprockets_statsd.mixins.Application(statsd={ app = sprockets_statsd.tornado.Application(statsd={
'host': 'localhost', 'host': 'localhost',
'port': '8125', 'port': '8125',
'prefix': 'my-service', 'prefix': 'my-service',
@ -181,14 +181,14 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.run_coroutine(app.stop_statsd()) self.run_coroutine(app.stop_statsd())
def test_stopping_without_starting(self): def test_stopping_without_starting(self):
app = sprockets_statsd.mixins.Application(statsd={ app = sprockets_statsd.tornado.Application(statsd={
'host': 'localhost', 'host': 'localhost',
'port': '8125', 'port': '8125',
}) })
self.run_coroutine(app.stop_statsd()) self.run_coroutine(app.stop_statsd())
def test_optional_parameters(self): def test_optional_parameters(self):
app = sprockets_statsd.mixins.Application( app = sprockets_statsd.tornado.Application(
statsd={ statsd={
'host': 'localhost', 'host': 'localhost',
'port': '8125', 'port': '8125',
@ -204,7 +204,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.run_coroutine(app.stop_statsd()) self.run_coroutine(app.stop_statsd())
def test_starting_with_invalid_protocol(self): def test_starting_with_invalid_protocol(self):
app = sprockets_statsd.mixins.Application(statsd={ app = sprockets_statsd.tornado.Application(statsd={
'host': 'localhost', 'host': 'localhost',
'prefix': 'my-service', 'prefix': 'my-service',
'protocol': 'unknown' 'protocol': 'unknown'
@ -213,7 +213,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
self.run_coroutine(app.start_statsd()) self.run_coroutine(app.start_statsd())
def test_that_protocol_strings_are_translated(self): def test_that_protocol_strings_are_translated(self):
app = sprockets_statsd.mixins.Application(statsd={ app = sprockets_statsd.tornado.Application(statsd={
'host': 'localhost', 'host': 'localhost',
'prefix': 'my-service', 'prefix': 'my-service',
'protocol': 'tcp', 'protocol': 'tcp',
@ -223,7 +223,7 @@ class ApplicationTests(AsyncTestCaseWithTimeout):
app.statsd_connector.processor._ip_protocol) app.statsd_connector.processor._ip_protocol)
self.run_coroutine(app.stop_statsd()) self.run_coroutine(app.stop_statsd())
app = sprockets_statsd.mixins.Application(statsd={ app = sprockets_statsd.tornado.Application(statsd={
'host': 'localhost', 'host': 'localhost',
'prefix': 'my-service', 'prefix': 'my-service',
'protocol': 'udp', 'protocol': 'udp',

View file

@ -4,7 +4,7 @@ toxworkdir = ./build/tox
[testenv] [testenv]
deps = deps =
.[dev] .[dev,tornado]
commands = commands =
python -m unittest python -m unittest