Table of contents

Child pages

...

• 2010.02.22 - Mengu.net - Django vs. web2py
• 2010.12.04 - Stack Overflow - Django vs web2py for a beginner developer
• 2014.06.21 - Reddit - Can anyone explain the differences between web2py, Django, Flask, etc?

web2py: The Complete Reference Manual

• web2py.com - Book - web2py: Complete Reference Manual
  • Chapter 4 - The Core
    • The 'Workflow' section is useful.

      • An HTTP requests arrives to the web server (the built-in Rocket server or a different server connected to web2py via WSGI or another adapter). The web server handles each request in its own thread, in parallel.
        The HTTP request header is parsed and passed to the dispatcher (explained later in this chapter).
        The dispatcher decides which of the installed application will handle the request and maps the PATH_INFO in the URL into a function call. Each URL corresponds to one function call.
        Requests for files in the static folder are handled directly, and large files are automatically streamed to the client.
        Requests for anything but a static file are mapped into an action (i.e. a function in a controller file, in the requested application).
        Before calling the action, a few things happen: if the request header contains a session cookie for the app, the session object is retrieved; if not, a session id is created (but the session file is not saved until later); an execution environment for the request is created; models are executed in this environment.
        Finally the controller action is executed in the pre-built environment.
        If the action returns a string, this is returned to the client (or if the action returns a web2py HTML helper object, it is serialized and returned to the client).
        If the action returns an iterable, this is used to loop and stream the data to the client.
        If the action returns a dictionary, web2py tries to locate a view to render the dictionary. The view must have the same name as the action (unless specified otherwise) and the same extension as the requested page (defaults to .html); on failure, web2py may pick up a generic view (if available and if enabled). The view sees every variable defined in the models as well as those in the dictionary returned by the action, but does not see global variables defined in the controller.
        The entire user code is executed in a single database transaction unless specified otherwise.
        If the user code succeeds, the transaction is committed.
        If the user code fails, the traceback is stored in a ticket, and a ticket ID is issued to the client. Only the system administrator can search and read the tracebacks in tickets.

    • web2py maps a URL of the form: http://127.0.0.1:8000/a/c/f.html to the function f() in controller "c.py" in application "a".
    • A diagram of how a request is handled: Image Added
    • web2py maps GET/POST requests of the form: http://127.0.0.1:8000/a/c/f.html/x/y/z?p=1&q=2 to function f in controller "c.py" in application a, and it stores the URL parameters in the request variable as follows: request.args = ['x', 'y', 'z'] and request.vars = {'p': 1, 'q': 2} and request.application = 'a' and request.controller = 'c' and request.function = 'f'

• • • Command line options
    • Workflow
      • Conditional models
    • Dispatching
    • Libraries
    • Applications
    • API
    • Accessing the API from Python modules
      • Sharing the global scope with modules using the current object
      • Warning! Do not use the current object in global scope in a module
    • request
    • response - 'response' is a variable that contains a bunch of attributes used when returning a response to the user.
    • session - 'session' is a variable that allows you to save information between requests within a single session.
      • Don't store user-defined classes in session
      • Separate sessions
    • cache - cache is a global object available in the web2py execution environment. It has two attributes: cache.ram: the application cache in main memory. cache.disk: the application cache on disk.
      • cache.action - If you are showing to the user a wiki page whose content will never change (or it changes once a week), it is useful to store that page, but it is even more useful to tell the client that that page is not going to change. This is accomplished sending out some specific headers along with the page: when the client's browser receives the content, it is stored in the browser's cache and it will not be requested again to your site. Of course this is a major speedup for public-facing sites. The cache.action decorator allows for smarter handling of this situation. It lets you customize the caching based on the URL's variables, the user, the language, etc.
    • URL - The URL function is one of the most important functions in web2py. It generates internal URL paths for the actions and the static files.
      • Absolute urls - By default, URL generates relative URLs. However, you can also generate absolute URLs by specifying the scheme and host arguments (this is useful, for example, when inserting URLs in email messages).
      • Digitally signed urls - When generating a URL, you have the option to digitally sign it. This will append a _signature GET variable that can be verified by the server.
    • HTTP and redirect - web2py defines only one new exception called HTTP. This exception can be raised anywhere in a model, a controller, or a view. The 'redirect' function is simply a shortcut for a call to the 'HTTP' 303 (redirect) exception.
    • Internationalization, and Pluralization with T - The object T is the language translator. It constitutes a single global instance of the web2py class gluon.language.translator. All string constants (and only string constants) should be wrapped by T, for example a = T("hello world").
      • Determining the language
      • Translating variables
      • Comments and multiple translations
      • Pluralization engine
      • Translations, pluralization, and MARKMIN
    • Cookies - web2py uses the Python cookies modules for handling cookies. You can set a cookie as follows: response.cookies['mycookie'] = 'somevalue'. The cookie can be retrieved with: request.cookies['mycookie'].value.
    • Application init - When you deploy web2py, you will want to set a default application, i.e., the application that starts when there is an empty path in the URL, as in: http://127.0.0.1:8000. By default, when confronted with an empty path, web2py looks for an application called init. If there is no init application it looks for an application called welcome.
      
    • URL rewrite - web2py has the ability to rewrite the URL path of incoming requests prior to calling the controller action (URL mapping), and conversely, web2py can rewrite the URL path generated by the URL function (reverse URL mapping). One reason to do this is for handling legacy URLs, another is to simplify paths and make them shorter.
      • Parameter-based system
      • Pattern-based system
      • Routes on error
      • Static asset management
    • Running tasks in the background - The proper way to run time-consuming tasks is doing it in the background. There is not a single way of doing it, but here we describe three mechanisms that are built into web2py: cron, homemade task queues, and scheduler.
      • Cron - web2py cron is the way to go if you need tasks in the background at scheduled times and these tasks take a relatively short time compared to the time interval between two calls. Each task runs in its own process, and multiple tasks can run concurrently, but you have no control over how many tasks run. If accidentally one task overlaps with itself, it can cause a database lock and a spike in memory usage.
      • Homemade task queues
      • web2py Scheduler - The mainstream web2py solution for running tasks in the background (and therefore away from the webserver process) is the built-in scheduler. The number of running processes is fixed, and they can run on different machines. Each process is called a worker. Each worker picks a task when available and executes it as soon as possible after the time when it is scheduled to run, but not necessarily at that exact time. There cannot be more processes running than the number of scheduled tasks and therefore no memory spikes. Scheduler tasks can be defined in models and are stored in the database. The web2py scheduler does not implement a distributed queue since it assumes that the time to distribute tasks is negligible compared with the time to run the tasks. Workers pick up the task from the database.
        • Parameters
        • Scheduler Deployment
        • Complete Scheduler signature
        • Tasks
        • Task Lifecycle
        • queue_task
        • task_status
        • Results and output
        • Managing processes
        • Reporting progress percentages
    • Third party modules - web2py is written in Python, so it can import and use any Python module, including third party modules. It just needs to be able to find them. As with any Python application, modules can be installed in the official Python "site-packages" directory, and they can then be imported from anywhere inside your code.
    • Execution environment - web2py model and controller files are not Python modules in that they cannot be imported using the Python import statement. The reason for this is that models and controllers are designed to be executed in a prepared environment that has been pre-populated with web2py global objects (request, response, session, cache and T) and helper functions.
    • Cooperation - applications can cooperate (share information) in various ways. web2py provides the exec_environment function to allow you to access models and controllers directly.
    • Logging - web2py has a way to make it easy to use the 'logging' module.
    • WSGI - we feel the core functionality of a framework (handling cookies, session, errors, transactions, dispatching) can be better optimized for speed and security if it is handled by a single comprehensive layer. web2py allows you to use third party WSGI applications and middleware in three ways (and their combinations).
  • Chapter 6: The database abstraction layer (DAL) - web2py comes with this. It's an API that maps Python objects into database objects such as queries, tables, and records. The DAL dynamically generates the SQL in real time using the specified dialect for the database back end, so that you do not have to write SQL code or learn different SQL dialects (the term SQL is used generically), and the application will be portable among different types of databases.
    • Dependencies - sqlite3, pymysql, pg8000, and imaplib ship with web2py.
    • The DAL: A quick tour - web2py defines the following classes that make up the DAL:
      • The DAL object ('db') represents a database connection
      • Table
      • Field
      • DAL Rows ('rows')
      • Row
      • Query - is an object that represents a SQL "where" clause
      • Set - is an object that represents a set of records. (Q: Like a Python set?)
      • Expression - is something like an orderby or groupby expression.
    • DAL constructor - db = DAL('sqlite://storage.sqlite')
      • DAL signature - A list of the options you can choose.
      • Connection strings (the uri parameter) - Examples of what the URI argument to the constructor will look like for different dbs (eg SQLite, MySQL, FireBird)
        • In SQLite the database consists of a single file. If it does not exist, it is created. This file is locked every time it is accessed. In the case of MySQL (and others) the database "test" must be created outside web2py.
      • Connection pooling - As it is rather slow to establish a new database connection for each request, web2py implements a mechanism for connection pooling. Once a connection is established and the page has been served and the transaction completed, the connection is not closed but goes into a pool. When the next http request arrives, web2py tries to recycle a connection from the pool and use that for the new transaction. If there are no available connections in the pool, a new connection is established.
      • Connection failures (attempts parameter) - If web2py fails to connect to the database it waits 1 seconds and by default tries again up to 5 times before declaring a failure.
      • Lazy Tables - setting lazy_tables = True provides a major performance boost. (SF has this enabled.)
      • Model-less applications - Using web2py's model directory for your application models is very convenient and productive. With lazy tables and conditional models, performance is usually acceptable even for large applications. Many experienced developers use this is production environments.

        However, it is possible to define DAL tables on demand inside controller functions or modules. This may make sense when the number or complexity of table definitions overloads the use of lazy tables and conditional models. (SF does not do this.)

      • Replicated databases - The first argument of DAL(...) can be a list of URIs. In this case web2py tries to connect to each of them. (The main purpose for this is to deal with multiple database servers and distribute the workload among them).
      • Reserved keywords - check_reserved tells the constructor to check table names and column names against reserved SQL keywords in target back-end databases.
      • Database quoting and case settings (entity_quoting, ignore_field) - I didn't understand this part.
      • Experiment with the web2py shell - You can experiment with the DAL API using the web2py shell (-S command line option). Start by creating a connection. For the sake of example, you can use SQLite.
    • Table constructor - This section shows the arguments you can pass to the constructor and then gives a description of each of them.
      • Lazy Tables, a major performance boost - web2py models are executed before controllers, so all tables are defined at every request. Not all tables are needed to handle each request, so it is possible that some of the time spent defining tables is wasted. Conditional models (conditional models, chapter 4) can help, but web2py offers a big performance boost via lazy_tables. This feature means that table creation is deferred until the table is actually referenced. Enabling lazy tables is made when initialising a database via the DAL constructor. It requires setting the DAL(...,lazy_tables=True) parameter. This is one of the most significant response-time performance boosts in web2py.
    • Field constructor - ~18 options
      • Field types - ~14 options
      • Run-time field and table modification - "Most attributes of fields and tables can be modified after they are defined" What does that mean, exactly? My understanding is that databases are not easy to change...?
        • A field also has methods. A special method of the field object is validate and it calls the validators for the field.
    • Migrations - define_table checks whether or not the corresponding table exists. If it does not, it generates the SQL to create it and executes the SQL. If the table does exist but differs from the one being defined, it generates the SQL to alter the table and executes it. If a field has changed type but not name, it will try to convert the data
    • Fixing broken migrations
    • Migration control summary
    • insert
    • commit and rollback
    • Raw SQL
    • drop
    • Indexes
    • Legacy databases and keyed tables
    • Distributed transaction
    • More on uploads
    • Query, Set, Rows
    • select
    • Other methods
    • Computed fields
    • Virtual fields
    • One to many relation
    • Many to many
    • list: and contains
    • Other operators
    • Generating raw sql
    • Exporting and importing data
    • Caching selects
    • Self-Reference and aliases
    • Advanced features
    • Gotchas