Changes between Version 67 and Version 68 of DeveloperGuidelines/CodeConventions


Ignore:
Timestamp:
01/20/18 21:38:41 (4 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines/CodeConventions

    v67 v68  
    2626}}}
    2727
    28 === Print Statements ===
    29 
    30 For compatibility with WSGI as well as newer web2py (>=2.15), using the {{{print}}} statement in web application sources is '''strongly discouraged'''.
    31 
    32 CLI scripts containing print statements will even '''crash''' since gluon/shell.py now future-imports the {{{print()}}}-function.
    33 
    34 For everything that is to be executed in the restricted environment (i.e. all server code):
    35  - for messages explaining mandatory crashes that prevent the system from running at all (e.g. mandatory module import failures), use {{{sys.stderr.write()}}}
    36  - 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
    37  - for temporary debug output in code under development, use {{{sys.stderr.write()}}}
    38  - if absolutely necessary (re-think your design!), add the future-import to the file and use the print-''function''
    39 
    40 For CLI scripts:
    41  - use {{{sys.stderr.write()}}} for status/error messages, or {{{sys.stdout.write()}}} for results
    42  - alternatively, add the future-import to the script and use the print-function
    43 
    44 Using {{{sys.std*.write()}}} (remember that write expects string/buffer, so you must convert any parameters explicitly):
    45 {{{#!python
    46 import sys
    47 
    48 # For status/error/debug messages:
    49 sys.stderr.write("Here is a status message\n")
    50 
    51 # For results:
    52 sys.stdout.write("%s\n" % result)
    53 }}}
    54 
    55 Using the logger:
    56 {{{#!python
    57 from gluon import current
    58 
    59 # Use this for any permanent message output in server code:
    60 current.log.error("Here is an error message")
    61 
    62 current.log.debug("And this is a debug message")
    63 }}}
    64 
    65 If neither of the above is possible, import+use the print-function:
    66 {{{#!python
    67 # This must be the first statement in the file:
    68 from __future__ import print_function
    69 
    70 # Then use the print-function:
    71 print("The print-function", "accepts", "multiple arguments")
    72 
    73 # Remember that server code must write to stderr, not stdout:
    74 print("Direct output to stderr", file=sys.stderr)
    75 }}}
    7628=== Quotes ===
    7729
     
    259211
    260212Remember 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.
     213
     214=== Print Statements ===
     215
     216For compatibility with WSGI as well as newer web2py (>=2.15), using the {{{print}}} statement in web application sources is '''strongly discouraged'''.
     217
     218CLI scripts containing print statements will even '''crash''' since gluon/shell.py now future-imports the {{{print()}}}-function.
     219
     220For everything that is to be executed in the restricted environment (i.e. all server code):
     221 - for messages explaining mandatory crashes that prevent the system from running at all (e.g. mandatory module import failures), use {{{sys.stderr.write()}}}
     222 - 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
     223 - for temporary debug output in code under development, use {{{sys.stderr.write()}}}
     224 - if absolutely necessary (re-think your design!), add the future-import to the file and use the print-''function''
     225
     226For CLI scripts:
     227 - use {{{sys.stderr.write()}}} for status/error messages, or {{{sys.stdout.write()}}} for results
     228 - alternatively, add the future-import to the script and use the print-function
     229
     230Using {{{sys.std*.write()}}} (remember that write expects string/buffer, so you must convert any parameters explicitly):
     231{{{#!python
     232import sys
     233
     234# For status/error/debug messages:
     235sys.stderr.write("Here is a status message\n")
     236
     237# For results:
     238sys.stdout.write("%s\n" % result)
     239}}}
     240
     241Using the logger:
     242{{{#!python
     243from gluon import current
     244
     245# Use this for any permanent message output in server code:
     246current.log.error("Here is an error message")
     247
     248current.log.debug("And this is a debug message")
     249}}}
     250
     251If neither of the above is possible, import+use the print-function:
     252{{{#!python
     253# This must be the first statement in the file:
     254from __future__ import print_function
     255
     256# Then use the print-function:
     257print("The print-function", "accepts", "multiple arguments")
     258
     259# Remember that server code must write to stderr, not stdout:
     260print("Direct output to stderr", file=sys.stderr)
     261}}}
     262
    261263=== Nulls ===
    262264Nulls 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.