Skip to content

docs(examples): fix pyright errors in agentic examples - #568

Merged
leandrodamascena merged 3 commits into
ferrumio:mainfrom
vicolby:fm/pydynox-325-agentic-examples
Nov 1, 2026
Merged

leandrodamascena merged 3 commits into
ferrumio:mainfrom
vicolby:fm/pydynox-325-agentic-examples

Conversation

@vicolby

@vicolby vicolby commented Oct 31, 2026

Copy link
Copy Markdown
Contributor

Intent

Part of #325 (support strict type checking for mypy, pyright and ty). Fix the agentic examples (53 errors) and the fastapi import in async/. Measured on upstream main cdd8c85 (2026-10-25): type_checking/crud_types.py is already clean. docs/examples/agentic/ has 53 pyright errors: 14 missing third-party imports (smolagents, pydantic_ai, strands; add pyright reportMissingImports=false), 26 T | None attribute values used directly, 7 calls not awaited, 4 S3, 2 other (Employee.email in agentic/smolagents_encrypted.py:29, positional sync_scan args in agentic/strands_crud.py:110). Plus 1 missing fastapi import in docs/examples/async/. Decided: keep attributes typed T | None and add None checks in the examples. The S3Attribute library typing gap was fixed in #533.

What Changed

  • Updated the agentic examples (best_practices, pydantic_ai_*, smolagents_*, strands_*) to pass pyright. Optional attribute values now get None checks or defaults (for example doc.sk or "", emp.ssn is not None and ...). The S3Value narrowing uses an isinstance assert. Employee now declares the email attribute it uses.
  • Changed the query and scan calls in the examples to the typed API: partition_key=, sort_key_condition=Order.sk.begins_with(...) and filter_condition=Order.status == .... This replaces the raw expression strings and removes the positional sync_scan arguments in strands_crud.py. Optional tool parameters are now typed str | None.
  • Added [[tool.pyright.executionEnvironments]] entries in pyproject.toml for docs/examples/agentic and docs/examples/async/fastapi_example.py. They set reportMissingImports = false, because the example-only packages (smolagents, pydantic_ai, strands, fastapi) are not dev dependencies.

Part of #325.

Risk Assessment

✅ Low: The change only touches documentation example files and a pyright config block. Pyright run with python/ on the path reports 0 errors under docs/examples/agentic and resolves the fastapi import. The rewritten query/scan calls match the real Model.sync_query/sync_scan signatures, and the S3 assertions hold at runtime because save() replaces S3File with S3Value.

Testing

I built the extension with maturin and ran pyright 1.1.414 on the base commit (7f133f4) and the target commit. At base, docs/examples/agentic, async/fastapi_example.py and type_checking reported 53 errors; at the target they report 0. I then ran the real example modules against pydynox's in-memory backend with pass-through stubs for the strands and smolagents tool decorators. The rewritten query and scan calls and the None-safe sums all gave correct results. Running pyright over all of docs/examples/async also shows 4 errors in model_async.py, query_async.py and real_world.py (e.g. AsyncQueryResult.all); those files are outside this change's scope.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Pyright on agentic examples, fastapi_example.py and type_checking: 53 errors at base drop to 0 at target ✅ pass live pyright_base.txt (53 errors) vs pyright_scoped_target.txt (0 errors)
strands_crud.search_orders and best_practices.search_orders return correct results with and without a status filter, an unknown status, and a limit ✅ pass live drive_output.txt
strands_crud.get_order_status finds an existing order and returns an error for a missing one, using the typed scan condition ✅ pass live drive_output.txt
update_customer on an unknown customer returns an error, and smolagents_numbers.get_time_off_balance sums days correctly with the None-safe code ✅ pass live drive_output.txt
Employee.email exists on smolagents_encrypted.Employee (the missing-attribute fix) ✅ pass live drive_output.txt lists the model attributes including email
Evidence: pyright on target, scoped to the changed examples
0 errors, 0 warnings, 0 informations
Evidence: pyright on base commit
/private/tmp/basewt/docs/examples/async/fastapi_example.py
  /private/tmp/basewt/docs/examples/async/fastapi_example.py:3:6 - error: Import "fastapi" could not be resolved (reportMissingImports)
53 errors, 0 warnings, 0 informations
Evidence: Runtime driver output (in-memory backend)
all [{'order_id': 'O1', 'status': 'shipped'}, {'order_id': 'O2', 'status': 'pending'}, {'order_id': 'O3', 'status': 'shipped'}]
shipped [{'order_id': 'O1', 'status': 'shipped'}, {'order_id': 'O3', 'status': 'shipped'}]
{'order_id': 'O2', 'status': 'pending', 'total': 5}
bp all [{'order_id': 'O1', 'status': 'shipped', 'total': 5}, {'order_id': 'O2', 'status': 'pending', 'total': 5}, {'order_id': 'O3', 'status': 'shipped', 'total': 5}]
bp pending [{'order_id': 'O2', 'status': 'pending', 'total': 5}]
{'approved_days_used': 6, 'pending_days': 3, 'remaining': 14}
['department', 'email', 'name', 'pk', 'sk', 'ssn']
ALL OK
Evidence: Runtime driver script
import importlib.util, sys
from pydynox.testing import MemoryBackend

def load(name):
    spec = importlib.util.spec_from_file_location(name, f"docs/examples/agentic/{name}.py")
    m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m); return m

with MemoryBackend():
    sc = load("strands_crud")
    sc.create_customer("1", "Ann", "a@x.com")
    sc.update_customer("1", email="b@x.com")
    for oid, st in [("O1","shipped"),("O2","pending"),("O3","shipped")]:
        sc.Order(pk="CUSTOMER#1", sk=f"ORDER#{oid}", order_id=oid, status=st, total=5).sync_save()
    sc.Order(pk="CUSTOMER#2", sk="ORDER#O9", order_id="O9", status="shipped", total=1).sync_save()
    all_ = sc.search_orders("1"); print("all", all_)
    assert {o["order_id"] for o in all_} == {"O1","O2","O3"}
    shp = sc.search_orders("1", status="shipped"); print("shipped", shp)
    assert {o["order_id"] for o in shp} == {"O1","O3"}
    assert sc.search_orders("1", status="nope") == []
    assert sc.search_orders("1", limit=2) and len(sc.search_orders("1", limit=2)) <= 2
    s = sc.get_order_status("O2"); print(s); assert s["status"] == "pending"
    assert sc.get_order_status("ZZ") == {"error": "Order not found"}
    assert sc.update_customer("nobody") == {"error": "Customer not found"}

    bp = load("best_practices")
    for oid, st in [("O1","shipped"),("O2","pending")]:
        bp.Order(pk="CUSTOMER#1", sk=f"ORDER#{oid}", order_id=oid, status=st, total=5).sync_save()
    r = bp.search_orders("1"); print("bp all", r); assert {o["order_id"] for o in r}=={"O1","O2","O3"}
    r = bp.search_orders("1", status="pending"); print("bp pending", r); assert [o["order_id"] for o in r]==["O2"]

    sn = load("smolagents_numbers")
    for d,(days,st) in enumerate([(2,"approved"),(3,"pending"),(4,"approved")]):
        sn.TimeOff(pk="EMP#1", sk=f"REQUEST#{d}", request_type="v", days=days, status=st).sync_save()
    b = sn.get_time_off_balance("1"); print(b)
    assert b["approved_days_used"]==6, b

    se = load("smolagents_encrypted"); print(sorted(se.Employee._attributes if hasattr(se.Employee,'_attributes') else []))
print("ALL OK")

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 5 of 5 scenarios driven live against the product
Scenario Result Live Evidence
Pyright on agentic examples, fastapi_example.py and type_checking: 53 errors at base drop to 0 at target ✅ pass live pyright_base.txt (53 errors) vs pyright_scoped_target.txt (0 errors)
strands_crud.search_orders and best_practices.search_orders return correct results with and without a status filter, an unknown status, and a limit ✅ pass live drive_output.txt
strands_crud.get_order_status finds an existing order and returns an error for a missing one, using the typed scan condition ✅ pass live drive_output.txt
update_customer on an unknown customer returns an error, and smolagents_numbers.get_time_off_balance sums days correctly with the None-safe code ✅ pass live drive_output.txt
Employee.email exists on smolagents_encrypted.Employee (the missing-attribute fix) ✅ pass live drive_output.txt lists the model attributes including email
  • uv run --with maturin maturin develop
  • uvx pyright --pythonpath .venv/bin/python docs/examples/agentic docs/examples/async/fastapi_example.py docs/examples/type_checking (target: 0 errors)
  • same pyright command on base 7f133f4 archive (53 errors)
  • uvx pyright over docs/examples/async (4 unrelated errors in other files)
  • Runtime driver script executing strands_crud, best_practices, smolagents_numbers and smolagents_encrypted under MemoryBackend
⚠️ **Document** - 1 info
  • ℹ️ docs/examples/async/model_async.py:24 - Pyright still reports 4 errors in other docs/examples/async files (model_async.py Optional access, and .all on AsyncQueryResult in query_async.py and real_world.py). They are outside this change's scope (agentic examples and the fastapi import). Fixing them would be a follow-up under issue 325. docs/guides/type-checking.md is being rewritten in PR 567.
✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Scope reportMissingImports=false to the agentic examples and the FastAPI
example through pyright execution environments, since smolagents,
pydantic_ai, strands and fastapi are not dev dependencies.

Add None checks for T | None attribute values, narrow S3Attribute values
to S3Value before reading the key, use sync_ table helpers in sync code
and await the async ones, and replace raw expression strings in query
and scan calls with partition_key and Condition objects. Also add the
missing Employee.email attribute and stop iterating a query result twice
in smolagents_numbers.py.
@codecov

codecov Bot commented Oct 31, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@vicolby

vicolby commented Oct 31, 2026

Copy link
Copy Markdown
Contributor Author

@leandrodamascena ready for review, duplications sonar fails on are intentional because examples should stand on its own docs

@leandrodamascena

Copy link
Copy Markdown
Member

Thanks @vicolby! I pushed a fix for the Bedrock setup and the docstrings smolagents needs. All 11 examples now import with the frameworks installed, Pyright is clean, and the LocalStack checks passed. I agree about the duplication; these examples should stand on their own. Looks good to me 🙂

@sonarqubecloud

sonarqubecloud Bot commented Nov 1, 2026

Copy link
Copy Markdown

@leandrodamascena
leandrodamascena merged commit 50b4bf8 into ferrumio:main Nov 1, 2026
10 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants