The following results might be useful.  The "gnome-fs-directory" icon exists in
the icon theme, but the "gnome-eyes" icon is in the pixmaps folder.

  >>> import gtk
  >>> icon_theme = gtk.icon_theme_get_default()
  >>> pixbuf = icon_theme.load_icon('gnome-fs-directory', 24, 0)
  >>> pixbuf.get_width(), pixbuf.get_height()
  (24, 24)
  >>> pixbuf = icon_theme.load_icon('gnome-fs-directory', 256, 0)
  >>> pixbuf.get_width(), pixbuf.get_height()
  (256, 256)
  >>> pixbuf = icon_theme.load_icon('gnome-eyes', 24, 0)
  >>> pixbuf.get_width(), pixbuf.get_height()
  (48, 48)
  >>> pixbuf = icon_theme.load_icon('gnome-eyes', 256, 0)
  >>> pixbuf.get_width(), pixbuf.get_height()
  (240, 240)
  >>>

The code responsible for this is in gtkicontheme.c:

  if (icon_info->scale < 0.0)
    {
      gint image_size = MAX (image_width, image_height);
      if (image_size > 0)
	icon_info->scale = icon_info->desired_size / image_size;
      else
	icon_info->scale = 1.0;
      
      if (icon_info->dir_type == ICON_THEME_DIR_UNTHEMED)
	icon_info->scale = MAX (icon_info->scale, 1.0);
    }

It would have to be changed to 

 if (icon_info->scale < 0.0)
    {
      gint image_size = MAX (image_width, image_height);
      if (image_size > 0)
	icon_info->scale = icon_info->desired_size / (gdouble)image_size;
      else
	icon_info->scale = 1.0;     
     }

but I don't know enough about this code to judge whether that would be
an improvement, or if the current code works as intended and is just
underdocumented... I'll ask Owen on Monday

The documentation for gtk_icon_theme_load_icon() says the following:
 * @size: the desired icon size. The resulting icon may not be
 *        exactly this size; see gtk_icon_info_load_icon().
 ...
 * Looks up an icon in an icon theme, scales it to the given size
 * and renders it into a pixbuf. This is a convenience function;
 * if more details about the icon are needed, use
 * gtk_icon_theme_lookup_icon() followed by gtk_icon_info_load_icon().

And for gtk_icon_info_load_icon(), it says the following:
 * Note that the resulting
 * pixbuf may not be exactly this size; an icon theme may have icons
 * that differ slightly from their nominal sizes, and in addition GTK+
 * will avoid scaling icons that it considers sufficiently close to the
 * requested size. (This maintains sharpness.)

So I'd say that the result for rendering "gnome-eyes" at size 256 matches the
documentation (240 pixels is close to 256), but returning a 48x48 pixbuf when
size 24 is requested sounds like a bug.

There is discussion from:

http://mail.gnome.org/archives/gtk-devel-list/2003-May/msg00055.html

It looks like I might have simplified even a bit further from what
was discussed there, but it's along the same lines.

The gnome-eyes example above doesn't make a lot of sense to me;
as I read the code, GTK+ never scales a unthemed icon up but scales down
if requested

I'd consider this bug at most 'docs'.

Its the opposite, Owen. The code refuses to scale down. It does scale up, but
the scale factor is (mis-)calculated using int math instead of floating point, 
thus we don't exactly reach the desired size. Talking to alex earlier, he
doesn't remember any particular reason to refuse to scale unthemed icons down,
and considers the rounding issue to be an oversight.

Likely I just got the MAX/MIN backwards. If you read the discussion above,
especially:

 http://mail.gnome.org/archives/gtk-devel-list/2003-May/msg00060.html

You'll see I was thinking "down but not up". I suspect the scale factor
was also a bug, while scaling up by integer factors looks a bit better,
it still looks crappy, and we do use filtered scaling.

2004-10-04  Matthias Clasen  <mclasen@redhat.com>

	* gtk/gtkicontheme.c (icon_info_ensure_scale_and_pixbuf): 
	Make the code work as intended for unthemed icons; don't scale
	them up too much. Allow to scale them down, and do so 
	exactly.  (#154142, Ross Burton)
	(gtk_icon_info_load_icon): Amend docs.