{"record":{"id":"1da3458e192de851","repo":"python/cpython","slug":"module-must-be-a-string","errorCode":null,"errorMessage":"module must be a string","messagePattern":"module must be a string","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"Lib/_py_warnings.py","lineNumber":273,"sourceCode":"                   append=False):\n    \"\"\"Insert an entry into the list of warnings filters (at the front).\n\n    'action' -- one of \"error\", \"ignore\", \"always\", \"all\", \"default\", \"module\",\n                or \"once\"\n    'message' -- a regex that the warning message must match\n    'category' -- a class that the warning must be a subclass of\n    'module' -- a regex that the module name must match\n    'lineno' -- an integer line number, 0 matches all warnings\n    'append' -- if true, append to the list of filters\n    \"\"\"\n    if action not in {\"error\", \"ignore\", \"always\", \"all\", \"default\", \"module\", \"once\"}:\n        raise ValueError(f\"invalid action: {action!r}\")\n    if not isinstance(message, str):\n        raise TypeError(\"message must be a string\")\n    if not isinstance(category, type) or not issubclass(category, Warning):\n        raise TypeError(\"category must be a Warning subclass\")\n    if not isinstance(module, str):\n        raise TypeError(\"module must be a string\")\n    if not isinstance(lineno, int):\n        raise TypeError(\"lineno must be an int\")\n    if lineno < 0:\n        raise ValueError(\"lineno must be an int >= 0\")\n\n    if message or module:\n        import re\n\n    if message:\n        message = re.compile(message, re.I)\n    else:\n        message = None\n    if module:\n        module = re.compile(module)\n    else:\n        module = None\n\n    _wm._add_filter(action, message, category, module, lineno, append=append)","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_py_warnings.py#L255-L291","documentation":"Raised by warnings.filterwarnings when the module argument is not a str. Like message, module is a regex pattern string that the function compiles internally (re.compile(module)); pre-compiled patterns, bytes, or None passed positionally are rejected with TypeError('module must be a string').","triggerScenarios":"warnings.filterwarnings('ignore', module=re.compile('mymod')); module=b'mymod'; module=None passed explicitly; module/class arguments swapped in positional calls.","commonSituations":"Pre-compiled regex reuse; kwargs/positional mix-ups in long filterwarnings calls; programmatically assembled filter entries where a compiled pattern object leaks in; bytes literals copied from network-layer code.","solutions":["Pass the pattern as a str: module=r'^mymod\\..*'","Unwrap compiled patterns: getattr(module, 'pattern', module)","For 'all modules' use the default empty string, not None"],"exampleFix":"# before\nwarnings.filterwarnings('ignore', module=re.compile('mylib'))  # TypeError\n\n# after\nwarnings.filterwarnings('ignore', module=r'mylib')","handlingStrategy":"validation","validationCode":"def to_pattern_str(mod):\n    return getattr(mod, 'pattern', mod)\n\nimport warnings\nwarnings.filterwarnings('ignore', module=to_pattern_str(user_module))","typeGuard":"def is_pattern_str(mod) -> bool:\n    return isinstance(mod, str)","tryCatchPattern":null,"preventionTips":["module is a regex string compiled by the library; don't pre-compile","Use '' for 'all modules', not None","Use keyword arguments in long filterwarnings calls to avoid message/module swaps"],"tags":["warnings","validation","regex","filters"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}