Internally inconsistent documentation of `get` and `first` w.r.t. behaviour on multiple resulting rows

[kkom]

Describe the bug

The docstring both mentions that the first row meeting the criteria is returned, and that MultipleMatches exception is raised if more than 1 row is returned.

To Reproduce

Read the following docstrings:

ormar/ormar/queryset/queryset.py

Lines 892 to 897 in 6e6eafa

	async def first(self, *args: Any, **kwargs: Any) -> "T":
	"""
	Gets the first row from the db ordered by primary key column ascending.
	:raises NoMatch: if no rows are returned
	:raises MultipleMatches: if more than 1 row is returned.

ormar/ormar/queryset/queryset.py

Lines 948 to 958 in 6e6eafa

	async def get(self, *args: Any, **kwargs: Any) -> "T": # noqa: CCR001
	"""
	Get's the first row from the db meeting the criteria set by kwargs.
	If no criteria set it will return the last row in db sorted by pk.
	Passing a criteria is actually calling filter(*args, **kwargs) method described
	below.
	:raises NoMatch: if no rows are returned
	:raises MultipleMatches: if more than 1 row is returned.

ormar/ormar/relations/querysetproxy.py

Lines 387 to 401 in 6e6eafa

	async def get(self, *args: Any, **kwargs: Any) -> "T":
	"""
	Get's the first row from the db meeting the criteria set by kwargs.
	If no criteria set it will return the last row in db sorted by pk.
	Passing args and/or kwargs is a shortcut and equals to calling
	`filter(*args, **kwargs).get()`.
	Actual call delegated to QuerySet.
	List of related models is cleared before the call.
	:raises NoMatch: if no rows are returned
	:raises MultipleMatches: if more than 1 row is returned.

Expected behavior

The docstring:

• either says that the first row meeting the criteria is returned (and doesn't have any mention of raising a MultipleMatches exception)
• or it says that the a single row meeting the criteria is returned (and doesn't have any mention of ordering).

Versions (please complete the following information):

ormar: 6e6eafa

[collerek]

Well it behaves differently depending if you pass any filters or not.

When called empty (get() or first()`) it returns last/first row ordered by pk.

If you set a filter it returns one row matching the criteria or raises an Exception if multiple rows match the criteria.

So both of them return at max one record.

So that should probably be clarified in docstrings but both are correct (but not full).

If you could issue a PR for this I would be grateful.