{{ _('Index') }}
\n\n {% for key, dummy in genindexentries -%}\n {{ key }} {% if not loop.last %}| {% endif %}\n {%- endfor %}\n\n\n\n {% for key, entries in genindexentries %}\n
{{ key }}
\n\n
|
|
{{ _('Index') }}
\n{% for key, dummy in genindexentries -%}\n {{ key }}\n {% if not loop.last %}| {% endif %}\n {%- endfor %}
\n\n{{ _('Full index on one page') }}
\n{% endif %}\n {{ super() }}\n{% endblock %}\n" }, { "path": "pylons/docs/en/_oldtemplates/layout.html", "content": "{%- block doctype -%}\n\n{%- endblock %}\n{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %}\n{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}\n{%- macro relbar() %}\n \n{%- endmacro %}\n{%- macro sidebar() %}\n {%- if builder != 'htmlhelp' %}\n\n
\n {%- endif %}\n{%- endmacro -%}\n\n\n \n \n {%- if builder != 'htmlhelp' %}\n {%- set titlesuffix = \" — \" + docstitle %}\n {%- endif %}\n \n {%- block sidebarlogo %}\n {%- if logo %}\n \n {%- endif %}\n {%- endblock %}\n {%- block sidebartoc %}\n {%- if display_toc %}\n
\n {{ _('Table Of Contents') }}
\n {{ toc }}\n {%- endif %}\n {%- endblock %}\n {%- block sidebarrel %}\n {%- if prev %}\n{{ _('Previous topic') }}
\n \n {%- endif %}\n {%- if next %}\n{{ _('Next topic') }}
\n \n {%- endif %}\n {%- endblock %}\n {%- if sourcename %}\n{{ _('This Page') }}
\n \n {%- endif %}\n {%- if customsidebar %}\n {{ rendertemplate(customsidebar) }}\n {%- endif %}\n {%- block sidebarsearch %}\n {%- if pagename != \"search\" %}\n{% if builder == 'web' %}{{ _('Keyword search')}}{% else %}{{ _('Quick search') }}{% endif %}
\n \n {%- if builder == 'web' %}\n{{ _('Enter a module, class or function name.') }}
\n {%- endif %}\n {%- endif %}\n {%- endblock %}\n\n
\n\n{%- block relbar2 %}{{ relbar() }}{% endblock %}\n\n{%- block footer %}\n \n{%- endblock %}\n \n\n"
},
{
"path": "pylons/docs/en/_oldtemplates/modindex.html",
"content": "{% extends \"layout.html\" %}\n{% set title = _('Global Module Index') %}\n{% block extrahead %}\n{{ super() }}\n{% if builder != 'htmlhelp' and collapse_modindex %}\n \n{% endif %}\n{% endblock %}\n{% block body %}\n\n \n {%- if builder != 'htmlhelp' %}\n
\n{%- endblock %}\n\n{%- block sidebar2 %}{{ sidebar() }}{% endblock %}\n \n \n {%- endif %}\n
\n {%- endif %}\n \n {% block body %}{% endblock %}\n
\n {%- if builder != 'htmlhelp' %}\n {{ _('Global Module Index') }}
\n{% if builder == 'web' and freqentries %}\n{{ _('Most popular modules:') }}
\n\n {%- for module in freqentries %}\n {{ module.name|e }}\n {%- endfor %}\n
\n{% endif %}\n{% if builder == 'web' %}\n \n{% endif %}\n\n {%- for letter in letters %}\n {{ letter }} {% if not loop.last %}| {% endif %}\n {%- endfor %}\n \n\n
| {{ fname }} | {% if collapse -%}\n | \n {% if indent %} {% endif %}\n {% if fname %}{% endif -%}\n {{ stripped|e }}{{ modname|e }}\n {%- if fname %}{% endif %}\n {%- if pform[0] %} ({{ pform|join(', ') }}){% endif -%}\n | {% if dep %}{{ _('Deprecated')}}:{% endif %}\n {{ synops|e }} | \n {%- endif -%}\n {% endfor %}\n
\n {% trans %}Note: You requested an out-of-date URL from this server. We've tried to redirect you to the new location of this page, but it may not be the right one.{% endtrans %}\n
\n {% endif %}\n {{ body }}\n{% endblock %}\n"
},
{
"path": "pylons/docs/en/advanced_models.rst",
"content": ".. _advanced_models:\n\n===============\nAdvanced Models\n===============\n\nPylons works well with many different types of databases, in addition to other database object-relational mappers.\n\nAdvanced SQLAlchemy\n===================\n\nAlternative SQLAlchemy Styles\n-----------------------------\n\nIn addition to the declarative style, SQLAlchemy has a default more verbose and explicit approach.\n\nDefinitions using the default SQLAlchemy approach\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nHere is a sample :file:`model/__init__.py` with a \"persons\" table, based on \nthe default SQLAlchemy approach:\n\n.. code-block:: python\n\n \"\"\"The application's model objects\"\"\"\n import sqlalchemy as sa\n from sqlalchemy import orm\n\n from myapp.model import meta\n\n def init_model(engine):\n meta.Session.configure(bind=engine)\n meta.engine = engine\n\n\n t_persons = sa.Table(\"persons\", meta.metadata,\n sa.Column(\"id\", sa.types.Integer, primary_key=True),\n sa.Column(\"name\", sa.types.String(100), primary_key=True),\n sa.Column(\"email\", sa.types.String(100)),\n )\n\n class Person(object):\n pass\n\n orm.mapper(Person, t_persons)\n\nThis model has one table, \"persons\", assigned to the variable ``t_persons``.\n:class:`Person` is an ORM class which is bound to the table via the mapper.\n\nRelation example \n++++++++++++++++\n\nHere's an example of a `Person` and an `Address` class with a many:many relationship on `people.my_addresses`. See `Relational Databases for People in a Hurry \n @param format the format passed from the URI.\n \"\"\"\n #url('users')\n users = model.User.select()\n if format == 'json':\n data = []\n for user in users:\n d = user._state['original'].data\n del d['password']\n d['link'] = url('user', id=user.name)\n data.append(d)\n response.headers['content-type'] = 'text/javascript'\n return dumps(data)\n else:\n c.users = users\n return render('/users/index_user.mako')\n\n def create(self):\n \"\"\"POST /users: Create a new item.\"\"\"\n # url('users')\n user = model.User.get_by(name=request.params['name'])\n if user:\n # The client tried to create a user that already exists\n abort(409, '409 Conflict', \n headers=[('location', url('user', id=user.name))])\n else:\n try:\n # Validate the data that was sent to us\n params = model.forms.UserForm.to_python(request.params)\n except Invalid, e:\n # Something didn't validate correctly\n abort(400, '400 Bad Request -- %s' % e)\n user = model.User(**params)\n model.objectstore.flush()\n response.headers['location'] = url('user', id=user.name)\n response.status_code = 201\n c.user_name = user.name\n return render('/users/created_user.mako')\n\n def new(self, format='html'):\n \"\"\"GET /users/new: Form to create a new item.\n @param format the format passed from the URI.\n \"\"\"\n # url('new_user')\n return render('/users/new_user.mako')\n\n def update(self, id):\n \"\"\"PUT /users/id: Update an existing item.\n @param id the id (name) of the user to be updated\n \"\"\"\n # Forms posted to this method should contain a hidden field:\n # \n # Or using helpers:\n # h.form(url('user', id=ID),\n # method='put')\n # url('user', id=ID)\n old_name = id\n new_name = request.params['name']\n user = model.User.get_by(name=id)\n\n if user:\n if (old_name != new_name) and model.User.get_by(name=new_name):\n abort(409, '409 Conflict')\n else:\n params = model.forms.UserForm.to_python(request.params)\n user.name = params['name']\n user.full_name = params['full_name']\n user.email = params['email']\n user.password = params['password']\n model.objectstore.flush()\n if user.name != old_name:\n abort(301, '301 Moved Permanently',\n [('Location', url('users', id=user.name))])\n else:\n return\n\n def delete(self, id):\n \"\"\"DELETE /users/id: Delete an existing item.\n @param id the id (name) of the user to be updated\n \"\"\"\n # Forms posted to this method should contain a hidden field:\n # \n # Or using helpers:\n # h.form(url('user', id=ID),\n # method='delete')\n # url('user', id=ID)\n user = model.User.get_by(name=id)\n user.delete()\n model.objectstore.flush()\n return\n\n def show(self, id, format='html'):\n \"\"\"GET /users/id: Show a specific item.\n @param id the id (name) of the user to be updated.\n @param format the format of the URI requested.\n \"\"\"\n # url('user', id=ID)\n user = model.User.get_by(name=id)\n if user:\n if format=='json':\n data = user._state['original'].data\n del data['password']\n data['link'] = url('user', id=user.name)\n response.headers['content-type'] = 'text/javascript'\n return dumps(data)\n else:\n c.data = user\n return render('/users/show_user.mako')\n else:\n abort(404, '404 Not Found')\n\n def edit(self, id, format='html'):\n \"\"\"GET /users/id;edit: Form to edit an existing item.\n @param id the id (name) of the user to be updated.\n @param format the format of the URI requested.\n \"\"\"\n # url('edit_user', id=ID)\n user = model.User.get_by(name=id)\n if not user:\n abort(404, '404 Not Found')\n # Get the form values from the table\n c.values = model.forms.UserForm.from_python(user.__dict__)\n return render('/users/edit_user.mako')\n\n.. _xmlrpc_controller:\n\nUsing the XML-RPC Controller for XML-RPC requests\n================================================= \n\nIn order to deploy this controller you will need at least a passing familiarity with XML-RPC itself. We will first review the basics of XML-RPC and then describe the workings of the ``Pylons XMLRPCController``. Finally, we will show an example of how to use the controller to implement a simple web service. \n\nAfter you've read this document, you may be interested in reading the companion document: \"A blog publishing web service in XML-RPC\" which takes the subject further, covering details of the MetaWeblog API (a popular XML-RPC service) and demonstrating how to construct some basic service methods to act as the core of a MetaWeblog blog publishing service. \n\nA brief introduction to XML-RPC\n------------------------------- \n\nXML-RPC is a specification that describes a Remote Procedure Call (RPC) interface by which an application can use the Internet to execute a specified procedure call on a remote XML-RPC server. The name of the procedure to be called and any required parameter values are \"marshalled\" into XML. The XML forms the body of a POST request which is despatched via HTTP to the XML-RPC server. At the server, the procedure is executed, the returned value(s) is/are marshalled into XML and despatched back to the application. XML-RPC is designed to be as simple as possible, while allowing complex data structures to be transmitted, processed and returned. \n\nXML-RPC Controller that speaks WSGI \n-----------------------------------\n\nPylons uses Python's xmlrpclib library to provide a specialised :class:`XMLRPCController` class that gives you the full range of these XML-RPC Introspection facilities for use in your service methods and provides the foundation for constructing a set of specialised service methods that provide a useful web service --- such as a blog publishing interface. \n\nThis controller handles XML-RPC responses and complies with the `XML-RPC Specification
Welcome to the Analysis Demo
Here is a link.'\n\n def page2(self):\n return 'Thank you for using the Analysis Demo. Home'\n \n There are two shortcuts here which you would not use in a normal\n application. One, we're returning incomplete HTML documents. Two, we've\n hardcoded the URLs to make the analysis easier to follow, rather than using\n the ``url`` object.\n\n3. Now edit **analysis/config/routing.py**. Add these lines after \"CUSTOM\n ROUTES HERE\" (line 21)::\n\n map.connect(\"home\", \"/\", controller=\"main\", action=\"index\")\n map.connect(\"page2\", \"/page2\", controller=\"main\", action=\"page2\")\n\n4. Delete the file **analysis/public/index.html**.\n\n5. Now run the server. (Press ctrl-C to quit it.) ::\n\n $ paster serve development.ini\n Starting server in PID 7341.\n serving on http://127.0.0.1:5000\n\n\nPylons' dependencies\n====================\n\nPylons 1.0 has the following direct and indirect dependencies, which will be\nfound in your site-packages directory ($SP):\n\n* Beaker 1.5.4\n* decorator 3.2.0\n* FormEncode 1.2.2\n* Mako 0.3.4\n* MarkupSafe 0.9.3\n* Nose 0.11.4\n* Paste 1.7.3.1\n* PasteDeploy 1.3.3\n* PasteScript 1.7.3\n* Routes 1.12.3\n* simplejson 2.0.9 (if Python < 2.6)\n* Tempita 0.4\n* WebError 0.10.2\n* WebHelpers 1.2\n* WebOb 0.9.8\n* Webtest 1.2.1\n\nThese are the current versions as of August 29, 2010. Your installation may have\nslightly newer or older versions.\n\nThe analysis\n============\n\nStartup (PasteScript)\n---------------------\n\nWhen you run ``paster serve development.ini``, it runs the \"$BIN/paster\" program.\nThis is a platform-specific stub created by ``pip`` or ``easy_install``. It\ndoes this::\n\n __requires__ = 'PasteScript==1.7.3'\n import sys\n from pkg_resources import load_entry_point\n\n sys.exit(\n load_entry_point('PasteScript==1.7.3', 'console_scripts', 'paster')()\n )\n\nThis says to load a Python object \"paster\" located in an egg \"PasteScript\",\nversion 1.7.3, under the entry point group ``[console_scripts]``. \n\nTo explain what this means we have to get into Setuptools. Setuptools is\nPython's de facto package manager, and was installed as part of your virtualenv\nor Pylons installation. (If you're using Distribute 0.6, an alternative\npackage manager, it works the same way.) ``load_entry_point`` is a function\nthat looks up a Python object via entry point and returns it.\n\nSo what's an entry point? It's an alias for a Python object. Here's the entry\npoint itself::\n\n [console_scripts]\n paster=paste.script.command:run\n\nThis is from $SP/PasteScript-VERSION.egg-info/entry_points.txt.\n(If you used easy_install rather than pip, the path would be slightly\ndifferent: $APP/PasteScript-VERSION.egg/EGG-INFO/entry_points.txt.)\n\n\"console_scripts\" is the entry point group. \"paster\" is the\nentry point. The right side of the value tells which module to import\n(``paste.script.command``) and which object in it to return (the ``run``\nfunction). (To create an entry point, define it in your package's setup.py. Pip\nor easy_install will create the egg_info metadata from that. If you modify a\npackage's entry points, you must reinstall the package to update the egg_info.)\n\nThe most common use case for entry points is for plugins. So Nose for instance\ndefines an entry point group by which it will look for plugins. Any other\npackage can provide plugins for Nose by defining entry points in that group.\nPaster uses plugins extensively, as we'll soon see.\n\nSo to make a long story short, \"paster serve\" calls this ``run`` function. I\ninserted print statements into ``paste.script.command`` to figure out what it\ndoes. Here's a simplified description:\n\n1. The ``run()`` function parses the command-line options into a subcommand \n ``\"serve\"`` with arguments ``[\"development.ini\"]``.\n\n2. It calls ``get_commands()``, which loads Paster commands from plugins\n located at various entry points. (You can add custom commands with the\n \"--plugin\" command-line argument.) Paste's standard commands are listed in\n the same entry_points.txt file we saw above::\n\n [paste.global_paster_command]\n serve=paste.script.serve:ServeCommand [Config]\n #... other commands like \"make-config\", \"setup-app\", etc ...\n\n3. It calls ``invoke()``, which essentially does\n ``paste.script.serve.ServeCommand([\"development.ini\"]).run()``. This in turn\n calls ``ServeCommand.command()``, which handles daemonizing and other\n top-level stuff. Since our command line is short, there's no top-level\n stuff to do. It creates 'server' and 'app' objects based on the\n configuration file, and calls ``server(app)``.\n\nLoading the server and the application (PasteDeploy)\n----------------------------------------------------\n\nThis all happens during step 3 of the application startup. We need to find and\ninstantiate the WSGI application and server based on the configuration file.\nThe application is our Analysis application. The server is Paste's built-in\nmultithreaded HTTP server. A simplified version of the code is::\n\n # Inside paste.script.serve module, ServeCommand.command() method.\n from paste.deploy.loadwsgi import loadapp, loadserver\n server = self.loadserver(server_spec, name=server_name,\n relative_to=base, global_conf=vars)\n app = self.loadapp(app_spec, name=app_name,\n relative_to=base, global_conf=vars)\n\n``loadserver()`` and ``loadapp()`` are defined in module\n``paste.deploy.loadwsgi``. The code here is complex, so we'll just look at its\ngeneral behavior. Both functions see the \"config:\" URI and read our config\nfile. Since there is no server name or app name they both default to \"main\".\nTherefore loadserver() looks for a \"\\[server:main]\" section in the config file,\nand loadapp()` looks for \"\\[app:main]\". Here's what they find in\n\"development.ini\"::\n\n [server:main]\n use = egg:Paste#http\n host = 127.0.0.1\n port = 5000\n\n [app:main]\n use = egg:Analysis\n full_stack = true\n static_files = true\n ...\n\nThe \"use =\" line in each section tells which object to load. The other lines\nare configuration parameters for that object, or for plugins that object is\nexpected to load. We can also put custom parameters in \\[app:main] for our\napplication to read directly.\n\n\nServer loading\n++++++++++++++\n\n1. ``loadserver()``'s args are ``uri=\"config:development.ini\", name=None,\n relative_to=\"$APP\"``.\n\n2. A \"config:\" URI means to read a config file.\n\n3. A server name was not specified so it defaults to \"main\". So loadserver()\n looks for a section \"\\[server:main]\". The \"server\" part comes from the\n loadwsgi._Server.config_prefixes class attribute in\n $SP/paste/deploy/loadwsgi.py).\n\n4. \"use = egg:Paste#http\" says to load an egg called \"Paste\".\n\n5. loadwsgi._Server.egg_protocols lists two protocols it supports:\n \"server_factory\" and \"server_runner\".\n\n6. \"paste.server_runner\" is an entry point group in the \"Paste\" egg, and it has\n an entry point \"http\". The relevant lines in\n $SP/Paste\\*.egg_info/entry_points.txt are::\n\n [paste.server_runner]\n http = paste.httpserver:server_runner\n\n7. There's a server_runner() function in the paste.httpserver module\n ($SP/paste/httpserver.py).\n\nWe'll stop here for a moment and look at how the application is loaded.\n\nApplication loading\n+++++++++++++++++++\n\n1. loadapp() looks for a section \"\\[app:main]\" in the config file. The \"app\"\n part comes from the loadwsgi._App.config_prefixes class attribute (in\n $SP/paste/deploy/loadwsgi.py).\n\n2. \"use = egg:Analysis\" says to find an egg called \"Analysis\".\n\n3. loadwsgi._App.egg_protocols lists \"paste.app_factory\" as one of the\n protocols it supports.\n\n4. \"paste.app_factory\" is also an entry point group in the egg, as seen in\n $APP/Analysis.egg-info/entry_points.txt::\n\n [paste.app_factory]\n main = analysis.config.middleware:make_app\n\n5. The line \"main = analysis.config.middleware:make_app\" means to \n look for a ``make_app()`` object in the ``analysis`` package. \n This is a function imported from ``analysis.config.middleware`` \n ($APP/analysis/config/middleware.py).\n\n\nInstantiating the application (Analysis)\n----------------------------------------\n\nHere's a closer look at our application's ``make_app`` function::\n\n # In $APP/analysis/config/middleware.py\n def make_app(global_conf, full_stack=True, static_files=True, **app_conf):\n config = load_environment(global_conf, app_conf)\n app = PylonsApp(config=config)\n app = SomeMiddleware(app, ...) # Repeated for several middlewares.\n app.config = config\n return app\n\nThis sets up the Pylons environment (next subsection), creates the application\nobject (following subsection), wraps it in several layers of middleware (listed\nin \"Anatomy of a Request\" below), and returns the complete application object.\n\nThe \\[DEFAULT] section of the config file is passed as dict ``global_conf``.\nThe \\[app:main] section is passed as keyword arguments into dict ``app_conf``.\n\n``full_stack`` defaults to True because we're running the application\nstandalone. If we were embedding this application as a WSGI component of some\nlarger application, we'd set ``full_stack`` to False to disable some of the\nmiddleware. \n\n``static_files=True`` means to serve static files from our public\ndirectory ($APP/analysis/public). Advanced users can arrange for Apache to\nserve the static files itself, and put \"static_files = false\"\nin their configuration file to gain a bit of efficiency.\n\nload_environment & pylons.config\n++++++++++++++++++++++++++++++++\n\nBefore we begin, remember that ``pylons.config``, ``pylons.app_globals``,\n``pylons.request``, ``pylons.response``, ``pylons.session``, ``pylons.url``,\nand ``pylons.cache`` are special globals that change value depending on the\ncurrent request. The objects are proxies which maintain a thread-local stack of\nreal values. Pylons pushes the actual values onto them at the beginning of a\nrequest, and pops them off at the end. (Some of them it also pushes at other\ntimes so they can be used outside of requests.) The proxies delegate attribute\naccess and key access to the topmost actual object on the stack. (You can also\ncall ``myproxy._current_obj()`` to get the actual object itself.) The proxy\ncode is in ``paste.registry.StackedObjectProxy``, so these are called\n\"StackedObjectProxies\", or \"SOPs\" for short.\n\nThe first thing ``analysis.config.middleware.make_app()`` does is call\n``analysis.config.environment.load_environment()``::\n\n def load_environment(global_conf, app_conf):\n config = PylonsConfig()\n root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))\n paths = dict(root=root,\n controllers=os.path.join(root, 'controllers'),\n static_files=os.path.join(root, 'public'),\n templates=[os.path.join(root, 'templates')])\n\n # Initialize config with the basic options\n config.init_app(global_conf, app_conf, package='analysis',\n paths=paths)\n config['routes.map'] = make_map(config)\n config['pylons.app_globals'] = app_globals.Globals(config)\n config['pylons.h'] = analysis.lib.helpers\n\n # Setup cache object as early as possible\n import pylons\n pylons.cache._push_object(config['pylons.app_globals'].cache)\n\n # Create the Mako TemplateLookup, with the default auto-escaping\n config['pylons.app_globals'].mako_lookup = TemplateLookup(\n directories=paths['templates'],\n error_handler=handle_mako_error,\n module_directory=os.path.join(app_conf['cache_dir'], 'templates'),\n input_encoding='utf-8', default_filters=['escape'],\n imports=['from webhelpers.html import escape'])\n\n # CONFIGURATION OPTIONS HERE (note: all config options will override\n # any Pylons config options)\n\n return config\n\n``config`` is the Pylons configuration object, which will later be pushed onto\n``pylons.config``. It's an instance of ``pylons.configuration.PylonsConfig``, a\ndict subclass. ``config.init_app()`` initializes the dict's keys. It sets the\nkeys to a merger of app_conf and global_conf (with app_conf overriding). It\nalso adds \"app_conf\" and \"global_conf\" keys so you can access the original\napp_conf and global_conf if desired. It also adds several Pylons-specific keys.\n\n``config[\"routes.map\"]`` is the Routes map defined in\n``analysis.config.routing.make_map()``. \n\n``config[\"pylons.app_globals\"]`` is the application's globals object, which\nwill later be pushed onto ``pylons.app_globals``. It's an instance of\n``analysis.lib.app_globals.Globals``.\n\n``config[\"pylons.h\"]`` is the helpers module, ``analysis.lib.helpers``. Pylons\nwill assign it to ``h`` in the templates' namespace.\n\nThe \"cache\" lines push ``pylons.app_globals.cache`` onto ``pylons.cache`` for\nbackward compatibility. This gives a preview of how StackedObjectProxies work.\n\nThe Mako stanza creates a TemplateLookup, which ``render()`` will use to find\ntemplates. The object is put on ``app_globals``.\n\nIf you've used older versions of Pylons, you'll notice a couple differences in\n1.0. The ``config`` object is created as a local variable and returned, and\nit's passed explicitly to the route map factory and globals factory. Previous\nversions pushed it onto ``pylons.config`` immediately and used it from there.\nThis was changed to make it easier to nest Pylons applications inside other\nPylons applications. \n\nThe other difference is that Buffet is gone, and along with it the\n``template_engine`` argument and template config options. Pylons 1.0 gets out\nof the business of initializing template engines. You use one of the standard\nrender functions such as ``render_mako`` or write your own, and define any\nattributes in ``app_globals`` that your render function depends on.\n\n\nPylonsApp\n+++++++++\n\nThe second line of ``make_app()`` creates a Pylons application object\nbased on your configuration. Again the ``config`` object is passed around\nexplicitly, unlike older versions of Pylons. A Pylons application is an\ninstance of ``pylons.wsgiapp.PylonsApp`` instance. (Older versions of Pylons\nhad a ``PylonsBaseWSGIApp`` superclass, but that has been merged into\n``PylonsApp``.)\n\nMiddleware\n++++++++++\n\n``make_app()`` then wraps the application (the ``app`` variable) in several\nlayers of middleware. Each middleware provides an optional add-on service. \n\n================== ============================ ===============================\nMiddleware Service Effect if disabled\n================== ============================ ===============================\nRoutesMiddleware Use Routes to manage URLs. Routes and ``pylons.url`` won't\n work.\nSessionMiddleware HTTP sessions using Beaker, ``pylons.session`` won't work.\n with flexible persistence\n backends (disk, memached,\n database).\nErrorHandler Display interactive Paste will catch exceptions and \n traceback if an exception convert them to Internal Server\n occurs. In production mode, Error.\n email the traceback to the\n site admin.\nStatusCodeRedirect If an HTTP error occurs, If an HTTP error occurs, \n make a subrequest to display display a plain white HTML page\n a fancy styled HTML error with the error message.\n page.\nRegistryManager Handles the special globals The special globals won't work. \n (``pylons.request``, etc). There are other ways to access\n the objects without going\n through the special globals.\nStaticURLParser Serve the static files The static files won't be \n in the application's found. Presumably you've\n public directory. configured Apache to serve them\n directly.\nCascade Call several sub-middlewares No cascading through\n in order, and use the first alternative apps.\n one that doesn't return\n \"404 Not Found\". Used in\n conjunction with \n StaticURLParser.\n================== ============================ ===============================\n\nAt the end of the function, ``app.config`` is set to the ``config`` object, so\nthat any part of the application can access the config without going through\nthe special global.\n\nAnatomy of a request\n--------------------\n\nLet's say you're running the demo and click the \"link\" link on the home page.\nThe browser sends a request for \"http://localhost:5000/page2\". In my Firefox\nthe HTTP request headers are::\n\n GET /page2 \n Host: 127.0.0.1:5000\n User-Agent: Mozilla/5.0 ...\n Accept: text/html,...\n Accept-Language: en-us,en;q=0.5\n Accept-Encoding: gzip,deflate\n Accept-Charset: ISO-8859-1,utf-8;q=0.7*;q=0.7\n Keep-Alive: 300\n Connection: keep-alive\n Referer: http://127.0.0.1/5000/\n Cache-Control max-age=0\n\nThe response is::\n\n HTTP/1.x 200 OK\n Server: PasteWSGIServer/0.5 Python/2.6.4\n Date: Sun, 06 Dec 2009 14:06:05 GMT\n Content-Type: text/html; charset=utf-8\n Pragma: no-cache\n Cache-Control: no-cache\n Content-Length: 59\n\n Thank you for using the Analysis Demo. Home\n\nHere's the processing sequence:\n\n1. ``server(app)`` is still running, called by ``ServeCommand.command()`` in\n $SP/paste/script/serve.py.\n\n2. ``server`` is actually ``paste.httpserver.server_runner()`` in\n $SP/paste/httpserver. The only keyword args are 'host' and\n 'port' extracted from the config file. ``server_runner`` de-stringifies\n the arguments and calls ``serve(wsgi_app, **kwargs)`` (same module). \n\n3. ``serve()``'s 'use_threadpool' arg defaults to True, so it creates a\n ``WSGIThreadPoolServer`` instance called (``server``) with the following\n inheritance::\n\n SocketServer.BaseServer # In SocketServer.py in Python stdlib.\n BaseHTTPServer.HTTPServer # In BaseHTTPServer.py in Python stdlib.\n paste.httpserver.SecureHTTPServer # Adds SSL (HTTPS).\n paste.httpserver.WSGIServerBase # Adds WSGI.\n paste.httpserver.WSGIThreadPoolServer\n multiple inheritance: ThreadPoolMixIn <= ThreadPool\n\n Note that SecureHTTPServer overrides the implementation of Python's\n SocketServer.TCPServer\n\n4. It calls ``server.serve_forever()``, implemented by the ``ThreadPoolMixIn``\n superclass. This calls ``self.handle_request()`` in a loop until\n ``self.running`` becomes false. That initiates this call stack::\n\n # In paste.httpserver.serve(), calling 'server.serve_forever()'\n ThreadPoolMixIn.serve_forever() # Defined in paste.httpserver.\n -> TCPServer.handle_request() # Called for every request.\n -> WSGIServerBase.get_request()\n -> SecureHTTPServer.get_request()\n -> self.socket.accept() # Defined in stdlib socket module.\n\n ``self.socket.accept()`` blocks, waiting for the next request.\n\n5. The request arrives and ``self.socket.accept()`` returns a new socket for\n the connection. ``TCPServer.handle_request()`` continues. It calls\n ``ThreadPoolMixIn.process_request()``, which puts the request in a thread\n queue::\n\n self.thread_pooladd.add_task(\n lambda: self.process_request_in_thread(request, client_address))\n # 'request' is the connection socket.\n\n The thread pool is defined in the ``ThreadPool`` class. It spawns a number\n of threads which each wait on the queue for a callable to run. In this case\n the callable will be a complete Web transaction including sending the HTML\n page to the client. Each thread will repeatedly process transactions from\n the queue until they receive a sentinel value ordering them to die.\n\n The main thread goes back to listening for other requests, so we're no\n longer interested in it.\n\n6. **Thread #2** pulls the lambda out of the queue and calls it::\n\n lambda\n -> ThreadPoolMixIn.process_request_in_thread()\n -> BaseServer.finish_request()\n -> self.RequestHandlerClass(request, client_address, self) # Instantiates this.\n The class instantiated is paste.httpserver.WSGIHandler; i.e., the 'handler' variable in serve().\n\n7. The newly-created request handler takes over::\n\n SocketServer.BaseRequestHandler.__init__(request, client_address, server)\n -> WSGIHandler.handle()\n -> BaseHTTPRequestHandler.handle() # In stdlib BaseHTTPServer.py\n Handles requests in a loop until self.close_connection is true. (For HTTP keepalive?)\n -> WSGIHandler.handle_one_request()\n Reads the command from the socket. The command is\n \"GET /page2 HTTP/1.1\" plus the HTTP headers above.\n BaseHTTPRequestHandler.parse_request() parses this into attributes\n .command, .path, .request_version, and .headers.\n -> WSGIHandlerMixin.wsgi_execute().\n -> WSGIHandlerMixin.wsgi_setup()\n Creates the .wsgi_environ dict.\n\n The WSGI environment dict is described in PEP 333, the WSGI specification.\n It contains various keys specifying the URL to fetch, query parameters,\n server info, etc. All keys required by the CGI specification are present,\n as are other keys specific to WSGI or to paricular middleware. The\n application will calculate a response based on the dict. The application is\n wrapped in layers of middleware -- nested function calls -- which modify\n the dict on the way in and modify the response on the way out.\n\n8. The request handler, still in ``WSGIHandlerMixin.wsgi_execute()``, calls the\n application thus::\n\n result = self.server.wsgi_application(self.wsgi_environ,\n self.wsgi_start_response)\n\n ``wsgi_start_response`` is a callable mandated by the WSGI spec. The\n application will call it to specify the HTTP headers. The return value is\n an iteration of strings, which when concatenated form the HTML document to\n send to the browser. Other MIME types are handled analagously.\n\n9. The application, as we remember, was returned by\n ``analysis.config.middleware.make_app()``. It's wrapped in several layers\n of middleware, so calling it will execute the middleware in reverse order\n of how they're listed in $APP/analysis/config/middleware.py and\n $SP/pylons/wsgiapp.py:\n\n * ``Cascade`` (defined in $SP/paste/cascade.py) lists a \n series of applications which will be tried in order (Skipped if static_files is set to False):\n\n 1. ``StaticURLParser`` (defined in \n $SP/paste/urlparser) looks for a file URL\n under $APP/analysis/public that matches the URL. The demo\n has no static files.\n\n 2. If that fails the cascader tries your application. \n But first there are other middleware to go through...\n\n * ``RegistryManager`` (defined in $SP/paste/registry.py) \n makes Pylons special globals both thread-local and middleware-local.\n This includes **app_globals**, **cache**, **request**, **response**,\n **session**, **tmpl_context**, **url**, and any other\n ``StackedObjectProxy`` listed in $SP/pylons/__init__.py. (**h** is\n a module so it doesn't need a proxy.)\n\n * ``StatusCodeRedirect`` (defined in $SP/pylons/middleware.py)\n intercepts any HTTP error status returned by the application (e.g.,\n \"Page Not Found\", \"Internal Server Error\") and sends another request\n to the application to get the appropriate error page to display\n instead. (Skipped if ``full_stack`` argument was false.)\n\n * ``ErrorHandler`` (defined in $SP/pylons/middleware.py)\n sends an interactive traceback to the browser if the app raises an\n exception, if \"debug\" is true in the config file. Otherwise it\n attempts to email the traceback to the site administrator, and\n substitutes a generic Internal Server Error for the response.\n (Skipped if ``full_stack`` argument was false.\n\n * User-defined middleware goes here.\n\n * ``SessionMiddleware`` (wsgiapp.py) adds `Beaker`_\n session support (the ``pylons.session`` object). (Skipped if the\n WSGI environment has a key 'session' -- it doesn't in this demo.)\n\n * ``RoutesMiddleware`` (wsgiapp.py) compares the request URI against the\n routing rules in $APP/analysis/config/routing.py and sets\n 'wsgi.routing_args' to the routing match dict (useful) and\n 'routes.route' to the Route (probably not useful). Pylons 1.0 apps\n have a ``singleton=False`` argument that suppresses initializing the\n deprecated ``url_for()`` function. Routes now puts a URL\n generator in the WSGI environment, which Pylons aliases to\n ``pylons.url``.\n\n * The innermost middleware calls the PylonsApp instance it was \n initialized with.\n\n Note: CacheMiddleware is no longer used in Pylons 1.0. Instead,\n ``app_globals`` creates the cache as an attribute, and a line in\n environment.py aliases ``pylons.cache`` to it.\n\n10. Surprise! PylonsApp is itself middleware. Its .\\_\\_call\\_\\_() method does::\n\n self.setup_app_env(environ, start_response)\n controller = self.resolve(environ, start_response)\n response = self.dispatch(controller, environ, start_response)\n return response\n\n ``.setup_app_env()`` registers all those special globals.\n\n ``.resolve()`` calculates the controller class based on the route chosen by\n the RoutesMiddleware, and returns the controller class.\n\n ``.dispatch`` instantiates the controller class and calls in the WSGI\n manner. If the controller does not exist (``.resolve()`` returned None),\n raise an Exception that tells you what controller did not have any \n content.\n\n This method also handles the special URL \"/_test_vars\", which is enabled\n if the application is running under a Nose test. This URL initializes\n Pylons' special globals, for tests that have to access them before making\n a regular request.\n\n11. ``analysis.controllers.main.MainController`` does not have a\n ``.\\_\\_call\\_\\_()`` method, so control falls to its parent,\n ``analysis.lib.base.BaseController``. This trivially calls the\n grandparent, ``pylons.controllers.WSGIController``. It calls the action\n method ``MainController.page2()``. The action method may have any number of\n positional arguments as long as they correspond to variables in the routing\n match dict. (GET/POST variables are in the **request.params** dict.) If\n the method has a ``\\*\\*kwargs`` argument, all other match variables are put\n there. Any variables passed to the action method are also put on the\n **tmpl_context** object as attributes. If an action method name\n starts with \"\\_\", it's private and HTTPNotFound is raised.\n\n12. If the controller has .\\_\\_before\\_\\_() and/or .\\_\\_after\\_\\_() methods,\n they are called before and after the action, respectively. These can\n perform authorization, lock OS resources, etc. These methods can have\n arguments in the same manner as the action method. However, if the code is\n used by all controllers, most Pylons programmers prefer to it in the base\n controller's ``.\\_\\_call\\_\\_`` method instead.\n\n13. The action method returns a string, unicode, Response object, or is a\n generator of strings. In this trivial case it returns a string. A typical\n Pylons action would set some *tmpl_context* attributes and 'return\n render('/some/template.html\")' . In either case the global *response*\n object's body would be set to the string.\n\n14. ``WSGIController.\\_\\_call\\_\\_()`` continues, converting the Response object\n to an appropriate WSGI return value. (First it calls the start_response\n callback to specify the HTTP headers, then it returns an iteration of\n strings. The Response object converts unicode to utf-8 encoded strings, or\n whatever encoding you've specified in the config file.)\n\n15. The stack of middleware calls unwinds, each modifying the return value and\n headers if it desires. \n\n16. The server receives the final return value. (We're way back in\n ``paste.httpserver.WSGIHandlerMixin.wsgi_execute()`` now.) The outermost\n middleware has called back to ``server.start_response()``, which has saved\n the status and HTTP headers in ``.wsgi_curr_headers``. ``.wsgi_execute()``\n then iterates the application's return value, calling\n ``.wsgi_write_chunk(chunk)`` for each encoded string yielded.\n ``.wsgi_write_chunk('')`` formats the status and HTTP headers and sends them\n on the socket if they haven't been sent yet, then sends the chunk. The\n convoluted header behavior here is mandated by the WSGI spec.\n\n17. Control returns to ``BaseHTTPRequestHandler.handle()``.\n ``.close_connection`` is true so this method returns. The call stack\n continues unwinding all the way to\n ``paste.httpserver.ThreadPoolMixIn.process_request_in_thread()``. This\n tries to finish the request first and then close it unless it finds errors in it to end raising an Exception.\n\n18. The request lambda finishes and control returns to\n ``ThreadPool.worker_thread_callback()``. It waits for another request in\n the thread queue. If the next item in the queue is the shutdown sentinel\n value, thread #2 dies.\n\nThus endeth our request's long journey, and this analysis is finished too.\n\n.. _beaker: http://beaker.groovie.org/\n" }, { "path": "pylons/docs/en/forms.rst", "content": ".. _forms:\n\n===========\nForms\n===========\n\nThe basics\n==========\n\nWhen a user submits a form on a website the data is submitted to the URL specified in the `action` attribute of the ` \n\nIf the server is still running (see the :ref:`Getting Started Guide\n File description: ${h.text_field('description')}
\n ${h.submit('Submit')} \n ${h.end_form()} \n\nWhen a file upload has succeeded, the `request.POST` (or `request.params`) `MultiDict` will contain a `cgi.FieldStorage` object as the value of the field. \n\n`FieldStorage` objects have three important attributes for file uploads: \n\n`filename` \n The name of file uploaded as it appeared on the uploader's filesystem. \n\n`file` \n A file(-like) object from which the file's data can be read: A python `tempfile` or a `StringIO` object. \n\n`value` \n The content of the uploaded file, eagerly read directly from the file object. \n\nThe easiest way to gain access to the file's data is via the `value` attribute: it returns the entire contents of the file as a string: \n\n.. code-block:: python \n\n def upload(self): \n myfile = request.POST['myfile'] \n return 'Successfully uploaded: %s, size: %i, description: %s' % \\ \n (myfile.filename, len(myfile.value), request.POST['description']) \n\nHowever reading the entire contents of the file into memory is undesirable, especially for large file uploads. A common means of handling file uploads is to store the file somewhere on the filesystem. The `FieldStorage` typically reads the file onto filesystem, however to a non permanent location, via a python `tempfile` object (though for very small uploads it stores the file in a `StringIO` object instead). \n\nPython `tempfiles` are secure file objects that are automatically destroyed when they are closed (including an implicit close when the object is garbage collected). One of their security features is that their path cannot be determined: a simple `os.rename` from the `tempfile's` path isn't possible. Alternatively, `shutil.copyfileobj` can perform an efficient copy of the file's data to a permanent location: \n\n.. code-block:: python \n\n permanent_store = '/uploads/' \n\n class Uploader(BaseController): \n def upload(self): \n myfile = request.POST['myfile'] \n permanent_file = open(os.path.join(permanent_store, \n myfile.filename.lstrip(os.sep)), \n 'w') \n\n shutil.copyfileobj(myfile.file, permanent_file) \n myfile.file.close() \n permanent_file.close() \n\n return 'Successfully uploaded: %s, description: %s' % \\ \n (myfile.filename, request.POST['description']) \n\n.. warning:: \n The previous basic example allows any file uploader to overwrite any file in\n the `permanent_store` directory that your web application has permissions\n to.\n\nAlso note the use of `myfile.filename.lstrip(os.sep)` here: without it, `os.path.join` is unsafe. `os.path.join` won't join absolute paths (beginning with `os.sep`), i.e. `os.path.join('/uploads/', '/uploaded_file.txt')` == `'/uploaded_file.txt'`. Always check user submitted data to be used with `os.path.join`. \n\nValidating user input with FormEncode\n=====================================\n\nValidation the Quick Way \n------------------------\n\nAt the moment you could enter any value into the form and it would be displayed in the message, even if it wasn't a valid email address. In most cases this isn't acceptable since the user's input needs validating. The recommended tool for validating forms in Pylons is `FormEncode
Please correct the errors
\n % else: \nEnter Email Address
\n % endif \n\n % if c.form_errors: \n Email Address: ${h.text_field('email', value=c.form_result['email'] or '')} \n${c.form_errors['email']}
\n % else: \n Email Address: ${h.text_field('email')} \n % endif \n\n ${h.submit('Submit')} \n ${h.end_form()} \n\nNow when the form is invalid the `form.mako` template is re-rendered with the error messages. \n\n\nOther Form Tools \n================ \n\nIf you are going to be creating a lot of forms you may wish to consider using `FormBuild\n\n ${request.environ}\n\nThe :term:`request` variable in templates is used to get information about the current request. :ref:`Template globals
- \n % for employee in c.employees:\n
- ${employee.first_name} ${employee.last_name} \n % endfor\n
\n <%include file=\"list-partial.mako\"/>\n
\n \n \n\nTemplate ``list-partial.mako``:\n\n.. code-block:: mako\n\n ${c.employees.pager(\n 'Page $page: $link_previous $link_next ~4~',\n onclick=\"$('#my-page-area').load('%s'); return false;\")}\n - \n % for employee in c.employees:\n
- ${employee.first_name} ${employee.last_name} \n % endfor\n
' % _('Hello')) \n for lang in ['fr','en','es']: \n set_lang(lang) \n response.write(\"%s: %s
\" % (get_lang(), _('Hello'))) \n\nWhen writing wrapping strings in the gettext functions, it is important not to \npiece sentences together manually; certain languages might need to invert the \ngrammars. Don't do this: \n\n.. code-block:: python \n\n # BAD! \n msg = _(\"He told her \") \n msg += _(\"not to go outside.\") \n\nbut this is perfectly acceptable: \n\n.. code-block:: python \n\n # GOOD \n msg = _(\"He told her not to go outside\") \n\nThe controller has now been internationalized, but it will raise a \n``LanguageError`` until we have setup the alternative language catalogs. \n\nGNU gettext use three types of files in the translation framework. \n\nPOT (Portable Object Template) files \n------------------------------------\n\nThe first step in the localization process. A program is used to search \nthrough your project's source code and pick out every string passed to one \nof the translation functions, such as ``_()``. This list is put together in \na specially-formatted template file that will form the basis of all \ntranslations. This is the ``.pot`` file. \n\nPO (Portable Object) files \n--------------------------\n\nThe second step in the localization process. Using the POT file as a \ntemplate, the list of messages are translated and saved as a ``.po`` file. \n\nMO (Machine Object) files \n-------------------------\n\nThe final step in the localization process. The PO file is run through a \nprogram that turns it into an optimized machine-readable binary file, which \nis the ``.mo`` file. Compiling the translations to machine code makes the \nlocalized program much faster in retrieving the translations while it is \nrunning. \n\nGNU gettext provides a suite of command line programs for extracting messages \nfrom source code and working with the associated gettext catalogs. The `Babel \n
' % _('Hello')) \n for lang in ['fr','en','es']: \n set_lang(lang) \n response.write(\"%s: %s
\" % (get_lang(), _('Hello'))) \n response.write('Text: %s
' % text) \n\nIf we run this we get the following output: \n\n.. code-block:: text \n\n Default: Hello \n ['fr']: Bonjour \n ['en']: Good morning \n ['es']: Hola \n Text: Hello \n\nThis is because the function ``_('Hello')`` just after the imports is called \nwhen the default language is ``en`` so the variable ``text`` gets the value of \nthe English translation even though when the string was used the default \nlanguage was Spanish. \n\nThe rule of thumb in these situations is to try to avoid using the translation \nfunctions in situations where they are not executed on each request. For \nsituations where this isn't possible, perhaps because you are working with \nlegacy code or with a library which doesn't support internationalization, you \nneed to use lazy translations. \n\nIf we modify the above example so that the import statements and assignment to \n``text`` look like this: \n\n.. code-block:: python \n\n from pylons.i18n import get_lang, lazy_gettext, set_lang \n\n from helloworld.lib.base import * \n\n log = logging.getLogger(__name__) \n\n text = lazy_gettext('Hello') \n\nthen we get the output we expected: \n\n.. code-block:: text \n\n Default: Hello \n ['fr']: Bonjour \n ['en']: Good morning \n ['es']: Hola \n Text: Hola \n\nThere are lazy versions of all the standard Pylons `translation functions \n
') \n\nFor this reason you should only use the lazy translations where absolutely \nnecessary and should always ensure they are converted to strings by calling \n``str()`` or ``repr()`` before they are used in operations with real strings. \n\nProducing a Python Egg \n====================== \n\nFinally you can produce an egg of your project which includes the translation \nfiles like this: \n\n.. code-block:: bash \n\n $ python setup.py bdist_egg \n\nThe ``setup.py`` automatically includes the ``.mo`` language catalogs your \napplication needs so that your application can be distributed as an egg. This \nis done with the following line in your ``setup.py`` file: \n\n.. code-block:: python \n\n package_data={'translate_demo': ['i18n/*/LC_MESSAGES/*.mo']}, \n\nPlural Forms \n============ \n\nPylons also provides the ``ungettext()`` function. It's designed for \ninternationalizing plural words, and can be used as follows: \n\n.. code-block:: python \n\n ungettext('There is %(num)d file here', 'There are %(num)d files here',\n n) % {'num': n}\n\nPlural forms have a different type of entry in ``.pot``/``.po`` files, as \ndescribed in `The Format of PO Files \n