diff --git a/pyguide.md b/pyguide.md
index 4d38b3c..da8e70f 100644
--- a/pyguide.md
+++ b/pyguide.md
@@ -1071,7 +1071,7 @@ implement computations a subclass may ever want to override and extend.
### 2.14 True/False Evaluations
-Use the "implicit" false if at all possible.
+Use the "implicit" false if at all possible (with a few caveats).
@@ -1963,9 +1963,9 @@ aptly described using a one-line docstring.
None, this section is not required. It may also be omitted if the docstring
starts with Returns or Yields (e.g. `"""Returns row from Bigtable as a tuple
of strings."""`) and the opening sentence is sufficient to describe the
- return value. Do not imitate 'NumPy style'
- ([example](http://numpy.org/doc/stable/reference/generated/numpy.linalg.qr.html)),
- which frequently documents a tuple return value as if it were multiple
+ return value. Do not imitate older 'NumPy style'
+ ([example](https://numpy.org/doc/1.24/reference/generated/numpy.linalg.qr.html)),
+ which frequently documented a tuple return value as if it were multiple
return values with individual names (never mentioning the tuple). Instead,
describe such a return value as: "Returns: A tuple (mat_a, mat_b), where
mat_a is ..., and ...". The auxiliary names in the docstring need not
@@ -2477,27 +2477,36 @@ documentation must explain clearly how resource lifetime is managed.
Use `TODO` comments for code that is temporary, a short-term solution, or
good-enough but not perfect.
-A `TODO` comment begins with the word `TODO` in all caps, and a parenthesized
-context identifier. Ideally a bug reference, sometimes a username. A bug
-reference like `TODO(https://crbug.com/bug_id_number):` is
-preferable, because bugs are tracked and have follow-up comments, whereas
-individuals move around and may lose context over time. The `TODO` is followed by an explanation of
-what there is to do.
-
+A `TODO` comment begins with the word `TODO` in all caps, a following colon, and
+a link to a resource that contains the context, ideally a bug reference. A bug
+reference is preferable because bugs are tracked and have follow-up comments.
+Follow this piece of context with an explanatory string introduced with a hyphen
+`-`.
The purpose is to have a consistent `TODO` format that can be searched to find
-out how to get more details. A `TODO` is not a commitment that the person
-referenced will fix the problem. Thus when you create a `TODO` with a username,
-it is almost always your *own* username that is given.
+out how to get more details.
+
+```python
+# TODO: crbug.com/192795 - Investigate cpufreq optimizations.
+```
+
+Old style, formerly recommended, but discouraged for use in new code:
+
```python
# TODO(crbug.com/192795): Investigate cpufreq optimizations.
-# TODO(yourusername): File an issue and use a '*' for repetition.
+# TODO(yourusername): Use a "\*" here for concatenation operator.
+```
+
+Avoid adding TODOs that refer to an individual or team as the context:
+
+```python
+# TODO: @yourusername - File an issue and use a '*' for repetition.
```
If your `TODO` is of the form "At a future date do something" make sure that you
either include a very specific date ("Fix by November 2009") or a very specific
event ("Remove this code when all clients can handle XML responses.") that
-future code maintainers will comprehend.
+future code maintainers will comprehend. Issues are ideal for tracking this.
@@ -2722,7 +2731,9 @@ Always use a `.py` filename extension. Never use dashes.
class.
- Prepending a single underscore (`_`) has some support for protecting module
- variables and functions (linters will flag protected member access).
+ variables and functions (linters will flag protected member access). Note
+ that it is okay for unit tests to access protected constants from the
+ modules under test.
- Prepending a double underscore (`__` aka "dunder") to an instance variable
or method effectively makes the variable or method private to its class
@@ -3327,15 +3338,16 @@ return type is the same as the argument type in the code above, use
#### 3.19.12 Imports For Typing
-For symbols from the `typing` and `collections.abc` modules used to support
-static analysis and type checking, always import the symbol itself. This keeps
-common annotations more concise and matches typing practices used around the
-world. You are explicitly allowed to import multiple specific classes on one
-line from the `typing` and `collections.abc` modules. Ex:
+For symbols (including types, functions, and constants) from the `typing` or
+`collections.abc` modules used to support static analysis and type checking,
+always import the symbol itself. This keeps common annotations more concise and
+matches typing practices used around the world. You are explicitly allowed to
+import multiple specific symbols on one line from the `typing` and
+`collections.abc` modules. For example:
```python
from collections.abc import Mapping, Sequence
-from typing import Any, Generic
+from typing import Any, Generic, cast, TYPE_CHECKING
```
Given that this way of importing adds items to the local namespace, names in