gh-137376: Add note on top-level global declarations

encukou · encukou · commit 72f0c745ec5f · 2025-08-13T13:54:45.000+02:00
diff --git 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 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
