Type Stubs for PyMySQL

Warnings

• gotcha 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.
  Fix: Ensure both `pymysql` and `types-pymysql` are installed (`pip install pymysql types-pymysql`).
• gotcha 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.
  Fix: Consult your type checker's documentation (e.g., `mypy --install-types` or configuring `pyproject.toml`) to ensure it correctly finds `types-pymysql`.
• gotcha 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.
  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.

Install

• pip install types-pymysql Install `types-pymysql`

Imports

• pymysql

  import pymysql

  Type stubs are not imported directly at runtime; they provide type information for the original library (`pymysql`).
• Connection

  from pymysql import Connection

  Type stubs enhance type checking for objects like `Connection` from `pymysql`.
• DictCursor

  from pymysql.cursors import DictCursor

  Type stubs provide accurate return types for cursors like `DictCursor`.

Quickstart

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.

import pymysql
from pymysql.cursors import DictCursor
import os

# These environment variables simulate configuration for a MySQL database.
# Replace with your actual database details or set environment variables.
DB_HOST = os.environ.get('MYSQL_HOST', 'localhost')
DB_USER = os.environ.get('MYSQL_USER', 'root')
DB_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'password')
DB_NAME = os.environ.get('MYSQL_DB', 'test_db')

def get_example_data() -> list[dict]:
    """Connects to a MySQL database and fetches some example data."""
    try:
        # types-pymysql provides type hints for pymysql.connect's return (Connection)
        with pymysql.connect(
            host=DB_HOST,
            user=DB_USER,
            password=DB_PASSWORD,
            database=DB_NAME,
            cursorclass=DictCursor # Type stubs help with DictCursor return types
        ) as conn: # 'conn' is typed as 'pymysql.connections.Connection'
            with conn.cursor() as cursor: # 'cursor' is typed as 'pymysql.cursors.DictCursor'
                # Type stubs ensure 'execute' and 'fetchall' method signatures are known
                cursor.execute("SELECT 1 as id, 'hello' as message")
                result: list[dict] = cursor.fetchall()
                return result
    except pymysql.Error as e:
        print(f"Database connection or query error: {e}")
        return []

if __name__ == "__main__":
    # This code requires 'pymysql' to be installed and a running MySQL server.
    # 'types-pymysql' enhances static analysis of this code.
    data = get_example_data()
    if data:
        print("Fetched data:", data)
    else:
        print("Failed to fetch data. Check database connection and `pymysql` installation.")