Simplify python generation, gather requirements, and improve documentation

[cmungall]

Currently the python generation has lots of magic in it that should be better documented

• It creates very inclusive types with complex Unions, see Add option to pythongen to use less inclusive types #464.
• It creates classes for types, which can cause an issue with some frameworks
  • py2neo Bug/UX: extended_str incompatibility w/ Neo4j linkml-runtime#64
• It has very flexible post-init methods, but these can conflict with frameworks like
  • sqlalchemy (TODO: make an issue)
  • fastapi generated dataclasses not compatible with fastapi/pydantic dataclass bridge #486
• all objects inherit from JsonObj from jsonasobj2, which adds a layer of complexity
  • Strange behavior for empty lists hsolbrig/jsonasobj2#3
  • __repr__ not working for lists hsolbrig/jsonasobj2#2
• treatment of mixins
  • not factored into post-init Mixins aren't factored into post-init for pythongen classes #355
  • mixin slots are properly rolled down, which is good
  • however, mixins can't be used in isinstance checking - only primary hierarchy used

We are currently working on pydantic support

• Add pydantic support #172.

It's not yet clear whether we should converge on "one true way" of doing python OMs or continue to have both pythongen and pydanticgen

Here is a start on a list of requirements we can use to guide us in long term decision making

• expressive validation
  • ranges
  • min value, max value
  • regex
  • boolean combinations
• delayed validation
  • some validation operations may be expensive, so we may want to allow the ability to create objects pbypassing some expensive checks
• validation
  • simple instantiation from dicts/json
  • simple serialization to dicts/json
• automated conversion on instantiation
  • instantiation from nested dicts (must-have)
  • smart conversion
    • e.g. if bars is multivalued, then bars=Bar(...) converts to a list. IMO this is less necessary and can be confusing
• Union ranges where the schema uses exactly_one_of
• Any support
• inlining support
• flexibility on converting types
  • one option is to use aliases rather than classes
  • e.g. LINKML_STRING = str
• multiple inheritance support
• Compatibility with other frameworks
  • pydantic (either direct or via bridge)
  • fastapi
  • flask
  • sqlalchemy
  • pyneo

[nlharris]

This ticket has a lot of things in it, and it's not clear what's not done and what still needs to be done.