I want to provide type hints for the IDE tab completion (and IDE type linter) for the loop variable over Pandas' DataFrame itertuples(). I could do this with typing.NamedTuple, but I though that collections.namedtuple would be enough:

row: namedtuple('Pandas', ['Index', 'author_name'])
for row in authors_df.itertuples():
    print(f"{row.Index=}, {row.author_name}")

The PyCharms linter does not see any problems, and I get tab completion... however, the GitHub CI Action, that runs flake8 linter, shows the following error:

src/package/source.py:728:21: F821 undefined name 'Pandas'
    row: namedtuple('Pandas', ['Index', 'author_name'])

Is flake8 correct? How can I avoid this warning (if it is wrong), or how can I go about silencing it?

I want to provide type hints for the IDE tab completion (and IDE type linter) for the loop variable over Pandas' DataFrame itertuples(). I could do this with typing.NamedTuple, but I though that collections.namedtuple would be enough:

row: namedtuple('Pandas', ['Index', 'author_name'])
for row in authors_df.itertuples():
    print(f"{row.Index=}, {row.author_name}")

The PyCharms linter does not see any problems, and I get tab completion... however, the GitHub CI Action, that runs flake8 linter, shows the following error:

src/package/source.py:728:21: F821 undefined name 'Pandas'
    row: namedtuple('Pandas', ['Index', 'author_name'])

Is flake8 correct? How can I avoid this warning (if it is wrong), or how can I go about silencing it?

• python
• pandas
• python-typing
• flake8

1 Answer 1

flake8 is correct, and an IDE which follows conventions would not recognise your given annotation to provide autocompletion hints. PyCharm has historically implemented annotation parsing before the typing ecosystem was mature, and as such it may do things which are non-conformant, left over from legacy implementations.

For the purposes of type annotations, collections.namedtuple has a similar declaration format to typing.NamedTuple's factory function form, which is the following:

NAME = namedtuple("NAME", [<items spec>])

# Usage
row: NAME

Where [<items spec>] depends on whether you want your named tuple items (attributes) to be typed (typing.NamedTuple) or not (collections.namedtuple). A sequence of strings like ["Index", "author_name"] implies untyped attributes, which is sufficient for just autocompletion.

The point here is that the assignment statement, NAME = namedtuple("NAME", ...), must be present to allow usage of NAME inside type annotations. Type annotations have their own grammar, and a direct call expression like namedtuple("Pandas", ...) does not conform to this grammar, and is invalid inside type annotations.

Note that the form NAME = <factory function>("NAME", ...) is found in multiple places in Python typing.*. Along with NamedTuple, the other ones currently are:

• NewType
• ParamSpec
• TypeAliasType
• TypedDict
• TypeVar
• TypeVarTuple

Like NamedTuple, you must provide the assignment statement for these, and cannot directly use any of these in a call expression in a type annotation.