Changes between Version 67 and Version 68 of DeveloperGuidelines/CodeConventions

Timestamp:

01/20/18 21:38:41 (7 years ago)

Author:

Dominic König

Comment:

--

DeveloperGuidelines/CodeConventions

@@ -26 +26 @@
 }}}
 
-=== Print Statements ===
-
-For compatibility with WSGI as well as newer web2py (>=2.15), using the {{{print}}} statement in web application sources is '''strongly discouraged'''.
-
-CLI scripts containing print statements will even '''crash''' since gluon/shell.py now future-imports the {{{print()}}}-function.
-
-For everything that is to be executed in the restricted environment (i.e. all server code):
- - for messages explaining mandatory crashes that prevent the system from running at all (e.g. mandatory module import failures), use {{{sys.stderr.write()}}}
- - for all other permanent debug/error messages: use {{{current.log.*}}}, as it can be controlled centrally, and routed to a log file when web2py isn't console-run
- - for temporary debug output in code under development, use {{{sys.stderr.write()}}}
- - if absolutely necessary (re-think your design!), add the future-import to the file and use the print-''function''
-
-For CLI scripts:
- - use {{{sys.stderr.write()}}} for status/error messages, or {{{sys.stdout.write()}}} for results
- - alternatively, add the future-import to the script and use the print-function
-
-Using {{{sys.std*.write()}}} (remember that write expects string/buffer, so you must convert any parameters explicitly):
-{{{#!python
-import sys
-
-# For status/error/debug messages:
-sys.stderr.write("Here is a status message\n")
-
-# For results:
-sys.stdout.write("%s\n" % result)
-}}}
-
-Using the logger:
-{{{#!python
-from gluon import current
-
-# Use this for any permanent message output in server code:
-current.log.error("Here is an error message")
-
-current.log.debug("And this is a debug message")
-}}}
-
-If neither of the above is possible, import+use the print-function:
-{{{#!python
-# This must be the first statement in the file:
-from __future__ import print_function
-
-# Then use the print-function:
-print("The print-function", "accepts", "multiple arguments")
-
-# Remember that server code must write to stderr, not stdout:
-print("Direct output to stderr", file=sys.stderr)
-}}}
 === Quotes ===
 
@@ -259 +211 @@
 
 Remember that any uncaught exception leads to a HTTP 500 status with error ticket - and an HTTP 500 status in Eden is a bug by definition. Users can't do anything about error tickets, so the only legitimate reason to raise an uncaught exception in Eden is that you are 100% sure that the error condition leading to the exception is caused by a bug.
+
+=== Print Statements ===
+
+For compatibility with WSGI as well as newer web2py (>=2.15), using the {{{print}}} statement in web application sources is '''strongly discouraged'''.
+
+CLI scripts containing print statements will even '''crash''' since gluon/shell.py now future-imports the {{{print()}}}-function.
+
+For everything that is to be executed in the restricted environment (i.e. all server code):
+ - for messages explaining mandatory crashes that prevent the system from running at all (e.g. mandatory module import failures), use {{{sys.stderr.write()}}}
+ - for all other permanent debug/error messages: use {{{current.log.*}}}, as it can be controlled centrally, and routed to a log file when web2py isn't console-run
+ - for temporary debug output in code under development, use {{{sys.stderr.write()}}}
+ - if absolutely necessary (re-think your design!), add the future-import to the file and use the print-''function''
+
+For CLI scripts:
+ - use {{{sys.stderr.write()}}} for status/error messages, or {{{sys.stdout.write()}}} for results
+ - alternatively, add the future-import to the script and use the print-function
+
+Using {{{sys.std*.write()}}} (remember that write expects string/buffer, so you must convert any parameters explicitly):
+{{{#!python
+import sys
+
+# For status/error/debug messages:
+sys.stderr.write("Here is a status message\n")
+
+# For results:
+sys.stdout.write("%s\n" % result)
+}}}
+
+Using the logger:
+{{{#!python
+from gluon import current
+
+# Use this for any permanent message output in server code:
+current.log.error("Here is an error message")
+
+current.log.debug("And this is a debug message")
+}}}
+
+If neither of the above is possible, import+use the print-function:
+{{{#!python
+# This must be the first statement in the file:
+from __future__ import print_function
+
+# Then use the print-function:
+print("The print-function", "accepts", "multiple arguments")
+
+# Remember that server code must write to stderr, not stdout:
+print("Direct output to stderr", file=sys.stderr)
+}}}
+
 === Nulls ===
 Nulls make code much more complicated by introducing special cases that require special null-checking logic in every client, making code harder to understand and maintain. They often and easily cause hard-to-diagnose errors.