“Effective Django” at PyCon 2013

PyCon (the US variation, at least), is about a month and half away, and once again I’m looking at the schedule of presentations and events and wondering how it is the community pulls it off every year. I’m also busy preparing my contribution to PyCon. This year I’m happy to be presenting a tutorial, Effective Django.

You may wonder what I mean by “Effective Django”. It’s an introduction to Django with a focus on good engineering practices. What I’ve noticed from my own experience over the years is that with all of its features and flexibility, Django makes it easy to get up and going really quickly. It also lets you write code that’s difficult to test, scale, and maintain. I have written plenty of code like that over the years, and the problem is that the real pain may come long after the initial implementation. From talking to engineers at Eventbrite and elsewhere I have learned that I’m not alone in this, so I’ve been working on documenting how to do leverage Django effectively. My goal is that attendees of the tutorial will leave feeling like they’re able to work on a Django application and identify things to do (and avoid) that will help them write code that’s cohesive, testable, and scalable.

I’m enjoying putting together the material for PyCon, and I hope that if you’re new to Django and interested in starting off on the right foot you’ll join me in Santa Clara for the afternoon.

If you’re totally new to Django and want to get a complete introduction to web apps and Django, Effective Django pairs well with Karen Rustad’s “Going from web pages to web apps“.

author:Nathan Yergler
tags:talks, effective django, python,

New Work: Days Getting Shorter

Days Getting Shorter”, copyright 2013, Nathan Yergler

8” x 10” Two Plate Linocut, printed on Rives BFK

This was a fun piece to work on. It’s based on this photo (used with permission, albeit after the fact), which I’ve been staring at off and on for months. The most interesting thing to me is how the rainbow roll turned out (the gradient in the image). The ink at the top is a magenta with a little blue in it, and the ink at the bottom is mostly opaque white, with a little black in it to make it about the color of concrete or pavement. But the black shadow at the bottom masks most of the pure gray color, and the opaque white in the gray seems to really bring out the blue that’s in the magenta. Totally unexpected, but very pleasing to my eye.

author:Nathan Yergler
tags:linocut, multiplate

Bytes, Characters, Codecs, and Strings

One of the persistent areas of confusion for many Python developers is Unicode strings, byte strings, and how they interact. While Python 3 should help ease some of that pain, many places (including Eventbrite) are still running on Python 2. The problem is made worse by the fact that modern web frameworks (Django, in our case) attempt to do the Right Thing by using Unicode strings, but legacy code may assume byte strings with a specific encoding. That bifurcation can lead to confusion, and make it difficult to refactor code in a way that can be shared between both “sides of the street”.

Towards the end of 2012 I developed a brief training for the web team to help establish a baseline common understanding of Unicode and string handling in Python. The notes from the presentation are available, and I hope others find them useful, as well. I’m currently working on some edits to expand areas that seemed to have lingering confusion, and to address the upcoming shift to Python 3 more directly. If you have suggestions, you can contact me me with them.

author:Nathan Yergler
tags:python, unicode, i18n

Hieroglyph 0.5

During the last week of 2012 I pushed out a new release of Hieroglyph. I realized later that I haven’t really been talking about it here, so I wanted to mention some of the new features and functionality I’ve been working on. When I published the 0.3 release, I said I was planning to work on hooking analytics into the slide viewing so that creators could get a better sense of how their slide decks were being used. I have done some work to that end, but would up getting side tracking.

The 0.4 release consisted primarily of internal cleanups in preparation for adding analytics support. There were some places where the Javascript or styles were duplicated, so I put some effort into cleaning that up. I also split up the Javascript to separate slide control from user interaction. This was done to support both analytics and the initial implementation of the Presenter’s Console: a separate window that displays the previous, current, and next slides, and allows the presenter to control the primary display window. With Hieroglyph 0.4 and later you can open by pressing c within a slide document.

Hieroglyph 0.4 also added support for slide numbering and for applying a theme to individual documents inside of a project using the slideconf direction. For example:

.. slideconf::
   :theme: single-level

In December I put together some training for other engineers at Eventbrite around Python byte and unicode strings, and how to safely work with them both in our codebase. While I was putting that together, I realized that there was a lot of text and code samples in the documentation that I wanted to go through interactively, and not include in slides. I wound up going without slides, and found that presenting from the Python interactive interpreter was very effective for this sort of hands on training. That said, it would have been nice to have had a few key slides: an introduction, a summary of key points, and maybe where to go next. That’s the sort of content I’d like to keep with the main document so it doesn’t drift too far out of sync, but Hieroglyph didn’t really support that approach: it assumed that you wanted to generate a slide per section, unless you explicitly marked things as notslides.

Hieroglyph 0.5 adds a couple of features to support these different work modes. First, it adds an autoslides configuration parameter, that allows you to disable automatic slide generation of a project or document level. If autoslides is True (the default), you’ll see the previous Hieroglyph behavior, one slide per section. If it’s set to False, you’ll need to write slides using the second new feature, the slide directive.

The slide directive describes a single slide, including the title, level (which may be used for styling), and content. An example from the Hieroglyph smoketest document:

.. slide:: The ``slide`` Directive
   :level: 2

   In addition to headings, you can use the ``..slide::`` directive to
   define a slide.

Because the conditional slides directive differed by only one letter, Hieroglyph 0.5 also renamed the conditional directives to ifslides and ifnotslides. The previous names will continue to work (at least for a couple releases), but I’m using the new names myself to make it easier to understand what’s going on.

Thanks to bug reports filed in the Hieroglyph github project, the 0.5 release also includes fixes for styling nested lists and compatibility with the latex-pdf builder.

At this point Hieroglyph seems to be working pretty well for me and others. There are a few things I’d like to add yet, but for the next couple of months my focus is going to be more on using it rather than developing it. I’m working on more training for new engineers at Eventbrite, and I’ll be giving a tutorial of Effective Django at PyCon this year. I think both of those are going to be good opportunities use Hieroglyph in different contexts and hopefully get some more data on what’s working or not. If you’re using it (or just trying it out) and have comments or feedback, filing a bug is something I find really helpful.

author:Nathan Yergler
tags:hieroglpyh, sphinx, rst, slides


I’ve been contemplating leaving WordPress for a while. Part of it was a desire for something simpler, part of it was that as I worked on Hieroglyph, I found myself really appreciating the Sphinx build pipeline. Older blog posts on my site have also been in varying states of brokenness for the past few years: I used to use Textile for writing posts, but at some point the WordPress plugin I was using stopped working, so I just let it serve them with the raw markup. It felt like it’d be easier to fix those up into something sane if I had flat files to work with, instead of a relational database.

There are quite a few static site generators these days, but only one that I’ve found that leverages Sphinx. Tinkerer leverages Sphinx, adding an extension for aggregating post pages into archives, categories, and tag pages. Its use of Sphinx means that you can also generate non-blog pages with it, and you have quite a bit of flexibility to extend it if you need to.

Moving from my WordPress backend, I wanted keep the URLs as stable as possible. Tinkerer 1.0 is great, but it did a few things differently than I’d like. Specifically, it:

  • uses the Sphinx HTML builder, which adds .html extensions to the output pages
  • assumes that the blog’s root is the root of the domain (on my site it’s in the /blog/ path)
  • places every post in your RSS feed
  • doesn’t allow you to configure the output path for the feed or archives

I’ve forked Tinkerer on Bitbucket and addressed those issues. Making Tinkerer work with the dirhtml builder was most of the work, as there were several places that assumed you were dealing with HTML files (instead of directories with an index.html inside them). My experience with Sphinx from Hieroglyph came in handy here: the Sphinx HTML builders all have a .get_target_uri() method, which does the right thing. I’m sure there are some things I’ve missed or broken in the process, but my hope is that I can get my changes into shape and merged upstream. I’ve also added several configuration directives for customizing how Tinkerer works. I still need to update the documentation in my fork, but you can see those in the source.

As an aside, if you’re looking at migrating from WordPress to another platform, the exitwp script is a pretty sane place to start. I used it, along with pandoc, to transform my WordPress export into more uniform Restructured Text.

author:Nathan Yergler
tags:sphinx, tinkerer, rst