Marc abramowitz web complete reference manual

Copyright 2008-2013 by Massimo Di Pierro. All rights reserved.

THE CONTENT OF THIS BOOK IS PROVIDED UNDER THE TERMS OF THE CREATIVE COMMONS PUBLIC LICENSE BY-NC-ND 3.0.

Massimo Di Pierro

School of Computing

Library of Congress Cataloging-in-Publication Data:

ISBN: 978-0-578-12021-8

6

2.10.1 lambda . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

2.11 class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

2.15.1 os . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

2.15.2 sys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

3.1 Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

3.2 Simple examples . . . . . . . . . . . . . . . . . . . . . . . . . 77

3.2.5 Postbacks . . . . . . . . . . . . . . . . . . . . . . . . . 85

3.2.6 Internationalization . . . . . . . . . . . . . . . . . . . 88

3.4 A simple wiki . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

3.4.1 On date, datetime and time format . . . . . . . . . . . 119

7

3.5.4 Wiki menus . . . . . . . . . . . . . . . . . . . . . . . . 125

3.6.1 Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

3.6.2 About . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

3.6.7 Configuring admin . . . . . . . . . . . . . . . . . . . . 140

3.6.8 Mobile admin . . . . . . . . . . . . . . . . . . . . . . . 142

4.3 Dispatching . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

4.4 Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

4.8 response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

4.9 session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

4.11.2 Digitally signed urls . . . . . . . . . . . . . . . . . . . 182

4.12 HTTP and redirect . . . . . . . . . . . . . . . . . . . . . . . . . 184

4.13.3 Comments and multiple translations . . . . . . . . . 188 4.13.4 Pluralization engine . . . . . . . . . . . . . . . . . . . 189 4.13.5 Translations, pluralization, and MARKMIN . . . . . 191 4.14 Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 4.15 Application init . . . . . . . . . . . . . . . . . . . . . . . . . . 193 4.16 URL rewrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 4.16.1 Parameter-based system . . . . . . . . . . . . . . . . . 194 4.16.2 Pattern-based system . . . . . . . . . . . . . . . . . . 196 4.16.3 Routes on error . . . . . . . . . . . . . . . . . . . . . . 200 4.16.4 Static asset management . . . . . . . . . . . . . . . . . 201 4.17 Running tasks in the background . . . . . . . . . . . . . . . . 204 4.17.1 Cron . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 4.17.2 Homemade task queues . . . . . . . . . . . . . . . . . 207 4.17.3 Scheduler (experimental) . . . . . . . . . . . . . . . . 208 4.18 Third party modules . . . . . . . . . . . . . . . . . . . . . . . 218 4.19 Execution environment . . . . . . . . . . . . . . . . . . . . . . 219 4.20 Cooperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 4.21 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 4.22 WSGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 4.22.1 External middleware . . . . . . . . . . . . . . . . . . . 223 4.22.2 Internal middleware . . . . . . . . . . . . . . . . . . . 224 4.22.3 Calling WSGI applications . . . . . . . . . . . . . . . 224

5 The views 227 5.1 Basic syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 5.1.1 for...in . . . . . . . . . . . . . . . . . . . . . . . . . . 229 5.1.2 while . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 5.1.3 if...elif...else . . . . . . . . . . . . . . . . . . . . . 230 5.1.4 try...except...else...finally . . . . . . . . . . . . . 231 5.1.5 def...return . . . . . . . . . . . . . . . . . . . . . . . . 232 5.2 HTML helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 5.2.1 XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 5.2.2
Built-in helpers . . . . . . . . . . . . . . . . . . . . . . 236 5.2.3 Custom helpers . . . . . . . . . . . . . . . . . . . . . . 250 5.3 BEAUTIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

5.4.3 parent and siblings . . . . . . . . . . . . . . . . . . . . 254

5.4.4 Replacing elements . . . . . . . . . . . . . . . . . . . . 254

5.5.2 Customizing the default layout . . . . . . . . . . . . . 262

5.5.3 Mobile development . . . . . . . . . . . . . . . . . . . 263

6.2 Connection strings . . . . . . . . . . . . . . . . . . . . . . . . 269

6.2.1 Connection pooling . . . . . . . . . . . . . . . . . . . 271

6.5 Record representation . . . . . . . . . . . . . . . . . . . . . . 275

6.6 Migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

6.10.1 Timing queries . . . . . . . . . . . . . . . . . . . . . . 285

6.10.2 executesql . . . . . . . . . . . . . . . . . . . . . . . . . 285

6.14 Distributed transaction . . . . . . . . . . . . . . . . . . . . . . 288

10

6.17.10 update_record . . . . . . . . . . . . . . . . . . . . . . . 301 6.17.11 Inserting and updating from a dictionary . . . . . . . 301 6.17.12 first and last . . . . . . . . . . . . . . . . . . . . . . . 302 6.17.13 as_dict and as_list . . . . . . . . . . . . . . . . . . . . 302 6.17.14 Combining rows . . . . . . . . . . . . . . . . . . . . . 302 6.17.15 find, exclude, sort . . . . . . . . . . . . . . . . . . . . . 303 6.18 Other methods
. . . . . . . . . . . . . . . . . . . . . . . . . . 304 6.18.1 update_or_insert . . . . . . . . . . . . . . . . . . . . . 304 6.18.2 validate_and_insert, validate_and_update . . . . . . . 305 6.18.3 smart_query (experimental)
. . . . . . . . . . . . . . . 305 6.19 Computed fields . . . . . . . . . . . . . . . . . . . . . . . . . 306 6.20 Virtual fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 6.20.1 New style virtual fields . . . . . . . . . . . . . . . . . 307 6.20.2 Old style virtual fields . . . . . . . . . . . . . . . . . . 308 6.21 One to many relation . . . . . . . . . . . . . . . . . . . . . . . 310 6.21.1 Inner joins . . . . . . . . . . . . . . . . . . . . . . . . . 311 6.21.2 Left outer join . . . . . . . . . . . . . . . . . . . . . . . 313 6.21.3 Grouping and counting . . . . . . . . . . . . . . . . . 313 6.22 Many to many . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 6.23 list:<type>, and contains . . . . . . . . . . . . . . . . . . . . 315 6.24 Other operators . . . . . . . . . . . . . . . . . . . . . . . . . . 317 6.24.1 like, regexp, startswith, contains, upper, lower . . . . 317 6.24.2 year, month, day, hour, minutes, seconds . . . . . . . . . 318

11

7.1.7 Multiple forms per page . . . . . . . . . . . . . . . . . 354

7.1.8 Sharing forms . . . . . . . . . . . . . . . . . . . . . . . 355

7.2.2 SQLFORM in HTML . . . . . . . . . . . . . . . . . . . . . 363

7.2.3 SQLFORM and uploads . . . . . . . . . . . . . . . . . . . 364

7.2.8 Adding extra form elements to SQLFORM . . . . . . . . 370

7.2.9 SQLFORM without database IO . . . . . . . . . . . . . . 370

7.3.4 Form to edit a dictionary . . . . . . . . . . . . . . . . 373

7.4 CRUD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

7.5 Custom forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

7.5.1 CSS conventions . . . . . . . . . . . . . . . . . . . . . 383

7.6.3 Custom validators . . . . . . . . . . . . . . . . . . . . 399

7.6.4 Validators with dependencies . . . . . . . . . . . . . . 401

8 Emails and SMS 413

8.1 Setting up email . . . . . . . . . . . . . . . . . . . . . . . . . . 413

8.2.2 HTML emails . . . . . . . . . . . . . . . . . . . . . . . 415

8.2.3 Combining text and HTML emails . . . . . . . . . . . 416

8.4 Using the template system to generate messages . . . . . . . 417

8.5 Sending messages using a background task . . . . . . . . . . 418

9.1 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

9.1.1 Restrictions on registration . . . . . . . . . . . . . . . 431

9.1.6 Other login methods and login forms . . . . . . . . . 438

9.1.7 Record versioning . . . . . . . . . . . . . . . . . . . . 444

9.2.3 Authorization and CRUD . . . . . . . . . . . . . . . . 450

9.2.4 Authorization and downloads . . . . . . . . . . . . . 451

10 Services 463 10.1 Rendering a dictionary . . . . . . . . . . . . . . . . . . . . . . 463 10.1.1 HTML, XML, and JSON . . . . . . . . . . . . . . . . . 464 10.1.2 Generic views . . . . . . . . . . . . . . . . . . . . . . . 464 10.1.3 Rendering Rows . . . . . . . . . . . . . . . . . . . . . . 466 10.1.4 Custom formats . . . . . . . . . . . . . . . . . . . . . . 467 10.1.5 RSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 10.1.6 CSV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 10.2 Remote procedure calls . . . . . . . . . . . . . . . . . . . . . 470 10.2.1 XMLRPC . . . . . . . . . . . . . . . . . . . . . . . . . . 472 10.2.2 JSONRPC . . . . . . . . . . . . . . . . . . . . . . . . . 473

10.2.3 JSONRPC and Pyjamas

10.3.1 simplejson . . . . . . . . . . . . . . . . . . . . . . . . . 480

10.3.2 PyRTF . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

10.4.3 Access Control . . . . . . . . . . . . . . . . . . . . . . 491

10.5 Services and Authentication . . . . . . . . . . . . . . . . . . . 492

11.2.2 Confirmation on delete . . . . . . . . . . . . . . . . . 506

11.3 The ajax function . . . . . . . . . . . . . . . . . . . . . . . . . 507

13 Deployment recipes 531 13.1 anyserver.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 13.2 Linux and Unix . . . . . . . . . . . . . . . . . . . . . . . . . . 535 13.2.1 One step production deployment . . . . . . . . . . . 535 13.2.2 Apache setup . . . . . . . . . . . . . . . . . . . . . . . 535 13.2.3 mod_wsgi . . . . . . . . . . . . . . . . . . . . . . . . . 536 13.2.4 Setting password . . . . . . . . . . . . . . . . . . . . . 539 13.2.5 mod_wsgi and SSL . . . . . . . . . . . . . . . . . . . . 539 13.2.6 mod_proxy . . . . . . . . . . . . . . . . . . . . . . . . 540 13.2.7 Start as Linux daemon . . . . . . . . . . . . . . . . . . 542 13.2.8 Nginx . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 13.2.9 Lighttpd . . . . . . . . . . . . . . . . . . . . . . . . . . 546 13.2.10 Shared hosting with mod_python . . . . . . . . . . . 548 13.2.11 Cherokee with FastCGI . . . . . . . . . . . . . . . . . 548 13.2.12 Postgresql . . . . . . . . . . . . . . . . . . . . . . . . . 550 13.2.13 Start the scheduler as a Linux service (upstart) . . . 551 13.3 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552

13.3.1 Apache and mod_wsgi 13.3.2 Start as Windows service

13.6 Deploying on PythonAnywhere

. . . . . . . . . . . . . . . . 568

Index 603

Bibliography 609

As a result, in 2011, web2py won the Bossie Award for best Open Source Development Software, and in 2012 it won the Technology of the Year award from InfoWorld.

As you will learn in the following pages, web2py tries to lower the barrier of entry to web development by focusing on three main goals:

models, you will have access to a web-based database administration panel.

Also, web2py automatically generates forms for your data and it allows you to

SQL Injections. The template language prevents Cross Site Scripting

vulnerabilities. The forms generated by web2py provide field validation and

internally to become faster and leaner, whilst always maintaining backwards

compatibility.

Introduction

web2py [1] is a free, open-source web framework for agile development of secure database-driven web applications; it is written in Python [2] and programmable in Python. web2py is a full-stack framework, meaning that it contains all the components you need to build fully functional web applications. web2py is designed to guide a web developer to follow good software engineering practices, such as using the Model View Controller (MVC) pattern. web2py separates the data representation (the model) from the data presentation (the view) and also from the application logic and workflow (the controller). web2py provides libraries to help the developer design, implement, and test each of these three parts separately, and makes them work together. web2py is built for security. This means that it automatically addresses many of the issues that can lead to security vulnerabilities, by following well established practices. For example, it validates all input (to prevent injections), escapes all output (to prevent cross-site scripting), renames uploaded files (to prevent directory traversal attacks). web2py takes care of main security issues, so developers have less chances of introducing vulnerabilities. web2py includes a Database Abstraction Layer (DAL) that writes SQL [3] dynamically so that you, the developer, don’t have to. The DAL knows how to generate SQL transparently for SQLite [4], MySQL [5], PostgreSQL [6], MSSQL [7], FireBird [8], Oracle [9], IBM DB2 [10], Informix [11], Ingres [12], and MongoDB [13]. The DAL can also generate function calls for the Google Datastore when running on the

1 db.define_table('person', Field('name'), Field('image', 'upload'))

creates a database table called "person" with two fields: "name", a string; and "image", something that needs to be uploaded (the actual image). If the table already exists but does not match this definition, it is altered appropriately.

This code embeds a fully working wiki with tags, search, tag cloud, permissions, media attachments, and oembed support:

The following code instead:

Python programming typically follows these basic principles:

• Don’t repeat yourself (DRY).

26 web2py complete reference manual, 5th edition

not import user applications, but executes them in a predefined context. This context exposes the Python keywords, as well as the web2py keywords.

The purpose of web frameworks is to allow developers to build new apps quickly, easily and without mistakes. This is done by providing APIs and tools that reduce and simplify the amount of coding that is required.

The two classic approaches for developing web applications are:

14 ?></body></html>

The problem with this approach is that code is embedded into HTML, but the very same code also needs to generate additional HTML and to generate SQL statements to query the database, entangling multiple layers of the application and making it difficult to read and maintain. The situation is even worse for Ajax applications, and the complexity grows with the number of pages (files) that make up the application.

Web frameworks are typically categorized as one of two types: A "glued" framework is built by assembling (gluing together) several third-party components. A "full-stack" framework is built by creating components designed specifically to be tightly integrated and work together. web2py is a full-stack framework. Almost all of its components are built from scratch and are designed to work together, but they function just as well outside of the complete web2py framework. For example, the Database Abstraction Layer (DAL) or the template language can be used independently of the web2py framework by importing gluon.dal or gluon.template into your own Python applications. gluon is the name of the web2py module that contains system

28 web2py complete reference manual, 5th edition

The typical workflow of a request in web2py is described in the following diagram:

introduction 29

Views and Controller components make up the user• The Models,
application.

• Multiple applications can be hosted in the same web2py instance.

into an HTML page.

If the visitor requests the same page in XML,

If the request succeeds, the

• web2py also handles sessions and session cookies automatically, and when a transaction is committed, the session is also stored, unless specified otherwise.

It connects to the database (in this example a SQLite database stored in the storage.sqlite file) and defines a table called contact. If the table does not exist, web2py creates it and, transparently and in the background, generates SQL code in the appropriate SQL dialect for the specific database engine used. The developer can see the generated SQL but does not need to change the code if the database back-end, which defaults to SQLite, is replaced with MySQL, PostgreSQL, MSSQL, FireBird, Oracle, DB2, Informix, Interbase, Ingres, and the Google App Engine (both SQL and NoSQL).

In web2py, URLs are mapped to Python modules and function calls. In this case, the controller contains a single function (or "action") called contacts. An action may return a string (the returned web page) or a Python dictionary (a set of key:value pairs) or the set of local variables (as in this example). If the function returns a dictionary, it is passed to a view with the same name as the controller/function, which in turn renders the page. In this example, the function contacts generates a select/search/create/update/delete grid for table db.contact and returns the grid to the view.

web2py is one of many web application frameworks, but it has compelling and unique features. web2py was originally developed as a teaching tool, with the following primary motivations:

32 web2py complete reference manual, 5th edition

including an Integrated Development Environment with Debugger and database interface.

Abstraction Layer, the template language, and all the helpers amount to 1.4MB. The entire source code including sample applications and images amounts to 10.4MB.

• web2py has a small footprint and is very fast. It uses the Rocket [19] WSGI web server developed by Timothy Farrell. It is as fast as Apache with mod_wsgi, and supports SSL and IPv6.

Here is a screenshot of the main web2py admin interface:

• "Injection Flaws: Injection flaws, particularly SQL injection, are common in web applications. Injection occurs when user-supplied data is sent to an interpreter as part of a command or query. The attacker’s hostile data tricks the interpreter into executing unintended commands or changing data." web2py includes a Database Abstraction Layer that makes SQL injection impossible. Normally, SQL statements are not written by the developer. Instead,

34 web2py complete reference manual, 5th edition

• "Information Leakage and Improper Error Handling: Applications can unintentionally leak information about their configuration, internal workings, or violate privacy through a variety of application problems. Attackers use this weakness to steal sensitive data, or conduct more serious attacks." web2py includes a ticketing system. No error can result in code being exposed to the users. All errors are logged and a ticket is issued to the user that allows error tracking. But errors and source code are accessible only to the administrator.

• "Broken Authentication and Session Management: Account credentials

• "Insecure Communications: Applications frequently fail to encrypt network traffic when it is necessary to protect sensitive communications." web2py includes the SSL-enabled [22] Rocket WSGI server, but it can also use Apache or Lighttpd and mod_ssl to provide SSL encryption of communications.

• "Failure to Restrict URL Access: Frequently an application only protects sensitive functionality by preventing the display of links or URLs to unauthorized users. Attackers can use this weakness to access and perform unauthorized operations by accessing those URLs directly." web2py maps URL requests to Python modules and functions. web2py provides a mechanism for declaring which functions are public and which require The included Role Based Access Control authentication and authorization.

You can download web2py from the official web site:

web2py is composed of the following components:

• the welcome application: the basic scaffolding template for any other application. By default it includes a pure CSS cascading menu and user authentication (discussed in Chapter 9).

web2py is distributed in source code, and in binary form for Microsoft Windows and for Mac OS X.

At the bottom we find the interpreter. Moving up we find the web server (rocket), the libraries, and the applications. Each application consists for its own MVC design (models, controllers, views, modules, languages, databases, and static files). Each application includes it own database administration code (appadmin). Every web2py instance ships with three applications: welcome (the scaffolding app), admin (the web based IDE), and examples (copy of website and examples).

38 web2py complete reference manual, 5th edition

2 for general Python syntax and to the following chapters for a more detailed reference about the functions that are used.

• Chapter 8 covers communication with as sending emails and SMSes.

• Chapter 9 covers authentication, authorization and the extensible Role- Based Access Control mechanism available in web2py. Mail configuration and CAPTCHA are also discussed here, since they are used for authentication. In the third edition of the book we have added extensive coverage of integration with third-party authentication mechanisms such as OpenID, OAuth, Google, Facebook, LinkedIn, etc.

many commonly used functionality, such as charting, comments, and tagging.

• Chapter 13 is about production deployment of web2py applications. We specifically discuss the deployment on a LAMP web server (which we consider the main deployment alternative). We discuss alterantive web servers, and configuration of the PostgreSQL database. We discuss running as a service on a Microsoft Windows environment, and deployment on some specific platforms including Google Applications Engine, Heorku, and PythonAnywhere. In this chapter, we also discuss security and scalability issues.

1.8 Support

The main support channel is the usergroup [25], with dozens of posts every day. Even if you’re a newbie, don’t hesitate to ask - we’ll be pleased to help you. There is also a formal issue tracker system on http://code.google.com/p/web2py/issue. Last but not least, you can have professional support (see the web site for details).

PEP8 [27] contains good style practices when programming with Python. You will find that web2py does not always follow these rules. This is not because of omissions or negligence; it is our belief that the users of web2py should follow these rules and we encourage it. We chose not to follow some of those rules when defining web2py helper objects in order to minimize the probability of name conflict with objects defined by the user.

For example, the class that represents a <div> is called DIV, while according to the Python style reference it should have been called Div. We believe that, for this specific example that using an all-upper-case "DIV" is a more natural choice. Moreover, this approach leaves programmers free to create a class called "Div" if they choose to do so. Our syntax also maps naturally into the DOM notation of most browsers (including, for example, Firefox).

• The translator object T is upper case despite the fact that it is an instance of a class and not a class itself. Logically the translator object performs an action similar to the HTML helpers, it affects rendering part of the presentation. Also, T needs to be easy to locate in the code and must have a short name.

• DAL classes follow the Python style guide (first letter capitalized), for example Table, Field, Query, Row, Rows, etc.

STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER

Third party software distributed with web2py web2py contains third party software under the gluon/contrib/ folder and various JavaScript and CSS files. These files are distributed with web2py under their original licenses, as stated in the files.

1.12 Acknowledgments

Adam Bryzak, Adam Gojdas, Adrian Klaver, Alain Boulch, Alan Etkin, Alec Taylor, Alexandre Andrade, Alexey Nezhdanov, Alvaro Justen, Anand Vaidya, Anatoly Belyakov, Ander Arbelaiz, Anders Roos, Andrew Replogle,

I particularly thank Anthony, Jonathan, Mariano, Bruno, Vladyslav, Martin, Nathan, Simone, Thadeus, Tim, Iceberg, Denes, Hans, Christian, Fran and Patrick for their major contributions to web2py and Anthony, Alvaro, Brian, Bruno, Denes, Dane Denny, Erwin, Felipe, Graham, Jonathan, Hans, Kyle, Mark, Margaret, Michele, Nico, Richard, Roberto, Robin, Roman, Scott, Shane, Sharriff, Sriram, Sterling, Stuart, Thadeus, Wen (and others) for proofreading various versions of this book. Their contribution was

introduction 45

2

The Python language

You can find many tutorials, the official documentation and library references

48 web2py complete reference manual, 5th edition

The binary distributions of web2py for Microsoft Windows or Apple OS X come packaged with the Python interpreter built into the distribution file itself.

You can start it on Windows with the following command (type at the DOS prompt):

The admin interface also provides a web-based shell for each application. You can access the one for the "welcome" application at.

the python language 49

1 >>> help(1)
2 Help on int object:

3

Similarly, we can obtain a list of methods of the object "1" with the command dir:

1 >>> dir(1)

1 >>> a = 3

3 <type 'int'>

2.4.1 str

Python supports the use of two different types of strings: ASCII strings and Unicode strings. ASCII strings are delimited by ’...’, "..." or by ’..’ or """...""". Triple quotes delimit multiline strings. Unicode strings start with a u followed by the string containing Unicode characters. A Unicode string can be converted into an ASCII string by choosing an encoding for example:

6 number is 3

The last notation is more explicit and less error prone, and is to be preferred.