Challenging to tell when to use `models` vs not. Can we unify the objects into a single init?

[flaviuvadan]

It is currently challenging to know when to import the models module and use objects from that with Hera. Some users might expect that import hera.workflows.* gives them everything they need. However, imagine using ttl_strategy, which is easily available on a container but the GC strategy import must come from models, which is not as obvious. We should consider unifying the imports somehow

[elliotgunton]

I had an idea - but I'd be wary of doing something not obviously backwards-compatible or that blocks us in future - which would be to import all the models into hera/workflows/__init__.py (to allow import hera.workflows.* as you mentioned (although that import statement itself seems like a bad idea...)), or make lightweight wrappers around the models. We might be able to then expand on what the Hera classes offer on top of the models.

Would it make sense to make a docs-only change which addresses https://github.com/argoproj-labs/hera/issues/774 first?

[flaviuvadan]

make lightweight wrappers around the models

Could we automatically do this?

[flaviuvadan]

make lightweight wrappers around the models

Could we automatically do this?

@elliotgunton @ljyanesm I imagine the algorithm is something like:

• import * from hera.workflows.models
• A = set of objects from hera.workflows.models
• import * from hera.workflows
• B = set of objects from hera.workflows
• C = B \ A (set difference, keep A over B)
• for each c in C
  • name = camel case to snake case (c.name)
  • make a file called name inside hera.workflows
  • write to the file
  • from hera.workflows.models import c as ModelC
  • class c(modelC): pass
  • __all__ = ['c']
• make global init from hera.workflows only ===> now users can write from hera.workflows import * and they get everything

What do you think?

[hermesribeiro]

This can become less challenging if all models appear in the docs. A user can search for say, Affinity, and be redirected to the models page and infer the import path. Currently only hera.workflows.models.io.argoproj.workflow.v1alpha1 is included and others should be included as well. Maybe adding each module file in a separate URL like https://hera.readthedocs.io/en/latest/api/workflows/models/io/argoproj/workflow/v1alpha1 or something along these lines instead of adding them all into the models page can help making the section lighter.

However, other than searching elsewhere, there is absolutely no way to know semantically, syntactically or structurally which Argo yaml objects are hera workflows classes and which are only pydantic models beforehand, and even this assumes that the user knows that there is a difference at all. So a :heavy_plus_sign: 1 to unifying.

Should I open a separate issue for the models doc? I can open a PR too in the coming days too.

[flaviuvadan]

@hermesribeiro an update to the docs sounds really great as a starting point until we figure out exactly how to approach this!