`F821`: Incorrectly reports use before assignment for conditional import

[k4lizen]

Summary

I do this in my code:

from __future__ import annotations

import pwndbg


def myfunc() -> None:
    # note that dbg is an object in the pwndbg module
    if pwndbg.dbg.is_gdblib_available():
        import pwndbg.gdblib.functions
        _ = pwndbg.gdblib.functions.functions
        print("yes!")
    else:
        print("no!")

myfunc()

And I get the following:

~❯ uv run ruff check repro.py
F823 Local variable `pwndbg` referenced before assignment
 --> repro.py:7:8
  |
6 | def myfunc() -> None:
7 |     if pwndbg.dbg.is_gdblib_available():
  |        ^^^^^^
8 |         import pwndbg.gdblib.functions
9 |         _ = pwndbg.gdblib.functions.functions
  |

Found 1 error.

What is going on?

Repro

git clone https://github.com/k4lizen/pwndbg/
cd pwndbg
git checkout 4588a455f5e511b567458ef618eb627788b539d5
uv run --all-groups --all-extras ruff check repro.py

Version

ruff 0.14.10

[ntBre]

Thanks for the report! As pointed out on the PR (#22472 (comment)), this code raises an UnboundLocalError at runtime, so it seems like Ruff is giving an accurate diagnostic. Is there a reason you think the error should be suppressed?

I cloned pwndbg and tried this to confirm:

git clone https://github.com/pwndbg/pwndbg.git
cd pwndbg/
uv run python <<EOF
from __future__ import annotations

import pwndbg


def myfunc() -> None:
    # note that dbg is an object in the pwndbg module
    if pwndbg.dbg.is_gdblib_available():
        import pwndbg.gdblib.functions
        _ = pwndbg.gdblib.functions.functions
        print("yes!")
    else:
        print("no!")

myfunc()
EOF

Traceback (most recent call last):
  File "<stdin>", line 15, in <module>
  File "<stdin>", line 8, in myfunc
UnboundLocalError: cannot access local variable 'pwndbg' where it is not associated with a value

This was surprising to me too, but the local import pwndbg... makes the pwndbg reference within the function a local variable reference, which is then used before its definition. There's even a Python FAQ entry on this topic, although they use an assignment rather than an import in the example.

[k4lizen]

ou damn my bad, I thought this was fine at runtime. if theres a way for ruff to detect this case and maybe point to an explanation of whats going on that would be nice, but in general I'm fine with closing this issue.

i'm not sure what @dscorbett meant by this

This seems like a bug in the upstream rule.

[k4lizen]

as an aside, do you know what the valid/intended way is to achieve what i'm trying to do here?

[ntBre]

No worries at all, this was also confusing to me! I'll change the label to diagnostics, this could be an interesting use for a sub-diagnostic if it doesn't add too much complexity to the rule.

I think dscorbett was referring to the PR summary, which compared Ruff's implementation to pyflakes. I don't think you mentioned pyflakes, but the PR author checked the upstream tool to see if it also flagged this code.

as an aside, do you know what the valid/intended way is to achieve what i'm trying to do here?

I think if you declare pwndbg as global within the function, you can get the behavior you want:

 def myfunc() -> None:
+    global pwndbg
     # note that dbg is an object in the pwndbg module
     if pwndbg.dbg.is_gdblib_available():
         import pwndbg.gdblib.functions

I'm getting a different attribute error in that case, but I think that should work in general.

[k4lizen]

yup, can confirm that works, thanks!