Update 2014/03/16: I submitted a better different patch, which was partially merged, but there’s still an ongoing discussion about the best way to make find_packages() support PEP 420.

Earlier today I submitted a patch to setuptools that adds support for PEP 420 namespace packages (“NS packages”) to find_packages(). In the process, I learned a few things about NS packages that I found somewhat surprising.

My initial “intuitive” understanding was that only directories with either one or more .py files or containing only directories would be considered NS packages. I also thought that NS packages couldn’t be nested under regular packages (i.e., those with an __init__.py). I’m not exactly sure how I arrived at this understanding, but it’s what seemed to make sense before I dug into this.

The first thing I found surprising is that NS packages can be nested under regular packages. I couldn’t figure out what the use cases for this would be (which, of course, doesn’t mean there aren’t any). One potential problem with this is that if you have a directory with package data that’s not a Python package, it can be imported as a package, whereas in the pre-420 days you’d get an ImportError.

The second surprising thing, which is a generalization of the first, is that any subdirectory of a directory that’s on sys.path can be imported as an NS package. This is probably useful in certain scenarios, but it can also cause issues in other scenarios.

For example, if find_packages() emulated the above behavior, by default *every* subdirectory in a source tree would be considered a package and included in the package list and therefore in a distribution, which is often (maybe usually) undesirable.

If you’re using vanilla distutils, this isn’t an issue since you have to explicitly list all of the packages in a distribution, but that can be super tedious and it’s easy to forget to add new packages to setup(), and a lot of packages on PyPI already use find_packages().

So I had one thought that an explicit __not_a_namespace__ marker file could be added to directories that shouldn’t be considered NS packages (or maybe __package_data__ is a better name). This is almost certainly a non-starter though, because it could lead to a lot of empty files cluttering up your source tree (plus, you might forget to do this too, so it doesn’t really help with that aspect).

My patch for find_packages() adds the ability to explicitly specify the packages you want to include using wild card patterns. In the following example, the mypkg directory and all of its subdirectories will be included as packages (when running Python 3.3+):

project/
    docs/
        index.rst
    mypkg/
        mysubpkg/
            __init__.py
        xxx/
            some-file
        mymod.py
    setup.py

# setup.py
from setuptools import setup, find_packages

setup(
    packages=find_packages(include=['mypkg*']),
    ...
)

This goes part of the way toward making sure only the appropriate directories are included as packages in a distribution. In simple cases, it will be sufficient by itself. In other cases, it might be necessary to exclude certain directories:

setup(
    packages=find_packages(
        include=['mypkg*'],
        exclude=['mypkg.xxx']),
    ...
)

This is a bit more complex than the way things used to be–where you could almost always simply say packages=find_packages() without thinking about it–but I guess that’s the price of new features and functionality.

Update: I thought of a little hack for explicitly marking non-package directories–name them with an extension (e.g., some.data). They will then become unimportable, and find_packages() already skips directories with dots in their names.

I had the hardest time configuring Travis CI for several Python 3.3 packages. I think it may have been because they’re all PEP 420 namespace packages. The strange thing is that the tests would pass for some of the packages but not others.

I ended up creating a package (which I lovingly named travisty) so my repos wouldn’t be cluttered with hundreds of superfluous commits recording my failed attempts to get things working. I got pretty frustrated and almost gave up on Travis entirely.

There was a post on Planet Python recently about problems with Python 3 and virtualenv, and I’m guessing the issue is something related to that and not Travis specifically, but I never did actually figure it out.

Instead, I tried installing my packages using Buildout (which I prefer over virtualenv for development anyway), and that magically worked. It kind of bugs me that I don’t know why it works and the bare virtualenv doesn’t, but at this point I’m just happy that it does.

Here’s the .travis.yml I ended up with:

language: python
python:
  - "3.3"
install:
  - pip install zc.buildout
  - git clone git://github.com/TangledWeb/tangled ../tangled
  - buildout
script:
  - ./bin/tangled test

The tangled test script is just a tiny wrapper around the built in unittest discovery. It’s equivalent to ./bin/python -m unittest discover my/package.

I’ve been working on a Python 3 (3.3+) only Web Framework for the past few weeks. My initial motivation was to try to build something “RESTful” that doesn’t use the concepts (or terms) “view” or “controller” at all.

That’s because I don’t even know what a “view” is (or is supposed to be be). I’ve tried to think of views as “representations” (i.e., in the sense of representing some data as a particular content type like HTML or JSON), but in the real world view functions are often used to implement business logic, and the term “view” seems misleading (“action” seems more appropriate in this case). The term view is also used by some frameworks to refer to templates (e.g., Rails), and this usage actually makes a bit more sense to me.

If you’re just throwing some code together, maybe this type of thing doesn’t matter too much, but when things get complex (as they tend to) and you’re looking for ways to keep things simple (in terms of concepts, code organization, etc), I think it can make a big difference. Your core abstractions inform (and possibly limit) your thinking; they can also limit, to an extent, what’s possible or at least easily doable.

A different way to say this is that “views” and “controllers” don’t really fit my brain, so I’m experimenting with something different. I actually tried to implement something like this on top of Pyramid at one point (pyramid_restler), but I got hung up trying to build on top of views (although it’s still useful, IMO).

So, I set out to create a new framework that uses resources and representations as its main abstractions. Resources are things that are mounted at a particular path, respond to HTTP methods, and return data that gets represented according to the requested content type (i.e., as specified by the Accept header (note to self: should look at Accept-* headers as well)).

I’ve also put some effort into making the framework “correct” in terms of HTTP status codes and other RESTful concepts. But I’m finding that it’s not so easy to create a general purpose framework that handles every scenario right out of the box. For example, it’s okay (according to the RFC) to return various status codes for a POST or a PUT depending on the circumstances, so you can’t just say, “Oh, it’s a POST, so we’ll automatically return a 201 Created.”

I’m not sure how to completely generalize HATEOAS either. For certain scenarios you can say things like, “This container resource has these items, so generate a set of links to the items and include that in the representation.” But I’m not sure how you could cover every link scenario in a generic manner. If certain constraints are enforced, maybe… (maybe I just haven’t thought hard enough about this…)

That said, I think it’s possible to create a framework that at least nudges people in the “right” direction (or at least a particular direction).

So that’s the gist of it. As it matures, I plan to post more about it (including links to the source, which will be MIT licensed). For now, I’m mostly avoiding the term RESTful and just calling it resource-oriented.

Python 3

This is the first project that I’ve really used Python 3 for, and it’s been fun playing with all the shiny new stuff (hello, built in namespace packages). I was planning to say more about the choice of Python 3 (3.3+ in particular) in this post, but I think it’s gotten a bit long already. I’ll be writing another post about that soon, including the issues I’ve run into (or lack thereof).

Update 1/13: After reading the comments and thinking about it some more, I think binascii.hexlify(os.urandom(n)) is the easiest way to generate random tokens, and random = random.SystemRandom(); ''.join(random.choice(alphabet) for _ in range(n)) is better when you need a string that contains only characters from a specific alphabet. Pyramid uses the former approach; Django uses the latter.

I’m working on a web site where I need to generate random CSRF tokens. After digging around a bit, I found os.urandom(n), which returns “a string of n random bytes suitable for cryptographic use.” Okay, that sounds good… except that it can include bytes that aren’t “web safe”.

So I needed a way to encode the output of urandom. I poked around some more and saw binascii.hexlify(data) being used for this purpose (in Pyramid). For some reason, though, I thought it would be “clever” to hash the output from urandom like so: hashlib.sha1(os.urandom(128)).hexdigest().

What I like about this is that no matter how many bytes you request from urandom (assuming more bytes means more entropy), you always end up with a 40 character string that’s safely encoded.

I’m not sure if this provides any real benefit though (in terms of increased security). Are there better ways to generate random tokens?

Another thought I had was to use bcrypt.gensalt() and use its output as is–it uses urandom to generate the initial salt, which is then hashed, and also returns a fixed number of bytes (29).

On a slightly related note, I recently needed to generate a new PIN. My first thought was to reuse a PIN I use elsewhere, but of course that’s a bad idea. My second thought was to use KeePassX to generate one. I happened to have a calculator sitting next to me (one with big buttons); I closed my eyes and banged on it a bit to generate the PIN.