Collection of utilities, helpers, and principles for building Python backend applications. Supports aiohttp.web, Flask, and your web-framework.

  • Works on Python 3.5+
  • BSD licensed
  • Source, issues, and pull requests on GitHub


pip install rororo


rororo is licensed under the terms of BSD License.

Schemas API

Utilities API


Immutable Settings dictionary and various utilities to read settings values from environment.

Module helps you to prepare and read settings inside your web application.

rororo.settings.immutable_settings(defaults, **optionals)[source]

Initialize and return immutable Settings dictionary.

Settings dictionary allows you to setup settings values from multiple sources and make sure that values cannot be changed, updated by anyone else after initialization. This helps keep things clear and not worry about hidden settings change somewhere around your web application.

  • defaults (Union[module, Dict[str, Any]]) – Read settings values from module or dict-like instance.
  • **optionals

    Update base settings with optional values.

    In common additional values shouldn’t be passed, if settings values already populated from local settings or environment. But in case of using application factories this makes sense:

    from . import settings
    def create_app(**options):
        app = ...
        app.settings = immutable_settings(settings, **options)
        return app

    And yes each additional key overwrite default setting value.

Return type:



Check whether given key is valid setting key or not.

Only public uppercase constants are valid settings keys, all other keys are invalid and shouldn’t present in Settings dict.

Valid settings keys


Invalid settings keys

Parameters:key (str) – Key to check.
Return type:bool
rororo.settings.inject_settings(mixed, context, fail_silently=False)[source]

Inject settings values to given context.

  • mixed (Union[str, module, Dict[str, Any]]) – Settings can be a string (that it will be read from Python path), Python module or dict-like instance.
  • context (Mutablemapping[str, Any]) – Context to assign settings key values. It should support dict-like item assingment.
  • fail_silently (bool) – When enabled and reading settings from Python path ignore errors if given Python path couldn’t be loaded.
Return type:



Iterate over settings values from settings module or dict-like instance.

Parameters:mixed (Union[module, Dict[str, Any]]) – Settings instance to iterate.
Return type:Iterator[Tuple[str, Any]]
rororo.settings.from_env(key, default=None)[source]

Shortcut for safely reading environment variable.

  • key (str) – Environment var key.
  • default (Optional[~T]) – Return default value if environment var not found by given key. By default: None
Return type:

Union[str, ~T, None]

rororo.settings.setup_locale(lc_all, first_weekday=None, *, lc_collate=None, lc_ctype=None, lc_messages=None, lc_monetary=None, lc_numeric=None, lc_time=None)[source]

Shortcut helper to setup locale for backend application.

  • lc_all (str) – Locale to use.
  • first_weekday (Optional[int]) – Weekday for start week. 0 for Monday, 6 for Sunday. By default: None
  • lc_collate (Optional[str]) – Collate locale to use. By default: <lc_all>
  • lc_ctype (Optional[str]) – Ctype locale to use. By default: <lc_all>
  • lc_messages (Optional[str]) – Messages locale to use. By default: <lc_all>
  • lc_monetary (Optional[str]) – Monetary locale to use. By default: <lc_all>
  • lc_numeric (Optional[str]) – Numeric locale to use. By default: <lc_all>
  • lc_time (Optional[str]) – Time locale to use. By default: <lc_all>
Return type:



Shortcut helper to configure timezone for backend application.

Parameters:timezone (str) – Timezone to use, e.g. “UTC”, “Europe/Kiev”.
Return type:None


Logging utilities.

Module provides easy way to setup logging for your web application.

rororo.logger.default_logging_dict(*loggers, **kwargs)[source]

Prepare logging dict suitable with logging.config.dictConfig.


from logging.config import dictConfig
  • *loggers – Enable logging for each logger in sequence.
  • **kwargs – Setup additional logger params via keyword arguments.
Return type:

Dict[str, Any]

rororo.logger.update_sentry_logging(logging_dict, sentry_dsn, *loggers, level=None, **kwargs)[source]

Enable Sentry logging if Sentry DSN passed.


Sentry logging requires raven library to be installed.


from logging.config import dictConfig

LOGGING = default_logging_dict()
SENTRY_DSN = '...'

update_sentry_logging(LOGGING, SENTRY_DSN)

Using AioHttpTransport for SentryHandler

This will allow to use aiohttp.client for pushing data to Sentry in your aiohttp.web app, which means elimination of sync calls to Sentry.

from raven_aiohttp import AioHttpTransport
update_sentry_logging(LOGGING, SENTRY_DSN, transport=AioHttpTransport)
  • logging_dict (Dict[str, Any]) – Logging dict.
  • sentry_dsn (Optional[str]) – Sentry DSN value. If None do not update logging dict at all.
  • *loggers – Use Sentry logging for each logger in the sequence. If the sequence is empty use Sentry logging to each available logger.
  • **kwargs – Additional kwargs to be passed to SentryHandler.
Return type:


class rororo.logger.IgnoreErrorsFilter[source]

Ignore all warnings and errors from stdout handler.


Allow only debug and info log messages to stdout handler.

Return type:bool


Various utilities for aiohttp and other aio-libs.

rororo.aio.add_resource_context(router, url_prefix=None, name_prefix=None)[source]

Context manager for adding resources for given router.

Main goal of context manager to easify process of adding resources with routes to the router. This also allow to reduce amount of repeats, when supplying new resources by reusing URL & name prefixes for all routes inside context manager.

Behind the scene, context manager returns a function which calls:

resource = router.add_resource(url, name)
resource.add_route(method, handler)


with add_resource_context(app.router, '/api', 'api') as add_resource:
    add_resource('/', get=views.index)
    add_resource('/news', get=views.list_news, post=views.create_news)
  • router (Any) – Route to add resources to.
  • url_prefix (Optional[str]) – If supplied prepend this prefix to each resource URL.
  • name_prefix (Optional[str]) – If supplied prepend this prefix to each resource name.
Return type:



Check whether current request is XHR one or not.

Basically it just checks that request contains X-Requested-With header and that the header equals to XMLHttpRequest.

Parameters:request (Any) – Request instance.
Return type:bool

Convert Redis URL string to dict suitable to pass to aioredis.create_redis(...) call.


async def connect_redis(url=None):
    url = url or 'redis://localhost:6379/0'
    return await create_redis(**get_aioredis_parts(url))
Parameters:url (str) – URL to access Redis instance, started with redis://.
Return type:Dict[str, Any]


Useful functions to work with timedelta instances.

rororo.timedelta.str_to_timedelta(value, fmt=None)[source]

Convert string value to timedelta instance according to the given format.

If format not set function tries to load timedelta using default TIMEDELTA_FORMAT and then both of magic “full” formats.

You should also specify list of formats and function tries to convert to timedelta using each of formats in list. First matched format would return the converted timedelta instance.

If user specified format, but function cannot convert string to new timedelta instance - ValueError would be raised. But if user did not specify the format, function would be fail silently and return None as result.

  • value (str) – String representation of timedelta.
  • fmt (Optional[str]) – Format to use for conversion.
Return type:



Compute the arithmetic mean for timedeltas list.

Parameters:*values – Timedelta instances to process.
Return type:timedelta
rororo.timedelta.timedelta_div(first, second)[source]

Implement divison for timedelta instances.

  • first (timedelta) – First timedelta instance.
  • second (timedelta) – Second timedelta instance.
Return type:



Return full number of seconds from timedelta.

By default, Python returns only one day seconds, not all timedelta seconds.

Parameters:value (timedelta) – Timedelta instance.
Return type:int
rororo.timedelta.timedelta_to_str(value, fmt=None)[source]

Display the timedelta formatted according to the given string.

You should use global setting TIMEDELTA_FORMAT to specify default format to this function there (like DATE_FORMAT for builtin date template filter).

Default value for TIMEDELTA_FORMAT is 'G:i'.

Format uses the same policy as Django date template filter or PHP date function with several differences.

Available format strings:

Format character Description Example output
a Not implemented.  
A Not implemented.  
b Not implemented.  
B Not implemented.  
c Not implemented.  
d Total days, 2 digits with leading zeros. Do not combine with w format. '01', '41'
D Not implemented.  
f Magic “full” format with short labels. '2w 4d 1:28:07'
F Magic “full” format with normal labels. '2 weeks, 4 days, 1:28:07'
g Day, not total, hours without leading zeros. To use with d, j, or w. '0' to '23'
G Total hours without leading zeros. Do not combine with g or h formats. '1', '433'
h Day, not total, hours with leading zeros. To use with d or w. '00' to '23'
H Total hours with leading zeros. Do not combine with g or h formats. '01', ``'433'
i Hour, not total, minutes, 2 digits with leading zeros To use with g, G, h or H formats. 00 to '59'
I Total minutes, 2 digits or more with leading zeros. Do not combine with i format. '01', '433'
j Total days, one or 2 digits without leading zeros. Do not combine with w format. '1', '41'
J Not implemented.  
l Days long label. Pluralized and localized. 'day' or 'days'
L Weeks long label. Pluralized and localized. 'week' or 'weeks'
m Week days long label. Pluralized and localized. 'day' or 'days'
M Not implemented.  
n Not implemented.  
N Not implemented.  
O Not implemented.  
P Not implemented.  
r Standart Python timedelta representation with short labels. '18 d 1:28:07'
R Standart Python timedelta representation with normal labels. '18 days, 1:28:07'
s Minute, not total, seconds, 2 digits with leading zeros. To use with i or I. '00' to '59'
S Total seconds. 2 digits or more with leading zeros. Do not combine with s format. '00', '433'
t Not implemented.  
T Not implemented.  
u Second, not total, microseconds. 0 to 999999
U Not implemented.  
w Week, not total, days, one digit without leading zeros. To use with W. 0 to 6
W Total weeks, one or more digits without leading zeros. '1', '41'
y Not implemented.  
Y Not implemented.  
z Not implemented.  
Z Not implemented.  

For example,

>>> import datetime
>>> from rororo.timedelta import timedelta_to_str
>>> delta = datetime.timedelta(seconds=99660)
>>> timedelta_to_str(delta)
... '27:41'
>>> timedelta_to_str(delta, 'r')
... '1d 3:41:00'
>>> timedelta_to_str(delta, 'f')
... '1d 3:41'
>>> timedelta_to_str(delta, 'W L, w l, H:i:s')
... '0 weeks, 1 day, 03:41:00'

Couple words about magic “full” formats. These formats show weeks number with week label, days number with day label and seconds only if weeks number, days number or seconds greater that zero.

For example,

>>> import datetime
>>> from rororo.timedelta import timedelta_to_str
>>> delta = datetime.timedelta(hours=12)
>>> timedelta_to_str(delta, 'f')
... '12:00'
>>> timedelta_to_str(delta, 'F')
... '12:00'
>>> delta = datetime.timedelta(hours=12, seconds=30)
>>> timedelta_to_str(delta, 'f')
... '12:00:30'
>>> timedelta_to_str(delta, 'F')
... '12:00:30'
>>> delta = datetime.timedelta(hours=168)
>>> timedelta_to_str(delta, 'f')
... '1w 0:00'
>>> timedelta_to_str(delta, 'F')
... '1 week, 0:00'
  • value (timedelta) – Timedelta instance to convert to string.
  • fmt (Optional[str]) – Format to use for conversion.
Return type:



Different utility functions, which are common used in web development, like converting string to int or bool.


Convert string or other Python object to boolean.


Passing flags is one of the most common cases of using environment vars and as values are strings we need to have an easy way to convert them to boolean Python value.

Without this function int or float string values can be converted as false positives, e.g. bool('0') => True, but using this function ensure that digit flag be properly converted to boolean value.

Parameters:value (Any) – String or other value.
Return type:bool
rororo.utils.to_int(value, default=None)[source]

Convert given value to int.

If conversion failed, return default value without raising Exception.

  • value (str) – Value to convert to int.
  • default (Optional[~T]) – Default value to use in case of failed conversion.
Return type:

Union[int, ~T, None]


1.2.1 (2019-03-22)

  • Do not depend on jsonschema>=3.0.0

1.2.0 (2018-11-01)

  • Publish 1.2 release

1.2.0a1 (2018-10-22)

  • Make all project packages PEP-561 compatible

1.2.0a0 (2018-10-18)

  • Python 3.7 support
  • Ensure that rororo works well with latest aiohttp
  • Allow setting level on updating logging dict to use Sentry handler
  • Add new rororo.timedelta module with utilities to work with timedeltas
  • Add new rororo.utils module
  • Move type annotations to rororo.annotations module

1.1.1 (2017-10-09)

  • Do not attempt to convert empty list to dict for request/response data

1.1.0 (2017-10-09)

  • Allow to supply non-dicts in request/response data

1.0.0 (2017-05-14)

  • Publish 1.0 release, even proper docs are not ready yet

1.0.0b1 (2017-05-13)

  • Annotate all code in rororo
  • Use mypy on linting source code
  • Require Python 3.5 or higher due to changes above

1.0.0a5 (2016-10-23)

1.0.0a4 (2016-09-01)

  • Pass kwargs to SentryHandler on configuring Sentry logging

1.0.0a3 (2016-08-08)

  • Add rororo.aio module with:
    • add_resource_context context manager
    • is_xhr_request, parse_aioredis_url utility functions
  • Update flake8 config & bump aiohttp version for tests
  • Added ChangeLog & modified GitHub Releases Page

1.0.0a2 (2015-12-18)

  • Adds ability to supply custom error class while making manual errors by schema.make_error method
  • Default validator class preset default values from schema to instance for validation
  • Several improvements to test process

1.0.0a1 (2015-11-26)

  • New beginning for rororo project. Now it is a bunch of helper methods instead of yet another web-framework.