Skip to content

docs: clarify get/first/last MultipleMatches semantics#1678

Merged
collerek merged 3 commits into
masterfrom
docs/clarify-get-first-multiple-matches
May 14, 2026
Merged

docs: clarify get/first/last MultipleMatches semantics#1678
collerek merged 3 commits into
masterfrom
docs/clarify-get-first-multiple-matches

Conversation

@collerek

Copy link
Copy Markdown
Collaborator

Summary

Fixes the internally inconsistent docstrings flagged in #967.

  • first() / last() (and their _or_none variants) always run with LIMIT 1 via _fetch_single, so MultipleMatches can never be raised — the docstrings claimed otherwise.
  • get() enforces the single-match contract only when criteria are set (via filter/exclude or args/kwargs). With no criteria it falls back to returning the last row by pk (LIMIT 1) and cannot raise MultipleMatches either. The old wording ("first row meeting the criteria … MultipleMatches if more than 1 row") conflated these two modes.

Docs-only change: updated docstrings in ormar/queryset/queryset.py and ormar/relations/querysetproxy.py, plus the user-facing docs/queries/read.md sections for get / first / last.

Closes #967

Test plan

  • make pre-commit
  • make coverage (100%, 653 passed)

first/last (and their _or_none variants) always run with LIMIT 1 and
never raise MultipleMatches — the docstrings claimed otherwise. get()
only enforces the single-match contract when criteria are set; the
no-criteria fallback returns the last row by pk and cannot raise
MultipleMatches either.

Updates the queryset and querysetproxy docstrings plus docs/queries/read.md
to spell out this distinction.

Refs #967
@codspeed-hq

codspeed-hq Bot commented May 13, 2026

Copy link
Copy Markdown

Merging this PR will not alter performance

⚡ 3 improved benchmarks
❌ 1 (👁 1) regressed benchmark
✅ 94 untouched benchmarks

Performance Changes

Mode Benchmark BASE HEAD Efficiency
WallTime test_get_or_create_when_create[40] 483.4 ms 417.2 ms +15.89%
WallTime test_update_or_create_when_create[10] 83.7 ms 75.2 ms +11.26%
👁 WallTime test_saving_models_individually[20] 133.3 ms 160.6 ms -16.98%
WallTime test_updating_models_individually[40] 325.8 ms 285.5 ms +14.14%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.


Comparing docs/clarify-get-first-multiple-matches (fc1ddb1) with master (260c6a7)1

Open in CodSpeed

Footnotes

  1. No successful run was found on master (722595f) during the generation of this report, so 260c6a7 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report.

@collerek
collerek merged commit a4666c6 into master May 14, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant