Merge lp:~leonardr/wadllib/what-kind-of-link into lp:wadllib

[Leonard Richardson]

Currently, wadllib assumes that all <link>s are links to other WADL-controlled resources. If you try to follow a link that's just a random link to some URL, you'll get an exception. There is no easy way to examine a link beforehand to see what kind of link it is.

This branch adds the '.link' property to Parameter, which lets you get the Link object under consideration. It adds a '.can_follow' property to Link, which lets you see whether you can handle the link with wadllib or whether you need to use a general HTTP client. For convenience, it also adds a '.follow' property to Link.

[j.c.sackett (jcsackett)]

Leonard--

This looks like a good improvement.

I have two suggestions (not requirements):

> === modified file 'src/wadllib/README.txt'
> --- src/wadllib/README.txt 2010-05-03 15:58:32 +0000
> +++ src/wadllib/README.txt 2011-02-03 15:16:29 +0000
> @@ -274,6 +273,57 @@
> >>> new_team.type_url
> 'http://api.launchpad.dev/beta/#team'
>
> +Examining links
> +---------------
> +
> +The 'linked_resource' property of a parameter lets you follow a link
> +to another object. The 'link' property of a parameter lets you examine
> +links before following them.
> +
> + >>> import simplejson
> + >>> links_wadl = application_for('links-wadl.xml')
> + >>> service_root = links_wadl.get_resource_by_path('')
> + >>> representation = simplejson.dumps(
> + ... {'scalar_value': 'foo',
> + ... 'known_link': 'http://known/',
> + ... 'unknown_link': 'http://unknown/'})
> + >>> bound_root = service_root.bind(representation)
> +
> + >>> print bound_root.get_parameter("scalar_value").link
> + None
> +
> + >>> known_resource = bound_root.get_parameter("known_link")
> + >>> link_to_known_resource = known_resource.link
> + >>> unknown_resource = bound_root.get_parameter("unknown_link")
> + >>> link_to_unknown_resource = unknown_resource.link
> +
> + >>> print link_to_known_resource.can_follow
> + True
> + >>> print link_to_unknown_resource.can_follow
> + False

This might read easier without assigning the .link to a variable. e.g.

+ >>> known_resource = bound_root.get_parameter("known_link")
+ >>> unknown_resource = bound_root.get_parameter("unknown_link")
+
+ >>> print known_resource.link.can_follow
+ True
+ >>> print unknown_resource.link.can_follow

I only suggest this because I think it's a clearer indication of using the "link" property, which is the ostensible point of this section of the doc test.

>=== modified file 'src/wadllib/application.py'
>--- src/wadllib/application.py 2010-05-03 16:15:19 +0000
>+++ src/wadllib/application.py 2011-02-03 15:16:29 +0000
>@@ -962,6 +976,28 @@
> self.parameter = parameter
> self.tag = link_tag
>
>+ @property
>+ def follow(self):
>+ """Follow the link to another Resource."""
>+ if not self.can_follow:
>+ raise WADLError("Cannot follow a link when the target has no "
>+ "WADL description. Try using a general HTTP "
>+ "client instead.")
>+ return self.resolve_definition()
>+
>+ @property
>+ def can_follow(self):
>+ """Can this link be followed within wadllib?
>+
>+ wadllib can follow a link if it points to a resource that has
>+ a WADL definition.
>+ """
>+ try:
>+ definition_url = self._get_definition_url()
>+ return True
>+ except WADLError:
>+ return False

It might make a bit more sense to return True as the last statement of this property, rather than returning True in the "try" clause. i.e.:

>+ try:
>+ definition_url = self._get_definition_url()
>+ except WADLError:
>+ return False
>+ return True

Min...

review: Approve (code*)

[lp:~leonardr/wadllib/what-kind-of-link]

20. By Leonard Richardson on 2011-02-03

This is actually version 1.1.9. Now trying to merge in version 1.1.8, which was never merged with trunk.

21. By Leonard Richardson on 2011-02-03

Merge from trunk.

22. By Leonard Richardson on 2011-02-03

Minor changes in response to feedback.

23. By Leonard Richardson on 2011-02-03

Added the 'parameters' method.

[Curtis Hovey (sinzui)]

This looks good to land.

review: Approve (code)

[Francis J. Lacoste (flacoste)]

Turns out that the file "links-wadl.xml" wasn't added to the branch :-(

I'll try to reconstruct it from the test, or will remove the test.

[Francis J. Lacoste (flacoste)]

That seems to do the trick:

=== added file 'src/wadllib/tests/data/links-wadl.xml'
--- src/wadllib/tests/data/links-wadl.xml 1970-01-01 00:00:00 +0000
+++ src/wadllib/tests/data/links-wadl.xml 2011-11-25 18:53:12 +0000
@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="http://research.sun.com/wadl/2006/10"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xsi:schemaLocation="http://research.sun.com/wadl/2006/10/wadl.xsd">
+ <resources base="http://www.example.com/">
+ <resource path="" type="#service-root"/>
+ </resources>
+
+ <resource_type id="service-root">
+ <method name="GET" id="service-root-get">
+ <response>
+ <representation href="#service-root-json"/>
+ </response>
+ </method>
+ </resource_type>
+
+ <representation id="service-root-json" mediaType="application/json">
+ <param style="plain" path="$['scalar_value']" name="scalar_value" />
+ <param style="plain" path="$['known_link']" name="known_link">
+ <link resource_type="#service-root"/>
+ </param>
+ <param style="plain" path="$['unknown_link']" name="unknown_link">
+ <link />
+ </param>
+ </representation>
+</application>

=== modified file 'src/wadllib/NEWS.txt'
--- src/wadllib/NEWS.txt	2011-02-03 15:46:06 +0000
+++ src/wadllib/NEWS.txt	2011-02-03 16:29:49 +0000
@@ -2,6 +2,16 @@
 NEWS for wadllib
 ================
 
+1.2.0 (2011-02-03)
+==================
+
+- It's now possible to examine a link before following it, to see
+  whether it has a WADL description or whether it needs to be fetched
+  with a general HTTP client.
+
+- It's now possible to iterate over a resource's Parameter objects
+  with the .parameters() method.
+
 1.1.8 (2010-10-27)
 ==================
 

=== modified file 'src/wadllib/README.txt'
--- src/wadllib/README.txt	2010-05-03 15:58:32 +0000
+++ src/wadllib/README.txt	2011-02-03 16:29:49 +0000
@@ -43,7 +43,6 @@
    ...                        "http://api.launchpad.dev/beta/")
 
 
-===============
 Link navigation
 ===============
 
@@ -139,12 +138,13 @@
 test data.
 
    >>> bound_service_root = bind_to_testdata(service_root, 'root')
+   >>> sorted([param.name for param in bound_service_root.parameters()])
+   ['bugs_collection_link', 'people_collection_link']
    >>> sorted(bound_service_root.parameter_names())
    ['bugs_collection_link', 'people_collection_link']
    >>> [method.id for method in bound_service_root.method_iter]
    ['service-root-get']
 
-
 Now the bound resource object has a JSON representation, and now
 'people_collection_link' makes sense. We can follow the
 'people_collection_link' to a new Resource object.
@@ -274,6 +274,55 @@
    >>> new_team.type_url
    'http://api.launchpad.dev/beta/#team'
 
+Examining links
+---------------
+
+The 'linked_resource' property of a parameter lets you follow a link
+to another object. The 'link' property of a parameter lets you examine
+links before following them.
+
+    >>> import simplejson
+    >>> links_wadl = application_for('links-wadl.xml')
+    >>> service_root = links_wadl.get_resource_by_path('')
+    >>> representation = simplejson.dumps(
+    ...     {'scalar_value': 'foo',
+    ...      'known_link': 'http://known/',
+    ...      'unknown_link': 'http://unknown/'})
+    >>> bound_root = service_root.bind(representation)
+
+    >>> print bound_root.get_parameter("scalar_value").link
+    None
+
+    >>> known_resource = bound_root.get_parameter("known_link")
+    >>> unknown_resource = bound_root.get_parameter("unknown_link")
+
+    >>> print known_resource.link.can_follow
+    True
+    >>> print unknown_resource.link.can_follow
+    False
+
+A link whose type is unknown is a link to a resource not described by
+WADL. Following this link using .linked_resource or .link.follow will
+cause a wadllib error. You'll need to follow the link using a general
+HTTP library or some other tool.
+
+    >>> known_resource.link.follow
+    <wadllib.application.Resource object ...>
+    >>> known_resource.linked_resource
+    <wadllib.application.Resource object ...>
+
+    >>> unknown_resource.link.follow
+    Traceback (most recent call last):
+    ...
+    WADLError: Cannot follow a link when the target has no WADL
+    description. Try using a general HTTP client instead.
+
+    >>> unknown_resource.linked_resource
+    Traceback (most recent call last):
+    ...
+    WADLError: Cannot follow a link when the target has no WADL
+    description. Try using a general HTTP client instead.
+
 Creating a Resource from a representation definition
 ====================================================
 
@@ -314,7 +363,6 @@
    ...     'total_size', 'application/json').get_value()
    63
 
-======================
 Resource instantiation
 ======================
 
@@ -351,7 +399,6 @@
 you've already processed the representation, pass in False for the
 'representation_needs_processing' argument.
 
-   >>> import simplejson
    >>> processed_limi_data = simplejson.loads(unicode(limi_data))
    >>> bound_limi = Resource(wadl, "http://api.launchpad.dev/beta/~limi",
    ...     "http://api.launchpad.dev/beta/#person", processed_limi_data,
@@ -419,7 +466,7 @@
    None
 
 Data type conversion
-====================
+--------------------
 
 The values of date and dateTime parameters are automatically converted to
 Python datetime objects.
@@ -464,7 +511,6 @@
    >>> print bound_root.get_parameter('a_datetime').get_value()
    None
 
-=======================
 Representation creation
 =======================
 
@@ -535,7 +581,6 @@
    ...
    ValueError: Unsupported media type: 'text/unknown'
 
-=======
 Options
 =======
 
@@ -565,7 +610,6 @@
    'has_options': valid values are: "Value 1", "Value 2"
 
 
-================
 Error conditions
 ================
 

=== modified file 'src/wadllib/application.py'
--- src/wadllib/application.py	2010-05-03 16:15:19 +0000
+++ src/wadllib/application.py	2011-02-03 16:29:49 +0000
@@ -388,6 +388,19 @@
                     return method
         return None
 
+    def parameters(self, media_type=None):
+        """A list of this resource's parameters.
+
+        :param media_type: Media type of the representation definition
+            whose parameters are being named. Must be present unless
+            this resource is bound to a representation.
+
+        :raise NoBoundRepresentationError: If this resource is not
+            bound to a representation and media_type was not provided.
+        """
+        return self._find_representation_definition(
+            media_type).params(self)
+
     def parameter_names(self, media_type=None):
         """A list naming this resource's parameters.
 
@@ -914,8 +927,22 @@
                 for option_tag  in self.tag.findall(wadl_xpath('option'))]
 
     @property
+    def link(self):
+        """Get the link to another resource.
+
+        The link may be examined and, if its type is of a known WADL
+        description, it may be followed.
+
+        :return: A Link object, or None.
+        """
+        link_tag = self.tag.find(wadl_xpath('link'))
+        if link_tag is None:
+            return None
+        return Link(self, link_tag)
+
+    @property
     def linked_resource(self):
-        """Find the type of resource linked to by this parameter.
+        """Follow a link from this parameter to a new resource.
 
         This only works for parameters whose WADL definition includes a
         <link> tag that points to a known WADL description.
@@ -923,10 +950,10 @@
         :return: A Resource object for the resource at the other end
         of the link.
         """
-        link_tag = self.tag.find(wadl_xpath('link'))
-        if link_tag is None:
+        link = self.link
+        if link is None:
             raise ValueError("This parameter isn't a link to anything.")
-        return Link(self, link_tag).resolve_definition()
+        return link.follow
 
 class Option(WADLBase):
     """One of a set of possible values for a parameter."""
@@ -949,7 +976,7 @@
     """A link from one resource to another.
 
     Calling resolve_definition() on a Link will give you a Resource for the
-    type of resource linked to.
+    type of resource linked to. An alias for this is 'follow'.
     """
 
     def __init__(self, parameter, link_tag):
@@ -962,6 +989,28 @@
         self.parameter = parameter
         self.tag = link_tag
 
+    @property
+    def follow(self):
+        """Follow the link to another Resource."""
+        if not self.can_follow:
+            raise WADLError("Cannot follow a link when the target has no "
+                            "WADL description. Try using a general HTTP "
+                            "client instead.")
+        return self.resolve_definition()
+
+    @property
+    def can_follow(self):
+        """Can this link be followed within wadllib?
+
+        wadllib can follow a link if it points to a resource that has
+        a WADL definition.
+        """
+        try:
+            definition_url = self._get_definition_url()
+        except WADLError:
+            return False
+        return True
+
     def _definition_factory(self, id):
         """Turn a resource type ID into a ResourceType."""
         return Resource(

=== modified file 'src/wadllib/version.txt'
--- src/wadllib/version.txt	2011-02-03 15:46:06 +0000
+++ src/wadllib/version.txt	2011-02-03 16:29:49 +0000
@@ -1,1 +1,1 @@
-1.1.8
+1.2.0