Python SDK examples README overstates async.py coverage

I did a quick review and confirmed the documentation mismatch.

The current sdk/python/examples/README.md states:

Each example folder contains runnable versions:
- sync.py
- async.py

and later instructs users to run:

python examples/<example-folder>/sync.py
python examples/<example-folder>/async.py

However, sdk/python/examples/09_async_parity/ currently contains:

09_async_parity/
└── sync.py

with no corresponding async.py.

As a result, the README currently establishes a repository-wide contract that is not satisfied by at least one example directory.

---

Root Cause

The issue appears to be documentation drift.

The README assumes a uniform example structure:

<example>/
├── sync.py
└── async.py

while 09_async_parity follows:

09_async_parity/
└── sync.py

Therefore, the documentation and repository contents have diverged.

---

Possible Fixes

Option A — Update Documentation (Recommended)

Adjust the README to describe the actual repository structure.

Suggested patch:

- Each example folder contains runnable versions:
-   * sync.py (public sync surface: Codex)
-   * async.py (public async surface: AsyncCodex)

+ Most example folders contain runnable versions:
+   * sync.py (public sync surface: Codex)
+   * async.py (public async surface: AsyncCodex)
+
+ Exceptions:
+   * 09_async_parity currently provides only sync.py.

Update execution instructions as well:

From sdk/python:

     python examples/<example-folder>/sync.py
-    python examples/<example-folder>/async.py
+    python examples/<example-folder>/async.py  # when present

or

+ Note: 09_async_parity currently exposes only sync.py.

Option B — Add async.py to 09_async_parity

If the intention is that every example directory should provide both interfaces, then an async.py implementation could be added.

Example skeleton:

from openai import AsyncOpenAI

client = AsyncOpenAI()

async def main():
    # async parity example logic
    ...

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

This preserves the README contract but introduces additional maintenance burden if the example is intentionally sync-only.

---

Best Fit

I recommend Option A.

Reasons:

1. The issue is documentation accuracy rather than missing functionality.
2. The smallest change is usually the safest change.
3. The repository already functions correctly.
4. Users only encounter a problem because the README promises something that does not exist.

---

Regression Prevention

To prevent future README/example mismatches, a lightweight validation test could be added.

Example:

from pathlib import Path

SYNC_ONLY_EXAMPLES = {
    "09_async_parity",
}

def test_example_entrypoints_match_repository_conventions():
    root = Path("sdk/python/examples")

    for example_dir in root.iterdir():
        if not example_dir.is_dir():
            continue

        sync_file = example_dir / "sync.py"
        async_file = example_dir / "async.py"

        assert sync_file.exists(), (
            f"{example_dir.name} is missing sync.py"
        )

        if example_dir.name not in SYNC_ONLY_EXAMPLES:
            assert async_file.exists(), (
                f"{example_dir.name} is missing async.py"
            )

Alternatively, if the project wants stronger guarantees, the README itself could become the source of truth and be validated against the filesystem during CI.

---
I'd be happy to prepare a PR implementing the documentation update and adding a regression test if maintainers agree with the proposed direction.

By Anup Das
anupddas8@gmail.com

I prepared a small targeted implementation for this on my fork, since external PRs to this repo appear to be invitation-gated.

Compare: https://github.com/openai/codex/compare/main...SylvainWinning:codex/python-sdk-examples-docs?expand=1
Branch: https://github.com/SylvainWinning/codex/tree/codex/python-sdk-examples-docs
Commit: 9f672b142f09aeb2e751ebdbd1fad2ebd459c26f

What it changes:

• Updates sdk/python/examples/README.md so it says most example folders have both sync.py and async.py.
• Documents that 09_async_parity/ currently provides only sync.py.
• Marks the generic async.py run command as # when present.
• Adds a regression test that checks sync-only example folders are explicitly documented.

Validation run locally:

• uv run --frozen --project sdk/python --only-group test pytest sdk/python/tests/test_artifact_workflow_and_binaries.py -k 'examples_readme' -> 2 passed
• uv run --frozen --project sdk/python --only-group format ruff format --check sdk/python/tests/test_artifact_workflow_and_binaries.py -> passed
• uv run --frozen --project sdk/python --only-group format ruff check sdk/python/tests/test_artifact_workflow_and_binaries.py -> passed
• uv run --frozen --project sdk/python pytest sdk/python/tests/test_artifact_workflow_and_binaries.py -> 36 passed
• git diff --check -> passed

I did not open a duplicate issue; this comment is intended to keep the implementation attached to this existing report.