pandas-dev/pandas · error · ValueError

{k} is a python keyword

Error message

{k} is a python keyword

What it means

Raised by register_option (config.py:575-576) as a ValueError when any path segment of the key is a Python keyword (checked via keyword.iskeyword). Keywords cannot serve as identifiers because attribute access via DictWrapper would be impossible.

Source

Thrown at pandas/_config/config.py:576

    key = key.lower()

    if key in _registered_options:
        raise OptionError(f"Option '{key}' has already been registered")
    if key in _reserved_keys:
        raise OptionError(f"Option '{key}' is a reserved key")

    # the default value should be legal
    if validator:
        validator(defval)

    # walk the nested dict, creating dicts as needed along the path
    path = key.split(".")

    for k in path:
        if not re.match("^" + tokenize.Name + "$", k):
            raise ValueError(f"{k} is not a valid identifier")
        if keyword.iskeyword(k):
            raise ValueError(f"{k} is a python keyword")

    cursor = _global_config
    msg = "Path prefix to option '{option}' is already an option"

    for i, p in enumerate(path[:-1]):
        if not isinstance(cursor, dict):
            raise OptionError(msg.format(option=".".join(path[:i])))
        if p not in cursor:
            cursor[p] = {}
        cursor = cursor[p]

    if not isinstance(cursor, dict):
        raise OptionError(msg.format(option=".".join(path[:-1])))

    # a namespace already lives here, i.e. `key` is a path prefix to one or
    # more already-registered options; registering it would clobber them
    # (GH#29242)
    if isinstance(cursor.get(path[-1]), dict):

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Rename the segment to a non-keyword (e.g. 'display.klass' or 'display.if_value').
2. Pre-screen segments with `import keyword; keyword.iskeyword(seg)`.
3. Avoid Python reserved words when naming your option namespace.

Example fix

# before
cf.register_option('display.class', True)  # class is a python keyword

# after
cf.register_option('display.klass', True)

import keyword
def no_keywords(key: str) -> bool:
    return not any(keyword.iskeyword(seg) for seg in key.lower().split('.'))

def is_keyword_free(key: str) -> bool:
    import keyword
    return not any(keyword.iskeyword(s) for s in key.split('.'))

When it happens

Trigger: cf.register_option('display.class', ...) or 'display.if' — 'class' and 'if' are Python keywords.

Common situations: Naming an option after a Python construct (class, return, lambda, for, while, etc.).

Related errors

• {k} is not a valid identifier
• No such keys(s): {pat!r}
• Option '{key}' has already been registered
• Option '{key}' is a reserved key
• Path prefix to option '{option}' is already an option

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/562932498be5706f. Report an issue: GitHub.