{"id":1762,"library":"types-pymysql","title":"Type Stubs for PyMySQL","description":"This package provides static type annotations (stubs) for the PyMySQL library, enabling type checkers like Mypy or Pyright to analyze code that uses PyMySQL. It helps catch type-related errors before runtime and improves IDE autocomplete and refactoring. The current version is 1.1.0.20260408, with updates often aligned with new `pymysql` releases or as needed by the typeshed project.","status":"active","version":"1.1.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["types","stubs","typing","mysql","database","type-checking"],"install":[{"cmd":"pip install types-pymysql","lang":"bash","label":"Install `types-pymysql`"}],"dependencies":[{"reason":"The runtime library for which these stubs provide type hints.","package":"pymysql","optional":true}],"imports":[{"note":"Type stubs are not imported directly at runtime; they provide type information for the original library (`pymysql`).","wrong":"import types_pymysql","symbol":"pymysql","correct":"import pymysql"},{"note":"Type stubs enhance type checking for objects like `Connection` from `pymysql`.","symbol":"Connection","correct":"from pymysql import Connection"},{"note":"Type stubs provide accurate return types for cursors like `DictCursor`.","symbol":"DictCursor","correct":"from pymysql.cursors import DictCursor"}],"quickstart":{"code":"import pymysql\nfrom pymysql.cursors import DictCursor\nimport os\n\n# These environment variables simulate configuration for a MySQL database.\n# Replace with your actual database details or set environment variables.\nDB_HOST = os.environ.get('MYSQL_HOST', 'localhost')\nDB_USER = os.environ.get('MYSQL_USER', 'root')\nDB_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'password')\nDB_NAME = os.environ.get('MYSQL_DB', 'test_db')\n\ndef get_example_data() -> list[dict]:\n    \"\"\"Connects to a MySQL database and fetches some example data.\"\"\"\n    try:\n        # types-pymysql provides type hints for pymysql.connect's return (Connection)\n        with pymysql.connect(\n            host=DB_HOST,\n            user=DB_USER,\n            password=DB_PASSWORD,\n            database=DB_NAME,\n            cursorclass=DictCursor # Type stubs help with DictCursor return types\n        ) as conn: # 'conn' is typed as 'pymysql.connections.Connection'\n            with conn.cursor() as cursor: # 'cursor' is typed as 'pymysql.cursors.DictCursor'\n                # Type stubs ensure 'execute' and 'fetchall' method signatures are known\n                cursor.execute(\"SELECT 1 as id, 'hello' as message\")\n                result: list[dict] = cursor.fetchall()\n                return result\n    except pymysql.Error as e:\n        print(f\"Database connection or query error: {e}\")\n        return []\n\nif __name__ == \"__main__\":\n    # This code requires 'pymysql' to be installed and a running MySQL server.\n    # 'types-pymysql' enhances static analysis of this code.\n    data = get_example_data()\n    if data:\n        print(\"Fetched data:\", data)\n    else:\n        print(\"Failed to fetch data. Check database connection and `pymysql` installation.\")\n","lang":"python","description":"This quickstart demonstrates how to use PyMySQL with type hints. Installing `types-pymysql` allows your type checker to understand the types returned by `pymysql.connect`, `conn.cursor()`, and methods like `cursor.execute()` and `cursor.fetchall()`, improving code quality and maintainability. Remember that `types-pymysql` provides *stubs*; you still need to `pip install pymysql` to run this code at runtime."},"warnings":[{"fix":"Ensure both `pymysql` and `types-pymysql` are installed (`pip install pymysql types-pymysql`).","message":"Installing `types-pymysql` provides *only* type annotations (stubs); it does not install the `pymysql` library itself. You must `pip install pymysql` separately for your application to function at runtime.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult your type checker's documentation (e.g., `mypy --install-types` or configuring `pyproject.toml`) to ensure it correctly finds `types-pymysql`.","message":"Type stubs are consumed by static type checkers (e.g., Mypy, Pyright). If your type checker isn't finding the stubs, ensure it's properly configured to discover installed type packages. Some environments might require explicit configuration for stub discovery.","severity":"gotcha","affected_versions":"All"},{"fix":"If encountering issues with new `pymysql` features, check the `typeshed` GitHub repository for updates or open an issue. Consider pinning `pymysql` to a version known to be well-supported by the current stubs.","message":"Type stubs in typeshed might occasionally lag behind the absolute latest features or minor versions of `pymysql`. While efforts are made to keep them up-to-date, new `pymysql` releases might introduce changes not immediately reflected in the stubs, leading to `Any` types or type-checking errors for very new features.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}