feat: add choices to strings to enable literal types

[MaximSrour]

Summary

Enables ormar.String to preserve string literal typing when choices are provided, while keeping the underlying database column as sqlalchemy.String.

Closes #1579.

Changes

• update ormar.String to project a typing.Literal[...] pydantic type when string choices are provided
• preserve nullable behavior for String(..., choices=..., nullable=True) by wrapping the projected type in Optional[...]
• keep normal String behavior unchanged when choices are not provided
• add/adjust tests for:
  • runtime validation of String(..., choices=...)
  • nullable string choices
  • generated JSON schema for string choices fields
• update field documentation to describe String and String(..., choices=...) in a single section

Testing

Built and ran targetted tests for the new changes, and ran tests against the entire suite. All passing.

Installed a local version of ORMAR into a personal repository that uses it, and tested against existing type errors.

Screenshots

Error before:

Using the new literal inference:

[codspeed-hq]

Merging this PR will degrade performance by 32.91%

⚡ 1 improved benchmark
❌ 2 regressed benchmarks
✅ 81 untouched benchmarks

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	WallTime	test_making_and_inserting_models_in_bulk[10]	8.5 ms	9.9 ms	-13.8%
❌	WallTime	test_creating_individually_with_related_models[10]	56.4 ms	84 ms	-32.91%
⚡	WallTime	test_updating_models_individually[10]	73 ms	63.2 ms	+15.45%

---

_{Comparing MaximSrour:add-choices-to-strings-to-enable-literal-types (aa11349) with master (8e144d0)}

[collerek]

Any particural reason why you dont want to use EnumField here?

[MaximSrour]

Any particural reason why you dont want to use EnumField here?

I wrote about it a bit in the linked issue, but it mostly comes down to flexibility - with an enum, I'd need to push a migration to update the column type (which can take a while when there are a lot of records), after which I'll be able to use the new value. With a string column instead, the code can immediately start using the new values.