gh-137376: Add note on top-level `global` declarations (GH-137707)

Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>

diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 2a72af4e9a32992bf7383693e0260be524e64c0d..3f2bcb2a60ee787073f7415efaf7138101b69fd1 100644 (file)
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -971,10 +971,17 @@ as globals. It would be impossible to assign to a global variable without
 :keyword:`!global`, although free variables may refer to globals without being
 declared global.
 
-The :keyword:`global` statement applies to the entire scope of a function or
-class body. A :exc:`SyntaxError` is raised if a variable is used or
+The :keyword:`!global` statement applies to the entire current scope
+(module, function body or class definition).
+A :exc:`SyntaxError` is raised if a variable is used or
 assigned to prior to its global declaration in the scope.
 
+At the module level, all variables are global, so a :keyword:`!global`
+statement has no effect.
+However, variables must still not be used or
+assigned to prior to their :keyword:`!global` declaration.
+This requirement is relaxed in the interactive prompt (:term:`REPL`).
+
 .. index::
    pair: built-in function; exec
    pair: built-in function; eval