[vistart]

Description

Adds the shared sync/async contract for find_one_or_create on a natural key.

• Covers creation from lookup plus defaults, returning an existing row without applying defaults, and lookup winning over defaults on the created row.
• Asserts empty lookups, unknown fields, None lookup values, expression values and database-generated primary keys are rejected.
• Covers composite primary keys, where the natural key may be a non-primary-key field.
• Covers the concurrent-insert path: when the insert loses a conflict that the lookup explains, the existing winner is returned with created=False; an unexplained constraint failure is re-raised.
• Sync and async test classes share method names and fixtures.
• Companion core PR: rhosocial/python-activerecord #134.

Adds: N/A (no tracking issue).

Type of change

• feat: A new feature
• docs: Documentation only changes (if related to the new feature)
• perf: A code change that improves performance (if part of the feature)
• test: Adding missing tests or correcting existing tests (for the new feature)
• chore: Changes to the build process or auxiliary tools and libraries suchs as documentation generation (if related to the new feature)
• ci: Changes to our CI configuration files and scripts (if related to the new feature)
• build: Changes that affect the build system or external dependencies (if related to the new feature)
• revert: Reverts a previous commit

Breaking Change

• Yes
• No

(If Yes, please describe the impact and migration path below):

N/A

Applicable rhosocial-activerecord Version Range:

rhosocial-activerecord>=1.0.0.dev30,<2.0.0

Related Repositories/Packages

• Core: rhosocial/python-activerecord branch feature/find-one-or-create adds the method.
• Backend repositories will add one-line wrapper tests importing these new testsuite modules after the core/testsuite batch merges.

Testing

• I have added new tests to cover my changes.
• I have updated existing tests to reflect my changes.
• All existing tests pass.
• This change has been tested on [specify backend/DB versions].

Test Plan:

pytest src/rhosocial/activerecord/testsuite/feature/query/basic/test_find_one_or_create.py
pytest src/rhosocial/activerecord/testsuite/feature/query/basic/test_find_one_or_create_async.py

The companion core PR installs this testsuite branch and runs the full core matrix.

Checklist

• My code follows the project's code style guidelines.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation (Docstrings, README.md, etc.).
• My changes generate no new warnings.
• I have added a Changelog fragment (changelog.d/<issue_number>.<type>.md).
• I have verified that my changes do not introduce SQL injection vulnerabilities.
• I have checked for potential performance regressions.

Additional Notes

This repository has no self-test workflow. The shared tests are validated by the companion core CI run. The changelog fragment is intentionally added after the PR number and CI result are known.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud