Clarify Cursor and CommandCursor docstrings to indicate where they are used

XMLWordPrintableJSON

    • None
    • Python Drivers
    • None
    • None
    • None
    • None
    • None
    • None

      Context

      The module docstring for cursor.py reads "Cursor class to iterate over Mongo query results" and the class AsyncCursor has no class-level docstring at all reads "Create a new cursor." Neither makes it clear that this cursor is specifically returned by collection.find() and is distinct from CommandCursor/AsyncCommandCursor, which is returned by commands like aggregate, listIndexes, and listCollections.

      A reader encountering AsyncCursor for the first time has no way to know from the docstring alone why two cursor classes exist or when they would encounter each one.

      This is a lower-cost alternative to PYTHON-5899 (renaming to FindCursor) that improves discoverability without a public API change.

      Definition of done

      • Add Update class-level docstring to AsyncCursor / Cursor that explains it is returned by collection.find() and distinguishes it from CommandCursor
      • Update the module docstring in cursor.py to reflect the same
      • Update _RawBatchCursor / _RawBatchCursor docstrings similarly if applicable

      Pitfalls

      None — purely additive documentation change.

            Assignee:
            Noah Stapp
            Reporter:
            Alex Clark
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated: