redis/redis-py · error · ValueError

Upstream driver name must use a Python package-style name…

Error message

Upstream driver name must use a Python package-style name: start with a lowercase letter and contain only lowercase letters, digits, hyphens, and underscores (e.g., 'django-redis').

What it means

_validate_driver_name (redis/driver_info.py:42) enforces that an upstream driver name matches ^[a-z][a-z0-9_-]*$ — a simplified PEP 503 distribution-name rule. add_upstream_driver calls this so the encoded LIB-NAME (name(driver_vver;...)) stays parseable and matches conventions used by other Redis clients. Names with uppercase letters, leading digits, dots, slashes, spaces, or unicode are rejected.

Solutions

Normalize the package name: lower-case it and run re.sub(r'[-_.]+', '-', name) before passing to add_upstream_driver.
Start the name with a lowercase ASCII letter and use only lowercase letters, digits, hyphens, underscores.
Add a unit test that feeds your package metadata through the normalizer so CI catches a bad name before release.

Example fix

// before
info.add_upstream_driver(importlib.metadata.metadata('My-Pkg')['Name'], VERSION)
// after
import re
raw = importlib.metadata.metadata('My-Pkg')['Name']
name = re.sub(r'[-_.]+', '-', raw).lower()
info.add_upstream_driver(name, VERSION)

Defensive patterns

Strategy: validation

Validate before calling

import re
def normalize_driver_name(name: str) -> str:
    return re.sub(r'[-_.]+', '-', name.strip()).lower()
def is_valid_driver_name(name: str) -> bool:
    return bool(re.match(r'^[a-z][a-z0-9_-]*$', name))

Type guard

import re
def is_valid_driver_name(name) -> bool:
    return isinstance(name, str) and bool(re.match(r'^[a-z][a-z0-9_-]*$', name))

Prevention

Normalize package names to PEP 503 form (lower-case, runs of -_. collapsed to -) before registering.
Add a CI test that runs your package name through the normalizer.
Never derive the driver name from user/free-form input without sanitizing.

When it happens

Trigger: driver_info.add_upstream_driver('Django-Redis', '5.4.0') (uppercase), add_upstream_driver('4redis', ...) (leading digit), add_upstream_driver('my.driver', ...) (dot), add_upstream_driver('django redis', ...) (space). The call happens when a higher-level driver (django-redis, celery, rq) registers itself with redis-py.

Common situations: A framework wrapping redis-py auto-registering its package metadata without normalizing the project name to lower-case PEP 503 form; reading the name from a PyPI title that has mixed case.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/6996914d6bc10042. Report an issue: GitHub.

Appendix: source

Thrown at redis/driver_info.py:42


def _validate_driver_name(name: str) -> None:
    """Validate an upstream driver name.

    The name should look like a typical Python distribution or package name,
    following a simplified form of PEP 503 normalisation rules:

    * start with a lowercase ASCII letter
    * contain only lowercase letters, digits, hyphens and underscores

    Examples of valid names: ``"django-redis"``, ``"celery"``, ``"rq"``.
    """

    import re

    _validate_no_invalid_chars(name, "Driver name")
    if not re.match(r"^[a-z][a-z0-9_-]*$", name):
        raise ValueError(
            "Upstream driver name must use a Python package-style name: "
            "start with a lowercase letter and contain only lowercase letters, "
            "digits, hyphens, and underscores (e.g., 'django-redis')."
        )


def _validate_driver_version(version: str) -> None:
    _validate_no_invalid_chars(version, "Driver version")


def _format_driver_entry(driver_name: str, driver_version: str) -> str:
    return f"{driver_name}_v{driver_version}"


@dataclass
class DriverInfo:
    """Driver information used to build the CLIENT SETINFO LIB-NAME and LIB-VER values.

View on GitHub (pinned to 6a6b581b48)