Re: URI Template -04 Implementation Notes

On 2 June 2010 05:00, Joe Gregorio <joe@bitworking.org> wrote:

> I've committed an incomplete implementation of the -04 spec
> in Python to svn along with test cases taken from the spec.
>
>   http://code.google.com/p/uri-templates/source/detail?r=57
>
> The tests themselves are taken directly from the spec and
> are stored in a JSON file, to make it easier to reuse them.
> (Well, almost taken verbatim from the spec, below I list
> the cases that were either inconsistent or looked wrong
> and how I changed them.) The code does not implement
> 'partial' modifiers.
>

Cool (the JSON part especially).


> Here are my notes:
>
> 1. The spec is fiddly, by which I mean that while the rules
>   for handling semicolon, query parameter, path and label
>   expansions all make sense on their own, they are all
>   slightly different from each other. It makes for a lot
>   more code than I expected, and is fairly tedious to implement.
>   I'm not sure that the amount of complexity is warranted.
>

>
  To simplify I would like to see label and semicolon path
>   style expansions dropped. I also believe the '+' modifier could
>   be dropped without loss of generality.
>


Please don't drop label expansion.  I added this to Routes (as used by
Pylons) and it enables applications to simplify their routing quite
significantly.  It's the optionality that makes them not redundant (unless
you want to revive the prefix operator!).  I'm not bothered by the other
features, but are there more consistent ways of specifying them?

But yes, it was fiddly and annoying.



> 2. From the spec, this rule isn't consistent:
>      ["{?x,y,empty}", "?x=1024&y=768&empty="],
>


Yes, it seems we have both concluded that the trailing '=' above is needed
(missing in the spec).



> 3. One of these is inconsistent
>     ["X{.empty}", "X."],
>     ["x{?empty_list}", "x"],
>


My implementation manages both of these.  Perhaps (it was a while ago) it
was at the cost of a special case in the code though.  What would you change
them to?



> 4. Also inconsistent
>     ["{;list}", ";val1,val2,val3"],
>     ["x{;name=none}", "x;name=Fred,Wilma,Pebbles"],
>


Yes, I disabled the latter test.



> 5. I tried working through the empty and default cases
>    (section 2.5) but came across so many cases that
>    seemed to disagree with previous examples or the wording
>    of the spec that I began to suspect the section was incomplete.
>    Here is the list of test cases I had collected and believe are wrong,
>    before I stopped:
>
>     ["x{empty_list=_}y", "xy"],
>     ["x{empty_list+=_}y", "xempty_list._y"],
>     ["x{empty_keys=_}y", "xy"],
>     ["x{empty_keys+=_}y", "xempty_keys._y"],
>     ["x{?empty}", "x?empty="],
>     ["x{?empty=none}", "x?empty="],
>     ["x{?empty_list*=none}", "x?none"],
>     ["x{?empty_list+=none}", "x?empty_list.none"],
>     ["x{?empty_keys*=none}", "x?none"],
>     ["x{?empty_keys+=none}", "x?empty_keys.none"],
>
>  I believe many of these cases with defaults are ones that Mike Burrows
>  raised earlier.
>


I pass several of those; I got away with disabling out just these tests:


    ('x{empty_list=_}y',       'xy'),
    ('x{empty_keys=_}y',       'xy'),
    ('x{;name=none}',          'x;name=Fred,Wilma,Pebbles'),
    ('x{;favs=none}',          'x;favs=color,red,volume,high'),
    ('x{;empty_list=none}',    'x;empty_list=none'),
    ('x{;empty_keys=none}',    'x;empty_keys=none'),



> 6. I've come across yet another case where going in reverse, from a
> template
>   to matching, would be useful. How about carving out () at the end of
>   an expression as a place where a regex could be stored for applications
>   that want to use a template for matching against incoming requests, but
>   just state that the allowed regex's and matching algorithms are outside
>   the scope of the current spec?
>


That could be done without changing the spec at this stage.  Routes (for
example) has a syntax that allows a regex to be embedded - e.g.
"{foo:[a-z]+}" - but it's usually much better to provide these as separate
parameters to the route definition.  Implementers are free to do something
similar now with the URI Template spec as it stands, and meanwhile the spec
can progress towards approval.

It should be sufficient for servers to be able to generate URI Templates
from their native formats (this is what described_routes does with templates
from Routes or Rails); in the worst case they can be maintained separately.
So far I've manage to avoid doing anything that will encourage clients to
parse URIs.

In summary, there are only a few broken tests, the complexity is slightly
annoying but still manageable (assuming the broken tests can be fixed to
something sensible), and I for one would still press on towards approval.
Meanwhile, feel free to get what you can from


http://bitbucket.org/asplake/described_routes/src/tip/described_routes/uri_template.py

http://bitbucket.org/asplake/described_routes/src/tip/tests/test_uri_template.py

When the spec is stable it would be nice to release either package (I really
don't mind whose) to pypi.


>  Thanks,
>   -joe
>
>
Regards,
Mike
mjb@asplake.co.uk
http://positiveincline.com
http://twitter.com/asplake