Minor changes

Author: cdce8p

peps/pep-0824.rst

@@ -14,15 +14,15 @@ Abstract
 
 This PEP proposes adding two new operators.
 
-* The "``None`` coalescing" operator ``??``
+* The "``None``-coalescing" operator ``??``
 * The "Coalescing assignment" operator ``??=``
 
-The ``None`` coalescing operator evaluates the left hand side,
-checks if it is ``not None`` and returns the result. If the value is
-``None``, the right hand side is evaluated and returned.
+The ``None``-coalescing operator evaluates the left hand side,
+checks if it is ``not None`` and, if so, returns the result. If the
+value is ``None``, the right hand side is evaluated and returned.
 
 The coalescing assignment operator will only assign the right hand side
-if the left hand side evaluates to ``None``.
+to the left hand side if the left hand side evaluates to ``None``.
 
 They are roughly equivalent to:
 
@@ -42,14 +42,15 @@ Motivation
 ==========
 
 First officially proposed ten years ago in (the now deferred) :pep:`505`,
-the idea to add coalescing operators has been along for some time now,
-discussed at length in numerous threads, most recently in
+the idea to add ``None``-coalescing operators has been along for some
+time now, discussed at length in numerous threads, most recently in
 [#discuss_revisit_505]_. This PEP aims to capture the current state of
 discussion and proposes a specification for addition to the Python
 language. In contrast to :pep:`505`, it will only focus on the two
-coalescing operators. See the `Deferred Ideas`_ section for more details.
+``None``-coalescing operators. See the `Deferred Ideas`_ section for
+more details.
 
-``None`` coalescing operators are not a new invention. Several other
+``None``-coalescing operators are not a new invention. Several other
 modern programming languages have so called "``null`` coalescing"
 operators, including TypeScript [#ts]_, ECMAScript (a.k.a. JavaScript)
 [#js_1]_ [#js_2]_, C# [#csharp]_, Dart [#dart_1]_ [#dart_2]_,
@@ -61,7 +62,7 @@ checking for truthiness, looks for ``None`` values.
 Explicit checks for ``None``
 ----------------------------
 
-In Python ``None`` is often used to denote the absents of a value. As
+In Python ``None`` is often used to denote the absence of a value. As
 such it it common to have to check if a value is ``None`` to do some
 action or provide a fallback value. Python provides several options to
 do that, each with their own advantages and disadvantages. One such
@@ -77,7 +78,7 @@ option is a conditional statement:
         print(f"The value is {s.lower()}")
 
 While the intent is quite clear, the conditional statement is verbose
-and often requires repeating the variable expression. An common
+and often requires repeating the variable expression. A common
 alternative is the conditional expression:
 
 .. code-block:: python
@@ -128,7 +129,7 @@ values other then ``None``, too. Common ones include ``0``, ``""``,
 ``()``, ``[]``, ``{}``, ``set()`` or custom objects which overwrite
 ``__bool__``.
 
-The "``None`` coalescing" operator can bridge this gab by adding an
+The "``None``-coalescing" operator can bridge this gab by adding an
 alternative to ``or`` which explicitly checks only for ``None`` values.
 Adding ``??`` can keep the expression concise while clearly
 communicating the intent:
@@ -168,7 +169,7 @@ helpful for more complex expressions.
 ::
 
     def other(obj):
-        if obj.var.some_other_object.another_variable is not None:
+        if obj.var.some_other_object.another_variable is None:
             obj.var.some_other_object.another_variable = "fallback"
 
         # can be replaced with
@@ -178,7 +179,7 @@ helpful for more complex expressions.
 Specification
 =============
 
-The ``None`` coalescing operator
+The ``None``-coalescing operator
 --------------------------------
 
 The ``??`` operator is added. It first evaluates the left hand side.
@@ -285,7 +286,7 @@ is extended to include the coalesce assignment.
 Backwards Compatibility
 =======================
 
-The coalescing operators are **opt-in**. Existing programs will
+The ``None``-coalescing operators are **opt-in**. Existing programs will
 continue to run as is. So far code which used either ``??`` or ``??=``
 raised a ``SyntaxError``.
 
@@ -299,8 +300,8 @@ There are no new security implications from this proposal.
 How to Teach This
 =================
 
-In a practical sense it might be helpful to think of the "``None``
-coalescing" operator ``??`` as a special case for the conditional ``or``
+In a practical sense it might be helpful to think of the "``None``-coalescing"
+operator ``??`` as a special case for the conditional ``or``
 operator, with the caveat that ``??`` checks for ``is not None`` instead
 of truthiness. As such it makes sense to include ``??`` when teaching
 about the other conditional operators ``and`` and ``or``.
@@ -325,9 +326,9 @@ Deferred Ideas
 -------------------------------
 
 :pep:`505` also suggest the addition of the ``None``-aware access
-operators ``?.`` and ``?[ ]``. As the coalescing operators have their
-own use cases, the ``None``-aware access operators were moved into a
-separate document, see PEP-823. Both proposals can be adopted
+operators ``?.`` and ``?[ ]``. As the ``None``-coalescing operators have
+their own use cases, the ``None``-aware access operators were moved
+into a separate document, see PEP-823. Both proposals can be adopted
 independently of one another.
 
 
@@ -376,7 +377,7 @@ is similar to other binary operators like ``+`` or ``**``. This is not
 the case. While binary operators first evaluate the left **and** right
 hand side before performing the operation, for ``??`` only the left hand
 side is evaluated if the values is ``not None``. As such the
-"``None`` coalescing" operator is much more closely related to the
+"``None``-coalescing" operator is much more closely related to the
 conditional operators ``or`` and ``and`` which also short-circuit the
 expression for truthy and falsy values respectively.
 
@@ -402,13 +403,13 @@ Common objections
 Just use a conditional expression
 ---------------------------------
 
-The coalescing operators can be considered syntactic sugar for
-existing conditional expressions and statements. As such some
+The ``None``-coalescing operators can be considered syntactic sugar
+for existing conditional expressions and statements. As such some
 questioned whether they would add anything meaningful to the
 language as a whole.
 
 As shown in the `Motivation`_ section, there are clear benefits to
-using the coalescing operators. To summarize them again:
+using the ``None``-coalescing operators. To summarize them again:
 
 - They help avoid repeating the variable expression or having to
   introduce a temporary variable.
@@ -425,9 +426,9 @@ Proliferation of ``None`` in code bases
 ---------------------------------------
 
 One of the reasons why :pep:`505` stalled was that some expressed their
-concern how coalescing and ``None``-aware operators will affect the code
-written by developers. If it is easier to work with ``None`` values,
-this will encourage developers to use them more. They believe that
+concern how ``None``-coalescing and ``None``-aware operators will affect
+the code written by developers. If it is easier to work with ``None``
+values, this will encourage developers to use them more. They believe that
 e.g. returning an optional ``None`` value from a function is usually an
 anti-pattern. In an ideal world the use of ``None`` would be limited as
 much as possible, for example with early data validation.
@@ -436,18 +437,18 @@ It is certainly true that new language features affect how the language
 as a whole develops. Therefore any changes should be considered carefully.
 However, just because ``None`` represents an anti-pattern for some, has
 not prevented the community as a whole from using it extensively. Rather
-the lack of coalescing operators has stopped developers from writing
-concise expressions and instead often leads to more complex code or such
-which can contain subtle errors, see the `Motivation`_ section for more
-details.
+the lack of ``None``-coalescing operators has stopped developers from
+writing concise expressions and instead often leads to more complex code
+or such which can contain subtle errors, see the `Motivation`_ section
+for more details.
 
 ``None`` is not special enough
 ------------------------------
 
 Some mentioned that ``None`` is not special enough to warrant dedicated
 operators.
 
-Coalescing operators have been added to a number of other modern
+``None``-coalescing operators have been added to a number of other modern
 programming languages. Furthermore, adding ``??`` and ``??=`` is
 something which was suggested numerous times since :pep:`505` was
 first proposed ten years ago.