From 5761305fc5cda18cf10654aa0f70387afd65fc4f Mon Sep 17 00:00:00 2001 From: Marcel Hellkamp Date: Thu, 15 Jul 2010 16:23:03 +0200 Subject: Documentation fixes ported from 0.8.1. --- apidoc/changelog.rst | 6 ++-- apidoc/faq.rst | 4 --- apidoc/index.rst | 30 ++++++++++++---- apidoc/recieps.rst | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++ bottle.py | 5 +-- 5 files changed, 127 insertions(+), 17 deletions(-) create mode 100644 apidoc/recieps.rst diff --git a/apidoc/changelog.rst b/apidoc/changelog.rst index 7c7344a..b6715b8 100644 --- a/apidoc/changelog.rst +++ b/apidoc/changelog.rst @@ -5,12 +5,11 @@ Release Notes and Changelog =========================== -Release 0.7 +Release 0.8 =========== .. rubric:: API changes - These changes may break compatibility with previous versions. * The built-in Key/Value database is not available anymore. It is marked deprecated since 0.6.4 @@ -18,9 +17,8 @@ These changes may break compatibility with previous versions. * Regular expressions must be encapsulated with ``#``. In 0.6 all non-alphanumeric characters not present in the regular expression were allowed. * Regular expressions not part of a route wildcard are escaped automatically. You don't have to escape dots or other regular control characters anymore. In 0.6 the whole URL was interpreted as a regular expression. You can use anonymous wildcards (``/index:#(\.html)?#``) to achieve a similar behaviour. - * Wildcards are escaped with a second colon (``/path/::not_a_wildcard``). -* The ``BreakTheBottle`` exception is gone. Use :class:`HTTPResponse`` instead. +* The ``BreakTheBottle`` exception is gone. Use :class:`HTTPResponse` instead. * The :class:`SimpleTemplate` engine escapes HTML special characters in ``{{bad_html}}`` expressions automatically. Use the new ``{{!good_html}}`` syntax to get old behaviour (no escaping). * The :class:`SimpleTemplate` engine returns unicode strings instead of lists of byte strings. * ``bottle.optimize()`` and the automatic route optimization is obsolete. diff --git a/apidoc/faq.rst b/apidoc/faq.rst index b57a775..893e1d1 100644 --- a/apidoc/faq.rst +++ b/apidoc/faq.rst @@ -32,10 +32,6 @@ Bottle searches in ``./`` and ``./views/`` for templates. In a mod_python_ or mo bottle.TEMPLATE_PATH.insert(0,'/absolut/path/to/templates/') -or change the working directory:: - - os.chdir(os.path.dirname(__file__)) - so bottle searches the right paths. Dynamic Routes and Slashes diff --git a/apidoc/index.rst b/apidoc/index.rst index ae62f69..2ed011e 100755 --- a/apidoc/index.rst +++ b/apidoc/index.rst @@ -26,7 +26,7 @@ Bottle is a fast, simple and lightweight WSGI_ micro web-framework for Python_. * **Routing:** Requests to function-call mapping with support for clean and dynamic URLs. * **Templates:** Fast and pythonic :ref:`build-in template engine ` and support for mako_, jinja2_ and cheetah_ templates. * **Utilities:** Convenient access to form data, file uploads, cookies, headers and other HTTP related metadata. -* **Server:** Build-in HTTP development server and support for paste_, fapws3_, flup_, cherrypy_ or any other WSGI_ capable HTTP server. +* **Server:** Build-in HTTP development server and support for paste_, fapws3_, `Google App Engine `_, cherrypy_ or any other WSGI_ capable HTTP server. .. rubric:: Example: "Hello World" in a bottle @@ -48,20 +48,25 @@ Bottle is a fast, simple and lightweight WSGI_ micro web-framework for Python_. Install the latest stable release via PyPi_ (``easy_install -U bottle``) or download `bottle.py`__ (unstable) into your project directory. There are no hard [1]_ dependencies other than the Python standard library. Bottle runs with **Python 2.5+ and 3.x** (using 2to3) -Documentation +User's Guide =============== -The documentation is a work in progress. If you have questions not answered here, please check the :doc:`faq`, file a ticket at bottles issue_tracker_ or send an e-mail to the `mailing list `_. +Start here if you want to learn how to use the bottle framework for web development. If you have any questions not answered here, feel free to ask the `mailing list `_. .. toctree:: :maxdepth: 2 tutorial - recieps + stpl faq + +API Documentation +================== +Looking for a specific function, class or method? These chapters cover all the interfaces provided by the Framework and explain how to use them. + +.. toctree:: + :maxdepth: 2 + api - stpl - changelog - development Tutorials and Resources ======================= @@ -70,7 +75,18 @@ Tutorials and Resources :maxdepth: 2 tutorial_app + recieps + +Development and Contribution +============================ + +These chapters are intended for developers interested in the bottle development and release workflow. +.. toctree:: + :maxdepth: 2 + + changelog + development Licence diff --git a/apidoc/recieps.rst b/apidoc/recieps.rst new file mode 100644 index 0000000..93fbf6f --- /dev/null +++ b/apidoc/recieps.rst @@ -0,0 +1,99 @@ +.. module:: bottle + +.. _beaker: http://beaker.groovie.org/ +.. _mod_python: http://www.modpython.org/ +.. _mod_wsgi: http://code.google.com/p/modwsgi/ +.. _werkzeug: http://werkzeug.pocoo.org/documentation/dev/debug.html +.. _paste: http://pythonpaste.org/modules/evalexception.html +.. _pylons: http://pylonshq.com/ + +Recieps +============= + +This is a collection of code snippets and examples for common use cases. + +Keeping track of Sessions +---------------------------- + +There is no build in support for sessions because there is no *right* way to do it (in a micro framework). Depending on requirements and environment you could use beaker_ middleware with a fitting backend or implement it yourself. Here is an example for beaker sessions with a file-based backend:: + + import bottle + from beaker.middleware import SessionMiddleware + + session_opts = { + 'session.type': 'file', + 'session.cookie_expires': 300, + 'session.data_dir': './data', + 'session.auto': True + } + app = SessionMiddleware(bottle.app(), session_opts) + + @bottle.route('/test') + def test(): + s = bottle.request.environ.get('beaker.session') + s['test'] = s.get('test',0) + 1 + s.save() + return 'Test counter: %d' % s['test'] + + bottle.run(app=app) + +Debugging with Style: Debugging Middleware +-------------------------------------------------------------------------------- + +Bottle catches all Exceptions raised in your app code to prevent your WSGI server from crashing. If the build-in :func:`debug` mode is not enough and you need exceptions to propagate to a debugging middleware, you can turn off this behaviour:: + + import bottle + app = bottle.app() + app.catchall = False #Now most exceptions are re-raised within bottle. + myapp = DebuggingMiddleware(app) #Replace this with a middleware of your choice (see below) + bottle.run(app=myapp) + +Now, bottle only catches its own exceptions (:exc:`HTTPError`, :exc:`HTTPResponse` and :exc:`BottleException`) and your middleware can handle the rest. + +The werkzeug_ and paste_ libraries both ship with very powerfull debugging WSGI middleware. Look at :class:`werkzeug.debug.DebuggedApplication` for werkzeug_ and :class:`paste.evalexception.middleware.EvalException` for paste_. They both allow you do inspect the stack and even execute python code within the stack context, so **do not use them in production**. + + +Embedding other WSGI Apps +-------------------------------------------------------------------------------- + +This is not the recommend way (you should use a middleware in front of bottle to do this) but you can call other WSGI applications from within your bottle app and let bottle act as a pseudo-middleware. Here is an example:: + + from bottle import request, response, route + subproject = SomeWSGIApplication() + + @route('/subproject/:subpath#.*#', method='ALL') + def call_wsgi(subpath): + new_environ = request.environ.copy() + new_environ['SCRIPT_NAME'] = new_environ.get('SCRIPT_NAME','') + '/subproject' + new_environ['PATH_INFO'] = '/' + subpath + def start_response(status, headerlist): + response.status = int(status.split()[0]) + for key, value in headerlist: + response.add_header(key, value) + return app(new_environ, start_response) + +Again, this is not the recommend way to implement subprojects. It is only here because many people asked for this and to show how bottle maps to WSGI. + + +Ignore tailing slashes +-------------------------------------------------------------------------------- + +For Bottle, ``/example`` and ``/example/`` are two different routes. To threat both URLs the same you can add two ``@route`` decorators:: + + @route('/test') + @route('/test/') + def test(): return 'Slash? no?' + +or add a WSGI middleware that strips tailing slashes from all URLs:: + + class StripPathMiddleware(object): + def __init__(self, app): + self.app = app + def __call__(self, e, h): + e['PATH_INFO'] = e['PATH_INFO'].rstrip('/') + return self.app(e,h) + + app = bottle.app() + myapp = StripPathMiddleware(app) + bottle.run(app=appmy) + diff --git a/bottle.py b/bottle.py index e1acc8e..5384740 100755 --- a/bottle.py +++ b/bottle.py @@ -1004,7 +1004,7 @@ def redirect(url, code=303): def send_file(*a, **k): #BC 0.6.4 - """ Raises the output of static_file() """ + """ Raises the output of static_file(). (deprecated) """ raise static_file(*a, **k) @@ -1196,7 +1196,8 @@ url = functools.wraps(Bottle.get_url)(lambda *a, **ka: app().get_url(*a, **ka mount = functools.wraps(Bottle.get_url)(lambda *a, **ka: app().mount(*a, **ka)) def default(): - raise DeprecationWarning("Use @error(404) instead.") + raise DeprecationWarning("The default() decorator is deprecated. "\ + "Use @error(404) instead.") -- cgit v1.2.1