Interruptible fade-out of DOM elements

Posted on Sun 30 August 2015 in Code • Tagged with HTML, JavaScript, DOM, jQuery, animation, promises

Here’s a nice animated effect you may have seen in some applications, quite often games. An ephemeral UI element is displayed, either in a corner or pretty prominently, and after a short while it slowly fades out to transparency over several seconds:

"Ding" with full opacity
"Ding" after fading out

If you hover your mouse over it, though, it turns opaque right away and stays like that until you move away with the cursor. It then tries to disappear again, lest you stop it once more and restore to full opacity — and so on. Leave it for a moment, though, and it eventually vanishes.

Cool, eh? Wouldn’t it be nice to have a similar mechanism for, say, notifications displayed within a web app? Sure it would be! And it doesn’t even seem all that complicated, so let’s give it a try.

A promising API

Before delving into implementation details, it’s a good practice think for a moment about an API that we’ll expose to the user. Since it looks like a relatively simple problem, we don’t need no classes or frameworks. All that’s necessary is a simple function:

function interruptibleFadeOut(element, options) {
    // ...

Surely, however, whoever calls it would like to be able to tell when the animation finishes (e.g. to remove the element they’ve passed from the DOM tree). Simply waiting a predefined number of seconds is not sufficient, because — as described above — the effect could be restarted arbitrary many times through mouse interaction.

We could pass a callback, of course, but the modern JavaScript way of dealing with asynchronicity and concurrency is through promises. Following this pattern, our function shall return a promise that resolves when the effect ends. Disregarding the possible user interaction for now, a minimal implementation of the fade-out alone would simply use the jQuery.fadeOut method and look something like this:

function interruptibleFadeOut(element, options) {
    if (typeof options === 'number') {
        options = {fadeOut: options};

    element = $(element);
    return new Promise(function(resolve) {
        element.fadeOut(options.fadeOut, function() {

The constructor of Promise is admittedly a little weird, as it employs a level of abstraction and indirection that is indicative of (more) functional programming languages. You pass it a function that’s invoked immediately with an argument that itself is a function. (Actually two arguments, but we ignore the other one here). That input function, resolve, should be called whenever the new promise “completes”, in whatever sense it’s appropriate for the particular use case.

Here, we’re resolving the promise when our animation ends. This enables callers to react to this in a very straightforward way:

var elem = $('#foo');
interruptibleFadeOut(elem, 400 /* ms */).then(function() {

As a small aside, the Promise class is a ECMAScript 6 feature, which means it may not be available in all the browsers. The open-source Q library is often used as a compatibility shim, among many other libraries implementing the Promises/A+ recommendation.

Interaction handling

There’s little value in just wrapping an existing jQuery method, so let’s make it more interesting through mouse events. We want hovering on the element to pause the animation, while moving the cursor away should resume it:

return new Promise(function(resolve) {
    element.on('mouseenter', function() {
        element.stop(true);  // true == discard remaining animation stages
        element.css('opacity', 1.0);
    element.on('mouseleave', function() {
        element.fadeOut(options.fadeOut, function() {

    element.fadeOut(options.fadeOut, function() {

That will mostly work even with the above code, but there are several problems that need to be addressed immediately:

  • The mouseenter and mouseleave event handlers are should only fire while the fade-out effect is being played. Currently, they “leak”, and remain bound even after it finishes, interfering with given DOM element for as long as it exists.
  • The whole concept of hovering is contingent upon the user having a pointing device. In today’s mobile world, this excludes a significant fraction of clients. We need an alternative interaction pattern for touchscreen devices, and one possible option is restart the effect on click/tap.
  • There is a fair amount of repetition here, and it will only get worse once the previous problems are dealt with.

Cleaning up

A correct (and cleaner) version is quite a bit longer, but shouldn’t be too hard to follow:

return new Promise(function(resolve) {
    // Event handlers used by the effect.
    var events = {
        mouseenter: function() { interruptAnimation(); },
        mouseleave: function() { delayedFadeOut(); },
        click: function() {
    Object.keys(events).forEach(function(name) {
        element.on(name, events[name]);

    // Helper functions.
    var interruptAnimation = function() {
        element.css('opacity', 1.0);
    var delayedFadeOut = function() {
        if (options.delay) {
        element.fadeOut(options.fadeOut, function() {
            Object.keys(events).forEach(function(name) {
      , events[name]);

    // Start the animation.
    if (options.fadeIn) {

The main part is of course the delayedFadeOut function. It is invoked right at the beginning, as well as whenever the animation has to be started again.

We also put the event handlers in a “map” (JavaScript object). This makes it easy to initially bind them to the element, and — more importantly — unbind them when the effect ends.

As a final touch, we also allow the caller to specify how long the element should remain at its full opacity before it starts to fade out (delay), and to optionally add a fadeIn stage at the very beginning to make everything look a little nicer. (I recommend no more than 300-400ms for that part, though).

Practical example

A complete code sample for the interruptibleFadeOut function can be seen in this gist. To use it in practice, you’d most likely need at least a little bit of CSS and additional JavaScript to position the element appropriately:

<div id="toast">Hello, world!</div>
#toast {
    position: fixed;
    display: none;

    /* These are arbitrary */
    top: 100px;
    width: 80%;
    height: 50px;
var toast = $('#toast');
    left: Math.round($(window).width() - element.outerWidth() / 2),
interruptibleFadeOut(toast, { fadeIn: 200, delay: 1000, fadeOut: 3000 })
    .then(function() { toast.remove() });

Styling it to look like a level-up ding is left as an exercise for the reader :)

Querying multiple scalar values in SQLAlchemy

Posted on Wed 26 August 2015 in Code • Tagged with SQLAlchemy, Python

SQLAlchemy is probably the greatest ORM library ever invented — and not just for Python. Like everything, though, it could sometimes use an improvement.

One typical pattern that I’ve seen repeated many times is querying for values of a single column from multiple rows. Almost always, the desired outcome is to have those values in a Python iterable. Unfortunately, when returning multiple rows, the Query class can only give them out as tuples, making it necessary to unpack them explicitly every time:

active_users_ids = [
    uid for (uid,) in session.query(

It’s worth noting that a very similar operation — retrieving a single column value from one row — is comparatively cleaner thanks to a dedicated Query.scalar method. So why not have a similar one for the use case above?…

Turns out that SQLAlchemy is so amazingly extensible that we can easily outfit Query with such a method ourselves.

Our own Query

The officially ordained way to do something like that is to extend the original sqlalchemy.orm.query.Query class with any additional functionality we require. We can then introduce a method in the subclass — let’s call it values — that implements our logic:

from sqlalchemy.orm.exc import MultipleResultsFound
from sqlalchemy.orm.query import Query as _Query

class Query(_Query):
    """Custom SQLAlchemy query class."""

    def values(self):
        """Return an iterable of all scalar, singleton element values
        from rows matched by this query.

        :raise MultipleValuesFound: If result rows have more than one element
            return [x for (x,) in self.all()]
        except ValueError as e:
            raise MultipleValuesFound(str(e))

class MultipleValuesFound(ValueError, MultipleResultsFound):
    """Exception raised by :meth:`Query.values`
    when multiple values were found in a single result row.

There is a special erroneous condition that occurrs when the Query returns rows with more than one column value. It would be possible to detect it preemptively by inspecting certain attributes of the query object, but it’s simpler to just catch the exception caused by unsuccessful tuple unpacking.

In any case, I recommend re-raising it as a custom exception to enable more robust error handling in the client code.

Wiring it

The last piece of the puzzle is to make Session objects in our application use the new Query class. It’s easy: we simply pass it as query_cls parameter to the Session constructor. In more realistic scenarios — such as web applications with per-request database sessions — it means giving it directly to the sessionmaker:

from sqlalchemy import create_engine
from sqlalchemy import scoped_session, sessionmaker

from myapp.ext.sqlalchemy import Query

session = scoped_session(sessionmaker(bind=create_engine(DATABASE_URL),

Of course, actual session setup in your app may differ in few details from the sample above.

Usage example

With the new Query class wired in, the values method becomes immediately usable:

active_user_ids = session.query(

and the ugly manual unpacking of row tuples is no longer necessary.

Custom errors in Jinja templates

Posted on Sun 23 August 2015 in Code • Tagged with Jinja, templates, Python, errors

Jinja is a pretty great templating engine for Python. Unlike the likes of Mustache or Handlebars, it doesn’t try to constrain overmuch the kind of logic that the programmer can put in their templates. Most Python expressions, for example, are supported, as are variables and functions (or macros in Jinja’s parlance).

One conspicously absent feature is throwing exceptions directly from template code. (It’s obviously possible from custom filters or tags). If we had it, we could add some more robust error checking to the template input values or macro paramaters.


Let’s say you have extracted a {% macro %} for rendering a button, like the one from Twitter Bootstrap:

{% macro button(text=none, style='default', type='button') %}
  <button class="btn btn-{{ style }}" type="{{ type }}">
    {% if text is not none %}
      {{ text }}
    {% else %}
      {{ caller() }}
    {% endif %}
{% endmacro %}

The benefit of this conditional definition is the relative ease of creating buttons with either just a text label:

{{ button("Load More...") }}

or some more complicated markup:

{% call button(style='success', type='submit') %}
  <i class="fa fa-check"></i>Finish
{% endcall %}

Supplying both, however, is an ambiguity that the macro currently “resolves” by preferring text over a {% call %} block. It should rather be an error instead:

{% if caller and caller is defined and text is not none %}
  {% error "Cannot supply text= parameter to button() when invoking it through {% call %}" %}
{% endif %}

But {% error %} isn’t a tag that Jinja supports by default. To make it available, we need to implement the logic ourselves.

Adding new Jinja tags

Don’t sweat, though! It won’t be necessary to fork Jinja itself and modify its core code. Custom tags may just as well be added with extensions, which is a dedicated Jinja mechanism.

An extension is just a Python class that declares tags it intends to support and implements a parse method:

from jinja2.ext import Extension

class ErrorExtension(Extension):
    tags = frozenset(['error'])

    def parse(self, parser):
        # ...

What can be a little tricky is that parse method itself shouldn’t take any direct action. Instead, it shall return a piece of ASTabstract syntax tree — that Jinja will include in the compiled template. All regular Jinja features are thus available, but the power of extensions doesn’t end here.

Handling the {% error %} tag

The argument to parse is a parser object, which we can use to extract tokens from the template source code. The error tag identifier is one such token, and the string following it is another. As it turns out, we are only tenuously interested in the former, but we definitely want to pick the latter, because it’s the error message we’ll raise an exception with:

tag =
message = parser.parse_expression()

As it was mentioned previously, the parse method itself won’t be raising this exception immediately. If we did that, no template with the {% error %} tag would ever parse successfully! What we need instead is an AST node that throws the exception when it’s evaluated. This way, it will be deferred until the template is being rendered and its execution point reaches the {% error "..." %} stanza.

Jinja already has a correct node type handy: it’s named CallBlock, and it represents a statement that {% call %}s given method of the Extension class:

from jinja2.nodes import CallBlock, Const

# (in ErrorExtension.parse)
node = CallBlock(
    self.call_method('_exec_error', [message, Const(tag.lineno)]),
    [], [], [])
return node

This method, _exec_error, should do the crux of what this extension is about: raise an exception. Let’s define a distinct error class for it, to tell user errors apart from those thrown by Jinja itself:

from jinja2 import TemplateAssertionError

class ErrorExtension(Extension):
    # ...
    def _exec_error(self, message, lineno, caller):
        raise TemplateUserError(message, lineno)

class TemplateUserError(TemplateAssertionError):

Using the extension

The last step is to tell Jinja to use our extension when compiling and rendering templates. For that, we simply add it to the Environment:


If you are using the Flask framework, jinja_env is an attribute on the Flask application object.

To see the complete code sample for ErrorExtension, have a look at this gist.


Posted on Sat 22 August 2015 in News

My name is Karol Kuczmarski, and this is my personal blog.

It’s built using Python and Pelican — a static site generator — with a little help from Fabric and Git.

I’ll be using it mostly to talk about programming, technologies I work with, and projects I’m hacking on.