astral-sh/ruff · error

Expected all submodule imports to contain a '.'

Error message

Expected all submodule imports to contain a '.'

What it means

An internal expectation in the F401 unused-import fix message builder: while generating the explicit re-export suggestion for an __init__.py, a submodule import binding's module path contains no '.', even though the code path is guarded by submodule_import: true. The message text cannot be built for a non-dotted module.

Source

Thrown at crates/ruff_linter/src/rules/pyflakes/rules/unused_import.rs:207

            context,
        } = self;
        if *ignore_init_module_imports {
            match context {
                UnusedImportContext::DunderInitFirstParty {
                    dunder_all_count: DunderAllCount::Zero,
                    submodule_import: false,
                } => return Some(format!("Use an explicit re-export: `{module} as {module}`")),
                UnusedImportContext::DunderInitFirstParty {
                    dunder_all_count: DunderAllCount::Zero,
                    submodule_import: true,
                } => {
                    return Some(format!(
                        "Use an explicit re-export: \
                        `import {parent} as {parent}; import {binding}`",
                        parent = binding
                            .split('.')
                            .next()
                            .expect("Expected all submodule imports to contain a '.'")
                    ));
                }
                UnusedImportContext::DunderInitFirstParty {
                    dunder_all_count: DunderAllCount::One,
                    submodule_import: false,
                } => return Some(format!("Add unused import `{binding}` to __all__")),
                UnusedImportContext::DunderInitFirstParty {
                    dunder_all_count: DunderAllCount::One,
                    submodule_import: true,
                } => {
                    return Some(format!(
                        "Add `{}` to __all__",
                        binding
                            .split('.')
                            .next()
                            .expect("Expected all submodule imports to contain a '.'")
                    ));
                }

View on GitHub (pinned to 26f38c119c)

Solutions

1. Check how the binding was classified as a submodule import without a dotted name
2. Fall back to a generic message when the module name has no '.'

When it happens

Trigger: Thrown at crates/ruff_linter/src/rules/pyflakes/rules/unused_import.rs:207 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/70ae40ac9aa6066f. Report an issue: GitHub.