spyder-ide / spyder-docs

Documentation for Spyder, the Scientific Python Development Environment
https://docs.spyder-ide.org
MIT License
33 stars 283 forks source link

Describe and clarify caveats with the Editor's "Run file" executing in an empty namespace #333

Open CAM-Gerlach opened 1 year ago

CAM-Gerlach commented 1 year ago

Issue Report

Issue Description

Adapted from my comment originally made in a Google Doc with @steff456 and @hyounes4560 that resulted in #331

This one's a little tricky for us to explain, but also rather important to explain well to users, e.g. as an important admonition.

Specifically, it refers to the default behavior (i.e. if Run in console's namespace instead of an empty one is checked in either the global or per-file Run configuration) where when running a file with Run File, the code is executed in a fresh, empty namespace rather than the console's one, so if e.g. in a new console, they run

[In 1] a = 3

Then they have a script that's just e.g.

print(a * 2)

Running the script with Run File will cause it to exit with a NameError, as the script does not define the name a (which is usually a user error).

However, the console's namespace (and thus the Variable Explorer, etc) will update with any updated values from the script, e.g. if they have a script

a = 6
b = a * 2

After running it, the value of the name a in the console will be set to 6, and the name b will be defined as having the value 12.

This behavior helps avoid common user mistakes and hard to debug script behavior, but can confuse some users as to why scripts aren't "seeing" the names or their values they define in the Console (and users have raised issues about it), so its worth explaining clearly, IMO.

Where is the relevant portion of the documentation located?

In Panes --> Editor --> Running code --> Run File

What would you suggest it be replaced with?

A description of the above

Other information