message: Strengthen the warning about source code of lambda functions, until the issue is fixed. As found in this bug can lead not just to parse errors but incorrect code as well.
diff: @@ -645,16 +645,31 @@ to quickly diagnose whether the source code is available for a function.
  #### Source code of lambda functions
  -Key Point: Declare lambda functions on separate lines to avoid failures to
  -load their source code.
  +Important: Declare lambda functions on single lines to make sure their source
  +code loads correctly.
  The Python runtime exposes the source code of lambda functions, however it
  -may include surrounding code. Typically, the code includes all the lines that
  -contained the lambda function, including surrounding code. This may make it
  +may omit parts of the actual body, or include surrounding code. This may make it
  impossible to parse the exact source code of the lambda function.
  -For example, consider the declaration of a lambda function below, which
  -is otherwise valid Python code:
  +For example, consider the declaration of a lambda function below:
  +
  +```
  +foo = (
  + lambda y: lambda x: x * y
  + - y
  +)
  +```
  +
  +The Python runtime will report the following source code for `foo`:
  +
  +```
  +>>> inspect.getsource(foo)
  +' lambda y: lambda x: x*y \n'
  +```
  +
  +In other cases, the source code it returns is not valid Python code, resulting
  +in an error:
  ```
  foo = (
  @@ -662,20 +677,30 @@ foo = (
  lambda: x)
  ```
  -The Python runtime will report the following source code for `foo[1]`:
  +The reported source code contains an invalid token `)`:
  ```
  >>> inspect.getsource(foo[1])
  ' lambda: x)\n'
  ```
  -The code is the entire line of code at which the lambda was declared. Because
  -the line is part of a larger expression, the line itself is not syntactically
  -correct and cannot be parsed.
  +This shortcoming can be avoided by declaring the lambda in a single assignment
  +or return value, and avoiding placing it inside parentheses which could cause
  +auto-formatting tools to break it into multiple lines:
  -This shortcoming can be avoided by declaring the lambda function separately:
  ```
  +# Good - single assignment
  my_lambda = lambda: x
  -foo = ('bar', my_lambda)
  +
  +# Good - single return
  +return lambda x, y: x*y - y
  +```
  +
  +```
  +# Bad - wrapped in parentheses
  +my_lambda = (lambda x, y: x * y - y)
  +
  +# Bad - inlined in another expression
  +foo(lambda x, y: x + y, bar)
  ```
  