# ===============================================
# LIST OF BUILT-IN PYTHON MODULES
# ===============================================
# This list contains all standard and built-in Python 3.x modules,
# including:
# 1. Core modules like: math, os, sys
# 2. Submodules like: collections.abc, http.client
# 3. Important classes from modules like: json.JSONEncoder
#
# Purpose: To facilitate checking whether a given module is built-in
# without the need for installation via pip or managing extra dependencies.
# ===============================================

BUILT_IN_PKGS = [
    "_thread",
    "_markupbase",
    "_dummy_thread",
    "__main__",
    "__future__",
    "ast",
    "array",
    "asynchat",
    "audioop",
    "asyncore",
    "atexit",
    "asyncio",
    "argparse",
    "aifc",
    "antigravity",
    "abc",
    "builtins",
    "base64",
    "bz2",
    "binascii",
    "bisect",
    "bdb",
    "binhex",
    "compileall",
    "codeop",
    "calendar",
    "copyreg",
    "cmd",
    "cgi",
    "cmath",
    "ctypes",
    "csv",
    "copy",
    "contextlib",
    "contextvars",
    "curses",
    "crypt",
    "colorsys",
    "cgitb",
    "concurrent",
    "configparser",
    "code",
    "collections",
    "codecs",
    "chunk",
    "decimal",
    "datetime",
    "doctest",
    "dis",
    "dataclasses",
    "difflib",
    "dbm",
    "ensurepip",
    "errno",
    "encodings",
    "enum",
    "email",
    "faulthandler",
    "fractions",
    "ftplib",
    "functools",
    "fnmatch",
    "formatter",
    "filecmp",
    "fileinput",
    "grp",
    "gc",
    "gettext",
    "getpass",
    "graphlib",
    "getopt",
    "gzip",
    "glob",
    "html",
    "hmac",
    "http",
    "hashlib",
    "heapq",
    "imaplib",
    "imghdr",
    "itertools",
    "imp",
    "inspect",
    "importlib",
    "idlelib",
    "ipaddress",
    "io",
    "json",
    "keyword",
    "logging",
    "locale",
    "lib2to3",
    "linecache",
    "lzma",
    "mailcap",
    "mailbox",
    "marshal",
    "msvcrt",
    "modulefinder",
    "msilib",
    "multiprocessing",
    "math",
    "mmap",
    "macpath",
    "mimetypes",
    "nntplib",
    "nis",
    "netrc",
    "numbers",
    "ntpath",
    "os.path",
    "optparse",
    "os",
    "operator",
    "ossaudiodev",
    "pwd",
    "posix",
    "py_compile",
    "pprint",
    "profile",
    "pyclbr",
    "pathlib",
    "pdb",
    "pkgutil",
    "pickletools",
    "plistlib",
    "pty",
    "pstats",
    "poplib",
    "pydoc",
    "pipes",
    "pickle",
    "posixpath",
    "platform",
    "quopri",
    "queue",
    "resource",
    "rlcompleter",
    "reprlib",
    "re",
    "random",
    "readline",
    "runpy",
    "smtplib",
    "sysconfig",
    "sndhdr",
    "shlex",
    "sunau",
    "struct",
    "socket",
    "site",
    "ssl",
    "stat",
    "symtable",
    "smtpd",
    "syslog",
    "socketserver",
    "shelve",
    "sys",
    "selectors",
    "select",
    "secrets",
    "spwd",
    "string",
    "shutil",
    "statistics",
    "sched",
    "stringprep",
    "subprocess",
    "sqlite3",
    "signal",
    "termios",
    "time",
    "turtle",
    "tracemalloc",
    "tokenize",
    "types",
    "timeit",
    "tarfile",
    "traceback",
    "test",
    "trace",
    "telnetlib",
    "textwrap",
    "tabnanny",
    "typing",
    "tkinter",
    "token",
    "threading",
    "tempfile",
    "tty",
    "urllib",
    "unittest",
    "unicodedata",
    "uuid",
    "uu",
    "venv",
    "wave",
    "winreg",
    "webbrowser",
    "winsound",
    "weakref",
    "warnings",
    "xmlrpc",
    "xml",
    "zipfile",
    "zipimport",
    "zlib",
    "os.path",
    "collections.abc",
    "collections.Counter",
    "collections.deque",
    "collections.namedtuple",
    "collections.OrderedDict",
    "collections.defaultdict",
    "collections.ChainMap",
    "concurrent.futures",
    "concurrent.futures.thread",
    "concurrent.futures.process",
    "http.client",
    "http.server",
    "http.cookies",
    "http.cookiejar",
    "email.mime",
    "email.message",
    "email.policy",
    "email.parser",
    "email.generator",
    "urllib.parse",
    "urllib.request",
    "urllib.response",
    "urllib.error",
    "urllib.robotparser",
    "xml.etree.ElementTree",
    "xml.dom",
    "xml.dom.minidom",
    "xml.sax",
    "xml.parsers",
    "tkinter.ttk",
    "tkinter.messagebox",
    "tkinter.filedialog",
    "tkinter.simpledialog",
    "tkinter.colorchooser",
    "logging.handlers",
    "logging.config",
    "unittest.mock",
    "unittest.TestCase",
    "unittest.TestSuite",
    "multiprocessing.managers",
    "multiprocessing.shared_memory",
    "multiprocessing.pool",
    "asyncio.streams",
    "asyncio.subprocess",
    "asyncio.queues",
    "asyncio.locks",
    "sqlite3.dbapi2",
    "decimal.Context",
    "re.Pattern",
    "re.Match",
    "datetime.date",
    "datetime.datetime",
    "datetime.time",
    "datetime.timedelta",
    "datetime.timezone",
    "json.JSONEncoder",
    "json.JSONDecoder",
    "itertools.islice",
    "itertools.chain",
    "itertools.combinations",
    "functools.partial",
    "functools.wraps",
    "functools.lru_cache",
    "random.Random",
    "random.SystemRandom",
    "hashlib.blake2b",
    "hashlib.blake2s",
    "hashlib.sha256",
    "ssl.SSLContext",
    "ssl.SSLSocket",
    "socket.socket",
    "socket.AF_INET",
    "socket.SOCK_STREAM",
    "threading.Thread",
    "threading.Lock",
    "threading.Event",
    "threading.Timer",
    "pathlib.Path",
    "pathlib.PurePath",
    "typing.List",
    "typing.Dict",
    "typing.Union",
    "typing.Optional",
    "typing.Callable",
    "encodings.utf_8",
    "encodings.ascii",
    "encodings.latin_1",
    "math.sqrt",
    "math.pi",
    "math.inf",
    "statistics.mean",
    "statistics.median",
    "statistics.stdev",
    "secrets.SystemRandom",
    "zipfile.ZipFile",
    "zipfile.ZipInfo",
    "tarfile.TarFile",
    "tarfile.TarInfo",
]

# ===============================================
# CREATE A FAST LOOKUP SET
# ===============================================
# Instead of performing a list comprehension every time (which can slow
# down lookup for large lists), we convert the list into a set at load time.
# Conversion to lowercase ensures case-insensitive checking.
#
# Using a set lookup is significantly faster than a list lookup (O(1) vs O(n)).
# ===============================================
_BUILT_IN_SET = set(pkg.lower() for pkg in BUILT_IN_PKGS)

# ===============================================
# FUNCTION: isbuiltin
# ===============================================
def isbuiltin(name: str) -> bool:
    """
    Checks whether the given name refers to a built-in Python module.

    PARAMETERS:
    -----------
    name : str
        The name of the module or submodule to check.
        It can be a top-level module, submodule, or even a class within a module.

    RETURNS:
    --------
    bool
        True if the module or submodule exists in Python's built-in modules.
        False if it does not exist.

    FEATURES / IMPROVEMENTS:
    ------------------------
    1. Performance:
       - Uses a set for fast lookup instead of a list.
       - Converts all elements to lowercase for case-insensitive search.

    2. Flexibility:
       - Automatically handles new built-in modules if added to the list.
       - Works for nested modules and specific classes within modules.

    3. Usage Example:
       >>> isbuiltin("os")
       True
       >>> isbuiltin("json.JSONEncoder")
       True
       >>> isbuiltin("nonexistent_module")
       False

    NOTES:
    ------
    - This function does not import the module; it purely checks against
      a pre-defined list of built-in modules.
    - This avoids overhead of importing modules and is safe for all Python environments.
    """
    return name.lower() in _BUILT_IN_SET