{"id":2868,"library":"asyncpg-stubs","title":"asyncpg-stubs","description":"asyncpg-stubs is a Python package providing type stubs to enhance static type checking and type inference for the high-performance asynchronous PostgreSQL client library, asyncpg. Currently at version 0.31.2, it maintains a close versioning scheme with asyncpg (matching major.minor versions) and receives frequent updates to ensure compatibility and accuracy.","status":"active","version":"0.31.2","language":"en","source_language":"en","source_url":"https://github.com/bryanforbes/asyncpg-stubs","tags":["async","database","postgresql","typing","stubs","type-hints"],"install":[{"cmd":"pip install asyncpg-stubs","lang":"bash","label":"Install"}],"dependencies":[{"reason":"Provides the runtime library for which these stubs offer type annotations. The stub's major.minor version should ideally match the asyncpg version used.","package":"asyncpg"},{"reason":"Required for advanced type hint features used within the stubs.","package":"typing-extensions"}],"imports":[{"note":"asyncpg-stubs provides type hints for symbols imported from the 'asyncpg' library; you do not typically import directly from 'asyncpg_stubs'.","symbol":"Connection","correct":"from asyncpg import Connection"},{"note":"asyncpg-stubs provides type hints for symbols imported from the 'asyncpg' library; you do not typically import directly from 'asyncpg_stubs'.","symbol":"Pool","correct":"from asyncpg import Pool"},{"note":"asyncpg-stubs provides type hints for symbols imported from the 'asyncpg' library; you do not typically import directly from 'asyncpg_stubs'.","symbol":"Record","correct":"from asyncpg import Record"}],"quickstart":{"code":"import asyncio\nimport asyncpg\nimport os\n\nasync def main():\n    # asyncpg-stubs provides type hints for asyncpg objects like Connection and Record.\n    # Replace with your PostgreSQL connection string or use environment variables.\n    # Example: DATABASE_URL='postgresql://user:password@localhost:5432/testdb'\n    conn_string = os.environ.get('DATABASE_URL', 'postgresql://user:password@localhost:5432/testdb')\n    \n    conn: asyncpg.Connection | None = None\n    try:\n        conn = await asyncpg.connect(conn_string)\n        print(\"Connected to PostgreSQL database.\")\n\n        # Execute a simple query\n        result: str = await conn.fetchval(\"SELECT 'Hello from asyncpg!'\")\n        print(f\"Query result: {result}\")\n\n        # Example with parameters and fetching a record\n        await conn.execute('''\n            CREATE TABLE IF NOT EXISTS my_table (\n                id serial PRIMARY KEY,\n                name text\n            );\n        ''')\n        await conn.execute(\"INSERT INTO my_table(name) VALUES($1)\", \"Test User\")\n        \n        record: asyncpg.Record | None = await conn.fetchrow(\"SELECT id, name FROM my_table WHERE name = $1\", \"Test User\")\n        if record:\n            print(f\"Fetched record: ID={record['id']}, Name={record['name']}\")\n        \n    except Exception as e:\n        print(f\"Error: {e}\")\n    finally:\n        if conn:\n            await conn.close()\n            print(\"Connection closed.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This example demonstrates a basic connection and query using `asyncpg`. When `asyncpg-stubs` is installed, type checkers (like MyPy or Pyright) will provide precise type hints for `asyncpg.Connection`, `asyncpg.Record`, and other asyncpg objects and methods used in this code, improving developer experience and catching potential type errors statically."},"warnings":[{"fix":"Ensure that `pip install asyncpg-stubs` installs a version compatible with your `asyncpg` installation, typically by specifying a similar version constraint (e.g., `asyncpg-stubs~=0.31.0` for `asyncpg~=0.31.0`).","message":"The `asyncpg-stubs` version should closely match the major and minor version of the `asyncpg` runtime library you are using. Mismatched versions can lead to incorrect type inference, type checking errors, or a lack of expected type information.","severity":"breaking","affected_versions":"<0.31.2"},{"fix":"Explicitly specify generic type arguments where previously implicit, or adjust your type checker's strictness settings if appropriate.","message":"Version `0.31.2` included a refactor to 'remove default type arguments'. If your codebase previously relied on implicit generic types that now require explicit specification for strict type checking, this change might flag new type errors.","severity":"gotcha","affected_versions":"0.31.2"},{"fix":"Upgrade to the latest `asyncpg-stubs` version to benefit from corrected and more precise type signatures for core `asyncpg` methods.","message":"Older versions of `asyncpg-stubs` (e.g., prior to `0.31.1`) had less accurate type signatures for methods like `fetchmany()` and `execute()`, which could lead to type checking errors when using these methods.","severity":"gotcha","affected_versions":"<0.31.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}