Automatically promote nonlocal as needed

[scauligi]

Promote nonlocal declarations to global ones if the "nearest" matching definition is in the global scope.

Also addresses #2507; can be considered a fix if we decide that the explicit-nonlocal formulation is the proper way to do things.

[Kodiologist]

Nice branch name. Although my favorite is still one I saw for a PR to Cataclysm DDA, the-gods-outlawed-burnt-water-long-ago.

[Kodiologist]

Looks good overall. I agree that this closes #2507.

Let's update the documenation of nonlocal in api.rst.

Can you add a comment or docstring to OuterVar or ResolveOuterVars explaining that their purpose is to decide when to promote nonlocal to global?

Shouldn't OuterVar.__init__ call super().__init__? Even if ast.stmt.__init__ doesn't do anything right now, it might in the future. If super().__init__ actually won't work with what you need to do here, it's worth a comment saying so.

I think scope.parent is not None can be just scope.parent.

for name in has:
    if name in undefined:
        undefined.remove(name)

This is better written undefined = [name for name in undefined if name not in has].

Tests of nonlocal with let are probably better put in tests/native_tests/let.hy, next to the other let-with-nonlocal tests, than in your new test file nonlocal.hy.

ration-log isn't used after it's assigned. It would be better to only return health.

[scauligi]

Done! I also removed one of the new tests that wasn't actually using nonlocal, as it was redundant with tests already in native_tests/let.hy.

[Kodiologist]

Thanks. I wouldn't remove mention of what nonlocal compiles to; just say that it can compile to global or nonlocal statements (with links to the Python keywords), and explain in what circumstances it will produce global instead of nonlocal.

[Kodiologist]

My thinking is that the Hy documentation should always link to the relevant parts of the Python documentation for describing semantics. We want to neither recapitulate Python's documentation, nor leave obvious semantic issues undefined.

[scauligi]

Alright, updated the nonlocal doc 👍