PYTHON-6023 Consolidate all non-IO code in AsyncCursor/Cursor into _A…

[sleepyStick]

…gnosticCursor

PYTHON-6023

Changes in this PR

batch_size, _has_next, _post_batch_resume_token, _end_session, _unpack_response, _get_namespace are moved out of AsyncCommandCursor/CommandCursor and into a new shared _AgnosticCommandCursorBase class.

Test Plan

existing tests should continue to pass

Checklist

Checklist for Author

• Did you update the changelog (if necessary)?
• Is there test coverage?
• Is any followup work tracked in a JIRA ticket? If so, add link(s).

Checklist for Reviewer

• Does the title of the PR reference a JIRA Ticket?
• Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
• Is all relevant documentation (README or docstring) updated?

[Copilot]

🟡 Changes recommended

The refactor widens the sync/async command cursor constructor type hints (and related attribute typing) in a way that is misleading for each API and should be narrowed before merge.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR refactors the command cursor implementations by extracting shared, non-I/O logic from AsyncCommandCursor/CommandCursor into a new shared base in pymongo/cursor_shared.py, reducing duplication between sync and async variants.

Changes:

• Introduces _AgnosticCommandCursorBase in pymongo/cursor_shared.py and moves shared cursor behaviors (__init__, batch_size, token helpers, etc.) into it.
• Updates both pymongo/asynchronous/command_cursor.py and pymongo/synchronous/command_cursor.py to inherit from the new agnostic base.
• Adds _AgnosticCollection typing alias to support shared typing across sync/async collection types.

File summaries

File	Description
pymongo/typings.py	Adds _AgnosticCollection alias for shared sync/async typing.
pymongo/cursor_shared.py	Adds _AgnosticCommandCursorBase and migrates shared command-cursor logic into it.
pymongo/asynchronous/command_cursor.py	Switches AsyncCommandCursor to inherit from _AgnosticCommandCursorBase.
pymongo/synchronous/command_cursor.py	Switches CommandCursor to inherit from _AgnosticCommandCursorBase.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sleepyStick]

maybe i'm misunderstanding the comment, but I if the non-io code is moved into _AgnosticCommandCursorBase, there is no sync vs async so i don't think this matters?

[aclark4life]

the type-checking value is lost for callers of AsyncCommandCursor / CommandCursor who get  Any / union-typed self._collection instead of the collection doc type. So maybe we do something like:

# pymongo/asynchronous/command_cursor.py
class AsyncCommandCursor(
    _AgnosticCommandCursorBase[_DocumentType], _AsyncCursorBase[_DocumentType]
):
    _collection: AsyncCollection[_DocumentType]
    ...

# pymongo/synchronous/command_cursor.py
class CommandCursor(_AgnosticCommandCursorBase[_DocumentType], _CursorBase[_DocumentType]):
    _collection: Collection[_DocumentType]
    ...

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pymongo/cursor_shared.py	88.23%	3 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!

[aclark4life]

the type-checking value is lost for callers of AsyncCommandCursor / CommandCursor who get  Any / union-typed self._collection instead of the collection doc type. So maybe we do something like:

# pymongo/asynchronous/command_cursor.py
class AsyncCommandCursor(
    _AgnosticCommandCursorBase[_DocumentType], _AsyncCursorBase[_DocumentType]
):
    _collection: AsyncCollection[_DocumentType]
    ...

# pymongo/synchronous/command_cursor.py
class CommandCursor(_AgnosticCommandCursorBase[_DocumentType], _CursorBase[_DocumentType]):
    _collection: Collection[_DocumentType]
    ...