Clarify Cursor and CommandCursor docstrings to indicate where they are used

XMLWordPrintableJSON

    • None
    • Python Drivers
    • Not Needed
    • Hide

      1. What would you like to communicate to the user about this feature?
      2. Would you like the user to see examples of the syntax and/or executable code and its output?
      3. Which versions of the driver/connector does this apply to?

      Show
      1. What would you like to communicate to the user about this feature? 2. Would you like the user to see examples of the syntax and/or executable code and its output? 3. Which versions of the driver/connector does this apply to?
    • 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:
              Resolved: