feat(dynamodb): add key_schema parameter to read_items to bypass Desc…

[jagannalla]

Description

This PR resolves #2396 by introducing an optional key_schema parameter to the wr.dynamodb.read_items function.

Problem:

Currently, wr.dynamodb.read_items performs an implicit DescribeTable API call under the hood on every invocation to resolve the table's hash and range keys. In loops, high-traffic scripts, or memory/time-constrained environments (like AWS Lambda), this redundant lookup:

1. Introduces unnecessary network latency.
2. Frequently triggers DynamoDB metadata API throttling limits.

Solution:

Added an optional key_schema parameter to the read_items method and its corresponding type stub overloads.

• If key_schema is supplied by the user (e.g. [{"AttributeName": "key", "KeyType": "HASH"}]), the library skips the costly DescribeTable API request entirely and uses the provided schema.
• If key_schema is omitted, the library defaults to its existing behavior of calling DescribeTable dynamically, ensuring 100% backward compatibility.

---

Related Issue

Closes #2396

---

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature / Enhancement (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

---

How Has This Been Tested?

Automated Tests:

Added a comprehensive unit test suite in tests/unit/test_moto.py named test_dynamodb_read_items_with_key_schema to verify:

1. Functional Correctness: Ensures read_items works flawlessly and parses records exactly as expected when key_schema is provided.
2. Bypass Verification: Spies on the underlying botocore client and asserts that zero DescribeTable calls are made under the hood when key_schema is supplied.
3. Backward Compatibility: Asserts that DescribeTable is called exactly once when key_schema is omitted.

All 44 mocked unit tests passed successfully:

.venv/bin/pytest tests/unit/test_moto.py
======================== 44 passed in 4.30s ========================

[kukushking]

Please update the docstring with the new key_schema parameter. Make sure to cover why it is added to help other users know that they can skip DescribeTable call.

Thank you!

[kukushking]

Thank you @jagannalla !

[jagannalla]

Hi @kukushking, thank you for merging the PR! Glad to have this improvement included.