feat: add literal_enums setting to produce Literal[...] instead of enum classes.

[emosenkis]

While attempting to generate a client for https://api.railz.ai/swagger/v2, I ran into duplicate enum values. I tried using the fixes from #725 and #1095 but neither was sufficient because while some duplicates result from case insensitivity, others result from characters (e.g. +) that are stripped when generating the Python name for the value. Allowing enums to be implemented as Literals provides a good alternative that should result in more readable code when an API defines enums that really are a collection of possible values not amenable to representation as a Python enum.

This solution works for me and if you're amenable to the idea, I can add tests, etc. to get it ready for merging. Down the line, I can imagine allowing more configuration options, such as using literal enums only for int enums, only for enums with duplicate values, or only for enums that match a regex but I don't know if you're interested in allowing that sort of granular configuration of generated types.

[dbanty]

This looks great, thanks!

Also related is #1076, though that one didn't provide a config option and didn't use the literals in the endpoint code, just added it as an additional generated piece.

I think I like this approach better—where the style is selected and only one or the other is generated, rather than both. I guess we'll need another new snapshot test for this style—probably a brand new OpenAPI document rather than keeping another variant of the massive end_to_end_tests/golden-record around.

I do think the more granular controls could also be good in the future. Someone might like to generate most of their enums as enum classes, but then opt in to Literal for a few that can't map well.

[chrisguillory]

This PR also unblocked our generation of:

 pipx run openapi-python-client generate --url https://fivetran.com/assets-docs/openapi/file_v1.json

which errors with:

ValueError: Duplicate key RE_SYNC in Enum

Thanks!

[emosenkis]

@dbanty I think this should be ready to merge so long as you're happy with how I implemented it. Fixing the various type errors in the generated code uncovered quite a few bugs in my code and a possibility of non-deterministic output due to ruff making different choices depending on the ordering of imports when one of them is unused. I added a parse-time check that the value is in the enum so that it will be equally as strict as regular enums.

[emosenkis]

I merged in main and have pdm check passing for me locally.

[emosenkis]

Ok, now I've actually tested with Python 3.8 and fixed the last few usages typing features that are only available from Python 3.10. Everything should pass this time.

[eli-bl]

I know I'm commenting a bit late, but... I'm trying to understand the decision to make this a whole new class, instead of adding an attribute to EnumProperty. I feel like adding a LiteralEnumProperty class both increases the amount of new logic required in other files to handle the new class— even in cases when the behavior isn't actually different from EnumProperty (for instance in merge_properties.py)— and also makes it a bit harder to see what the significant implementation differences are between those two classes (which I think may be relatively small compared to the amount of duplicated boilerplate code, although I haven't compared them line by line). Was there a particular reason for going this way?

[emosenkis]

@eli-bl I didn't think very hard about this at the time because I wasn't yet thinking about contributing it upstream. If I remember correctly, the main reason I didn't use EnumProperty class is that the values attribute needs to be a dict for EnumProperty and a set for LiteralEnumProperty. It's also true that the two are mutually incompatible so reusing the same class would result in if branches in virtually every template macro and many of the Python functions.

At the end of the day, I've spent about as much time as I can justify on getting this upstreamed. If someone wants to take it in a different direction I won't be offended but I don't have time to make a big change like unifying the two classes. Either way, I would really like for this feature to be accepted in some form!

[emosenkis]

@dbanty Test coverage is now 100% except the StrEnum / str, Enum version-gated definitions.

[dbanty]

Thank you so much for this! I had to update a snapshot and I added a mention to the readme both over in #1142—which is merged! This fixes an issue that's clearly bumped into a lot given the number of attempts at solving it 😅.