Instead of Literals, use Enums

[mikeweltevrede]

Summary

When I took a look at the repo, I noticed that pyfixest/estimation/literals.py uses typing.Literal for options where I think an Enum (StrEnum for Python 3.11+) would make more sense. I would like to hear your thoughts, I am unsure if there was maybe a specific reason Of course, I can work on implementing this.

Example

For example, instead of:

SolverOptions = Literal["np.linalg.solve", "np.linalg.lstsq"]
option: SolverOptions = "np.linalg.solve"

you would do:

class SolverOptions(Enum):
    NumpyLinAlgSolve = "np.linalg.solve"
    NumpyLinAlgLstSq = "np.linalg.lstsq"

option = SolverOptions.NumpyLinAlgSolve

NB: With StrEnum and using enum.auto, the right side would be numpylinalgsolve which would not work, unfortunately.

Benefits

Note: generated by ChatGPT and checked by myself.

1. Type Safety and Validation

• With Literal, the values are essentially just strings, and while type checking at the static analysis level works, runtime validation is limited.
• Enums encapsulate the values in a dedicated type, enabling runtime validation of membership in the defined set. For instance, you can easily check if a value belongs to the enum:

  if option not in SolverOptions:
      raise ValueError(f"Invalid option: {option}")

  With Literal, you don't have a way to check this dynamically without manually defining the allowed values.

2. Readability and Code Organisation

• With Literals, if the same string value is used in multiple places, code can become harder to maintain and prone to typos.

3. Extensibility

• Adding or modifying options in an Enum is more straightforward and less error-prone than modifying a Literal.

4. Namespace and Attribute Access

• Enums provide a namespace for related values, which helps in avoiding naming conflicts. Attribute access (SolverOptions.NumpyLinAlgSolve) is less error-prone and more IDE-friendly than string literals.
• IDEs and static analysis tools handle enums better than Literals. Renaming or modifying an Enum member is tracked across the codebase, whereas raw strings might not be detected reliably.

5. Functionality

• Enums can have additional behaviour by defining methods. For example:

  class SolverOptions(Enum):
      NumpyLinAlgSolve = "np.linalg.solve"
      NumpyLinAlgLstSq = "np.linalg.lstsq"
  
      def describe(self):
          return f"Solver option: {self.value}"
  
  SolverOptions.NumpyLinAlgSolve.describe()

  This makes enums more than just static definitions—they can encapsulate logic.

[s3alfisc]

Hi @mikeweltevrede! Thanks for the excellent suggestion. I don't think there is a particular reason why we chose Literals over Enums and I would be open to change =) Maybe @leostimpfle can correct me on this though 😄 @janosg & team recently did a rewrite of optimagic and they went with dataclasses instead of Enums - there's some background on their rationale here: link.

[leostimpfle]

I don't think there's a strong reason against enums but I personally think that they will be a bit more cumbersome from a user perspective. Instead of simply func(solver='np.linalg.solve') the user will have to know the specific enum required for a function, call import SolverOptions and then do func(solver=SolverOptions.NumpyLinAlgSolve).

I might be biased from numpy and pandas but I don't think I've seen the use of enums as argument types for user-exposed methods very much? For example, pandas.DataFrame.fillna has a method argument that is specified as a literal:

https://github.com/pandas-dev/pandas/blob/0691c5cf90477d3503834d983f69350f250a6ff7/pandas/_typing.py#L350

[mikeweltevrede]

Thanks for your thoughts both! I do agree that I have also not seen enums as argument types for user-exposed methods very much. Of course, if type hinting is done well, then the user can Ctrl+click on SolverOptions or do SolverOptions. with IntelliSense to see the available options. The former, of course, also works with the current approach!

For me for enums, the main advantage would indeed be more from a maintenance perspective where you can more easily modify an entry throughout the codebase. Rather than having to find all instances of np.linalg.solve and double checking if this is indeed part of the Literal you are refactoring, you can easily use the refactoring tools in your IDE.

All in all, I do not have a strong opinion. I just saw this and it triggered this thought :)

[janosg]

I am all for arguments with good support for autocomplete and protection against typos. But I have heard many times from users that they prefer strings over Enums.

Your situation looks like a classic str | callable situation where users can either select a pre-implemented option via a string (or Enum) or pass in a callable that satisfies a certain interface. Similar situations occur in many places in sklearn (e.g. the scoring argument in cross_validate

If this is the case, there are several solutions that give you the same typo protection and autocomplete behavior as an Enum. The simplest are modules or dataclasses that collect all pre-implemented callables.

No matter which solution you choose, I would also allow the string.

A related SciPy Issue is here; An example of a similar situation in optimagic is here