Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ysimonson/oz

A set of tools that run on top of the tornado framework.
https://github.com/ysimonson/oz

Last synced: 3 months ago
JSON representation

A set of tools that run on top of the tornado framework.

Awesome Lists containing this project

README 

        
# DEPRECATION NOTICE



This version of Oz is deprecated. Much of the functionality has been

supplanted both by improvements in tornado itself and in its surrounding

ecosystem.



For a modern rehash, please see [the new oz](http://github.com/dailymuse/oz).



# about

Oz is a set of classes for augmenting the functionality of the Tornado web

framework. I will give you an e-high-five if you understand the name's

reference.



## django-style error messages

DjangoErrorMixin provides pretty Django-like error messages when an exception

occurs. This is very useful when you're developing your web app, but not a good

idea to run in production. Consequently, this tool only runs when the setting

'debug' is set to True.



To use it, first enable debug in the settings:



    settings = {

        'debug': True,

    }

    

    app = tornado.web.Application([

        (r'/', HelloWorldHandler),

    ], **settings)

    

    http_server = tornado.httpserver.HTTPServer(app)

    http_server.listen(options.port)

    tornado.ioloop.IOLoop.instance().start()

    

Then in your handler, add the mixin:



    class HelloWorldHandler(DjangoErrorMixin, RequestHandler):

        def get(self):

            #This will throw an AssertionError to display the pretty error page

            assert False

            

            self.write('hello, world!')



If your application also defines a 'output_type_override' setting, the setting's

value will be used as a parameter key that clients can use to change the error

output format. For example, if you set 'output_type_override' to 'error_output',

then a client upon making a request can set a GET or POST parameter error_output

to either 'txt', 'verbose_txt' or 'html' to change the error output formatting.

For example, a request to http://localhost:8080/?error_output=verbose_txt will

provide a textual version of the Django error page instead. This is useful if

you want the debugging richness of the Django error page, but your client cannot

view html appropriately. Setting the format to txt will provide a simple Python

stack trace. verbose_txt is roughly a textual equivalent of the Django error

page. html is the default Dango error page output.



## http basic authentication

BasicAuthMixin enables HTTP basic authentication. The tool is very flexible,

as it uses a callback to check the credentials.



Add the mixin in your handler and call self.get_authenticated_user() (similar to

the auth mixins provided by Tornado) when you want to authenticate the request:



    class HelloWorldHandler(BasicAuthMixin, RequestHandler):

        def get(self):

            if not self.get_authenticated_user(auth_callback, 'realm'):

                return False

            

            self.write('hello, world!')

            

The first argument for get_authenticated_user() is the callback method you wish

to use for authentication. The second argument is the realm. An example callback

method:



    def auth_callback(request, realm, username, password):

        if username == 'foo' and password == 'bar':

            request.user_id = 1

            return True

        else:

            return False

            

The method must a boolean stating whether the authentication succeeded. It takes

in the RequestHandler object as the first argument in case you want to add some

useful attributes (in this case, we're adding user_id).



If authentication fails, the RequestHandler will finish() and no further code

will be executed. If it succeeds, the authenticated user will be available via

RequestHandler.get_current_user().



You can also use the basic_auth decorator for methods that you wish to protect

as an alternate use case for the mixin. Example:



    class HelloWorldHandler(BasicAuthMixin, RequestHandler):

        @basic_auth(auth_callback, 'realm')

        def get(self):

            self.write('hello, world!')



This is equivalent to the previous implementation example.



## argument patch

ArgumentPatchMixin replaces the default implementation of

RequestHandler.get_argument(), which returns GET/POST parameters sent with the

request. If a required argument is missing, it throws an HTTP code 400 (bad

request) instead of a 404 (not found). I think this makes more sense.



To use it, all you have to do is add the mixin:



    class HelloWorldHandler(ArgumentPatchMixin, RequestHandler):

        def get(self):

            name = self.get_argument('name')

            self.write('hello, %s!' % name)

            

## notes

 * Always put the mixins before the RequestHandler on the inheritance list. This

   will work:

   

       class HelloWorldHandler(ArgumentPatchMixin, RequestHandler):

           ...

           

   Whereas this will *NOT* work:

   

       class HelloWorldHandler(RequestHandler, ArgumentPatchMixin):

           ...

           

 * You can mix and match multiple mixins. This will work fine:

 

       class HelloWorldHandler(BasicAuthMixin, DjangoErrorMixin,

           ArgumentPatchMixin, RequestHandler):

           ...