From 3f695cfe22ed3a47ce058d91e667ffde0df658db Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Sun, 17 Mar 2024 23:09:18 -0400 Subject: [PATCH 1/5] gh-56374: Clarify documentation of nonlocal Redefine 'nonlocal scopes' in a way that excludes class scopes. Rearrange the rest of the doc. Add "Programmer's note". --- Doc/reference/simple_stmts.rst | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 810232e09dc5fa..ed61782ec31626 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -1006,25 +1006,29 @@ The :keyword:`!nonlocal` statement .. productionlist:: python-grammar nonlocal_stmt: "nonlocal" `identifier` ("," `identifier`)* -The :keyword:`nonlocal` statement causes the listed identifiers to refer to -previously bound variables in the nearest enclosing scope excluding globals. -This is important because the default behavior for binding is to search the -local namespace first. The statement allows encapsulated code to rebind -variables outside of the local scope besides the global (module) scope. - -Names listed in a :keyword:`nonlocal` statement, unlike those listed in a -:keyword:`global` statement, must refer to pre-existing bindings in an -enclosing scope (the scope in which a new binding should be created cannot -be determined unambiguously). - -Names listed in a :keyword:`nonlocal` statement must not collide with -pre-existing bindings in the local scope. +When the definition of a function or class is nested (enclosed) within +the definitions of other functions, its nonlocal scopes are the local +scopes of the enclosing functions. The :keyword:`nonlocal` statement +causes the listed identifiers to refer to names previously bound in +nonlocal scopes. It allows encapsulated code to rebind such nonlocal +identifiers. If a name is bound in more than one nonlocal scope, the +nearest binding is used. If a name is not bound in any nonlocal scope, +or if there is no nonlocal scope, a SyntaxError is raised. + +The nonlocal statement applies to the entire scope of a function or +class body. A SyntaxError is raised if a variable is used or +assigned to prior to its nonlocal declaration in the scope. .. seealso:: :pep:`3104` - Access to Names in Outer Scopes The specification for the :keyword:`nonlocal` statement. +**Programmer's note:** :keyword:`nonlocal` is a directive to the parser +and applies only to code parsed along with it. See the note for the +`!global` statement. + + .. _type: The :keyword:`!type` statement From 49b74466f8618c47704e8941d5999fe66d60d1ab Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Sun, 17 Mar 2024 23:22:26 -0400 Subject: [PATCH 2/5] Remove a '!'. --- Doc/reference/simple_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index ed61782ec31626..30b5c51a1f63ae 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -1026,7 +1026,7 @@ assigned to prior to its nonlocal declaration in the scope. **Programmer's note:** :keyword:`nonlocal` is a directive to the parser and applies only to code parsed along with it. See the note for the -`!global` statement. +`global` statement. .. _type: From c66f1da97540b234ac2f6a8f6c19d581ee064145 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Sun, 17 Mar 2024 23:38:37 -0400 Subject: [PATCH 3/5] Add `:keyword:` --- Doc/reference/simple_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 30b5c51a1f63ae..1a85ce98bed5c0 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -1026,7 +1026,7 @@ assigned to prior to its nonlocal declaration in the scope. **Programmer's note:** :keyword:`nonlocal` is a directive to the parser and applies only to code parsed along with it. See the note for the -`global` statement. +:keyword:`global` statement. .. _type: From da7017b9f52478bbf33a7b3d6d01045af3c73247 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 19 Mar 2024 13:44:09 -0400 Subject: [PATCH 4/5] Markup SyntaxError Co-authored-by: Kirill Podoprigora --- Doc/reference/simple_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 1a85ce98bed5c0..45efa710261ec5 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -1016,7 +1016,7 @@ nearest binding is used. If a name is not bound in any nonlocal scope, or if there is no nonlocal scope, a SyntaxError is raised. The nonlocal statement applies to the entire scope of a function or -class body. A SyntaxError is raised if a variable is used or +class body. A :exc:`SyntaxError` is raised if a variable is used or assigned to prior to its nonlocal declaration in the scope. .. seealso:: From 88a67718f10e5902d8c4bc94043826105b7e3a7a Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Tue, 19 Mar 2024 13:44:24 -0400 Subject: [PATCH 5/5] Markup SyntaxError --- Doc/reference/simple_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 45efa710261ec5..a253482156d3b4 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -1013,7 +1013,7 @@ causes the listed identifiers to refer to names previously bound in nonlocal scopes. It allows encapsulated code to rebind such nonlocal identifiers. If a name is bound in more than one nonlocal scope, the nearest binding is used. If a name is not bound in any nonlocal scope, -or if there is no nonlocal scope, a SyntaxError is raised. +or if there is no nonlocal scope, a :exc:`SyntaxError` is raised. The nonlocal statement applies to the entire scope of a function or class body. A :exc:`SyntaxError` is raised if a variable is used or