loudr/pale

Rest-ish API definition library for Python web apps

pale's Issues

example_app readme is out of date

the nested resources change added an endpoint and a resource to the example app, so now its readme needs to be updated.

test coverage for context.route_kwargs

There is no test coverage for context.route_kwargs

Implement `route_prefix` for Flask adapter

Currently, if an endpoint has a route URI of /space/endpoint, there is no way of setting a common prefix such as /api/space/endpoint.

This is exemplified on GAE by having contradicting .yaml route that differs from the endpoint URI.

Wrap `uri_for` into context (and/or adaptor)

Right now, uri_for for RelativeLinkField generation must be aware of the underlying adaptor.

It would be ideal to have this method exposed from the context (via context.uri_for or context.adaptor.uri_for) which would call the appropriate underlying method with the correct argument structure.

Add `Field` and `Argument` types to paledoc

For the basics/builtins, these should be pretty straight forward, but since folks will probably implement their own field types and argument types, it probably makes sense to have documentation renderings of the description of the argument outside of the context of how it's used (i.e. right now we have IntegerArgument included with its description within the endpoint doc, but we don't have a general "this argument represents an integer" doc.)

Clean descriptions in JSON docs

Use the clean_description function in pale/docs.py to clean out the descriptions for the JSON documentation returned by generate_json_docs

Pass the request context to the `RelativeLinks` generators

I'm not super confident in how the relative links generators are to begin with, but it's clear that they need a bit more for paginating search results (i.e. the search query parameters should stay the same, but the page or offset should change for the next or previous page).

Two ways of handling this come to mind:

1. A QueryResult object that contains the original query, and thus can propagate the parameters to the link generator (and therefore also requires no changes to pale), or,
2. Pull the parameters off of the context in the link generator itself, thus requiring the context.

This prompts a larger question around relative links in general - this is one of the places where there needs to be actual logic in the resource, which makes it more of a module than a manifest document, which feels counter to the spirit of the library in the first place. Another option there is to force the underlying model to provide the link data, which is then implicit in the resource definition..

Response content_type should be set as appropriate

The serializer of the response should indicate the response type. Presently all responses are text/html.

Method for handling "PUT" requests

`context.args` should populate keys for all arguments, even if the value is None

Right now, it's omitting keys of arguments whose values are None.

Add RAML output to pale/doc.py

Add a method generate_raml_docs and associated subprocesses that will generate documentation in RAML format.

RAML spec: [https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md]

Error throwing for missing arguments breaks in webapp2

basically, the PaleBaseResponse inherited by the APIError returns a tuple that works fine for flask, but needs to be run through the response handler for webapp2 in the same way that the actual content response is built on line 287-ish of pale/endpoint.py

Filing this as a TODO note for myself, since i'm not going to fix it right now.

ResourceList does not instantiate item_type with a name

The following error is thrown when defining a ResourceList with a specific uninstantiated item_type, due to a missing name attribute.

AttributeError: 'xxx' object has no attribute 'name'

Support URI arguments on flask

Similar to the webapp2 route argument implementation found in:
https://github.com/Loudr/pale/blob/master/pale/adapters/webapp2.py#L71-L86

Field rendering by passing raw data, not relying on object lookup

Currently, field rendering requires obj and field.

It may be necessary to pass a raw value to render for a field from _render_serializable for a resource, for cases when data comes in that is not specifically on an underlying model.

update_date in example_app is causes failure on the 29th, 30th, and 31st of any month

Tests are failing due to update_date in example app.

This is because of how DateTimeModel assumes a day when update_date is called:

if day is None:
   day = self.timestamp.day

In the test, self.timestamp is utcnow, so it could be the 30th.
The tests try to update the month to February (2), which has no 29th, 30th, or 31st.

This highlights how it is not safe to assume a day of None when updating a DateTimeModel.

ERROR: test_successful_post_with_required_params (tests.test_webapp2_adapter.Webapp2AdapterTests)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Users/josh/Development/pale/tests/test_flask_adapter.py", line 50, in test_successful_post_with_required_params
    resp = self.app.post('/api/time/parse', {'month': 2})
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webtest/app.py", line 370, in post
    content_type=content_type)
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webtest/app.py", line 735, in _gen_request
    expect_errors=expect_errors)
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webtest/app.py", line 631, in do_request
    self._check_status(status, res)
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webtest/app.py", line 663, in _check_status
    res)
AppError: Bad response: 500 Internal Server Error (not 200 OK or 3xx redirect for http://localhost/api/time/parse)
<html>
  <head>
    <title>Internal Server Error</title>
    <style>
      body {
        padding: 20px;
        font-family: arial, sans-serif;
        font-size: 14px;
      }
      pre {
        background: #F2F2F2;
        padding: 10px;
      }
    </style>
  </head>
  <body>
    <h1>Internal Server Error</h1>
    <p>The server has either erred or is incapable of performing
    the requested operation.</p>
    <pre>Traceback (most recent call last):
  File &quot;/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py&quot;, line 1535, in __call__
    rv = self.handle_exception(request, response, e)
  File &quot;/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py&quot;, line 1529, in __call__
    rv = self.router.dispatch(request, response)
  File &quot;/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py&quot;, line 1278, in default_dispatcher
    return route.handler_adapter(request, response)
  File &quot;/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py&quot;, line 1102, in __call__
    return handler.dispatch()
  File &quot;/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py&quot;, line 572, in dispatch
    return self.handle_exception(e, self.app.debug)
  File &quot;/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py&quot;, line 570, in dispatch
    return method(*args, **kwargs)
  File &quot;/Users/josh/Development/pale/pale/adapters/webapp2.py&quot;, line 19, in pale_handler
    return pale_endpoint._execute(self.request)
  File &quot;/Users/josh/Development/pale/pale/endpoint.py&quot;, line 170, in _execute
    raise e
ValueError: day is out of range for month
</pre>
  </body>
</html>
-------------------- >> begin captured logging << --------------------
root: INFO: extracted endpoints: [<tests.example_app.api.endpoints.CurrentTimeEndpoint object at 0x106d0eb50>, <tests.example_app.api.endpoints.ParseTimeEndpoint object at 0x106d0ed50>, <tests.example_app.api.endpoints.TimeRangeEndpoint object at 0x106d10050>]
root: INFO: adding endpoint current_time to webapp!
root: INFO: current_time
root: INFO: created route: <Route('/api/time/current', <class 'pale.adapters.webapp2.current_time'>, name='current_time', defaults={}, build_only=False)>
root: INFO: adding endpoint parse_time to webapp!
root: INFO: parse_time
root: INFO: created route: <Route('/api/time/parse', <class 'pale.adapters.webapp2.parse_time'>, name='parse_time', defaults={}, build_only=False)>
root: INFO: adding endpoint time_range_now_plus_duration to webapp!
root: INFO: time_range_now_plus_duration
root: INFO: created route: <Route('/api/time/range', <class 'pale.adapters.webapp2.time_range_now_plus_duration'>, name='time_range_now_plus_duration', defaults={}, build_only=False)>
root: INFO: app router state: <Router([<Route('/api/time/current', <class 'pale.adapters.webapp2.current_time'>, name='current_time', defaults={}, build_only=False)>, <Route('/api/time/parse', <class 'pale.adapters.webapp2.parse_time'>, name='parse_time', defaults={}, build_only=False)>, <Route('/api/time/range', <class 'pale.adapters.webapp2.time_range_now_plus_duration'>, name='time_range_now_plus_duration', defaults={}, build_only=False)>])>
root: ERROR: day is out of range for month
root: ERROR: day is out of range for month
Traceback (most recent call last):
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py", line 1535, in __call__
    rv = self.handle_exception(request, response, e)
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py", line 1529, in __call__
    rv = self.router.dispatch(request, response)
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py", line 1278, in default_dispatcher
    return route.handler_adapter(request, response)
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py", line 1102, in __call__
    return handler.dispatch()
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py", line 572, in dispatch
    return self.handle_exception(e, self.app.debug)
  File "/Users/josh/Development/pale/venv/lib/python2.7/site-packages/webapp2.py", line 570, in dispatch
    return method(*args, **kwargs)
  File "/Users/josh/Development/pale/pale/adapters/webapp2.py", line 19, in pale_handler
    return pale_endpoint._execute(self.request)
  File "/Users/josh/Development/pale/pale/endpoint.py", line 170, in _execute
    raise e
ValueError: day is out of range for month

Exceptions during unicode argument parsing

When StringArgument was given a unicode encoded value, the cast to str is failing and creating an uncaught exception.

StringEnumArgument

Support string arguments with a finite set of allowable values.

Better solution for catching OPTIONS requests

• Currently OPTIONS is manually caught and the response headers are updated.

This is in place of creating an alternate endpoint with the _http_method OPTIONS for all existing endpoints.

Support for JSON serialized body arguments

Support CORS

nuff said

Add optional permissions check for doc.py in generate_json_docs

Currently, the generate_json_docs method does not restrict which documentation is returned. Once issue #55 is closed, the new generate_raml_docs method will allow for restricting documentation on endpoints based on the 1) the user's context and 2) whether the endpoint requires permission.

Edit generate_json_docs so that it also allows for the same kind of controlled access.

Tidy up the JSON request body handling

#20 was a bit haphazard, and might require a bit more tidying and thought.

As mentioned in the post-mortem comments there, we need to make sure that we're checking Content-Type, and developing a reasonable strategy for error handling. My knee-jerk reaction is that if the body content isn't parsable by whichever parser we infer from Content-Type, then we should actually raise a 422 Unprocessable Entity here, instead of propagating the request any further down the pipe.

Field.render support for `dict` objects

This enables the use case where a passed resource is in fact a dict instead of a proper instantiated object.

_pre_response_handlers should be called in Exception cases as well

This may be solved more simply in a true pale solution of #13.

Our current issue is that ArgumentErrors call API.UnprocessableEntity (HTTP:422) which bypasses the _pre_response_handlers. This may be the desired behavior, but it leaves us unable to send a CORs header when there are argument errors.

Add RAML/JSON docs example to example app

Implement an endpoint that can return RAML or JSON documentation

Timestamp Field Rendering

It would be nice to specify a format argument:

• ISO
• Custom
• Timestamp Integer

class TimestampField(StringField):
    """A field for timestamp strings."""
    value_type = 'timestamp'

    # TODO - timestamp field rendering