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 example.py
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
===============
The ``sprockets_statsd.mixins`` module contains mix-in classes that make reporting metrics from your tornado_ web
application simple.
The ``sprockets_statsd.tornado`` module contains mix-in classes that make reporting metrics from your tornado_ web
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
@ -43,10 +44,10 @@ application simple.
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):
async def get(self):
with self.execution_timer('some-operation'):
@ -57,8 +58,12 @@ application simple.
await asyncio.sleep(1)
class Application(sprockets_statsd.mixins.Application, web.Application):
class Application(sprockets_statsd.tornado.Application, web.Application):
def __init__(self, **settings):
settings['statsd'] = {
'host': os.environ['STATSD_HOST'],
'prefix': 'applications.my-service',
}
super().__init__([web.url('/', MyHandler)], **settings)
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::
applications.timers.some-operation:1001.3449192047119|ms
applications.timers.MyHandler.GET.204:1002.4960041046143|ms
applications.my-service.timers.some-operation:1001.3449192047119|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
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
Optional prefix to use for metric paths. See the documentation for :class:`~sprockets_statsd.mixins.Application`
for addition notes on setting the path prefix.
Optional prefix to use for metric paths. See the documentation for :class:`~sprockets_statsd.tornado.Application`
for addition notes on setting the path prefix when using the Tornado helpers.
.. envvar:: STATSD_PROTOCOL
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.
You can fine tune the metric payloads and the connector by setting additional values in the ``statsd`` key of
:attr:`tornado.web.Application.settings`. See the :class:`sprockets_statsd.mixins.Application` class
documentation for a description of the supported settings.
If you are using the Tornado helper clases, then you can fine tune the metric payloads and the connector by
setting additional values in the ``statsd`` key of :attr:`tornado.web.Application.settings`. See the
:class:`sprockets_statsd.tornado.Application` class documentation for a description of the supported settings.
Reference
=========
@ -37,12 +37,12 @@ Reference
.. autoclass:: sprockets_statsd.statsd.Connector
:members:
Mixin classes
-------------
.. autoclass:: sprockets_statsd.mixins.Application
Tornado helpers
---------------
.. autoclass:: sprockets_statsd.tornado.Application
:members:
.. autoclass:: sprockets_statsd.mixins.RequestHandler
.. autoclass:: sprockets_statsd.tornado.RequestHandler
:members:
Internals

View file

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

View file

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

View file

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

View file

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