python: Implement version-agnostic Protocol types

[bact]

This PR adds src/shacl2code/lang/templates/python/protocols.py.j2 template to generates Protocol structure types for classes in the generated bindings.

Given two versions of a model (v1 and v2; v2 is backward compatible with v1) to shacl2code to generate Python bindings (one at a time), it will generate two bindings that look similar but v1.SomeClass and v2.SomeClass are considered distinct. They are not sharing a common parent type.

This makes it difficult for a downstream user who wants to write a function like:

def func(x: SomeClass) -> SomeClass: ...

Because if it defines SomeClass as v1.SomeClass, it will be incompatible with v2.SomeClass (and vice versa).

This PR provides the generation of protocols.SomeClass which is a structural type that accepts any class with the same shape (has similar members), so v1.SomeClass and v2.SomeClass can be both accepted, even they are unrelated.

This function will work across all versions of the model (provided that they are keeping backward compatibility to previous versions -- not removing any members in newer versions):

def func(x: protocols.SomeClass) -> protocols.SomeClass: ...

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
src/shacl2code/lang
python.py
Project Total

This report was generated by python-coverage-comment-action

[bact]

This PR may need update after #124 got merged, as the protocols may need to have the new Ontology class too. (Possible to get that from auto-generation, but still need to add a test for confidence)

[bact]

#124 merged. Need to review this PR (may need few revision). Put to draft.

[JPEWdev]

Why doesn't this need 'main' from cmd (and protocols)?

Also, is it possible to maybe use model.__all__ instead of manually filtering?

[bact]

For first question, it is intentional since cmd and protocols will not be usually used (as a library) and we like to avoid loading anything that is not likely to be used.

For cmd and main, same rational as removing main from spdx-python-model binding generation at spdx/spdx-python-model#51

For protocols, its main use case is for type check and it is better to keep it separate because if we allow them in mix in top-level import * all *Protocol classes will be loaded during runtime (no exactly harmful, but unnecessary waste memory - every model class will have its own *Protocol class counterpart).

Users who want them still able to access them by using fully qualified name.

--

For 2nd one, we can use model.__all__ too but since currently model doesn't have __all__, we have to define it there.

Do it in model.py.j2 is more straightforward, we explicitly say what we like to export. It is also cheaper (do it a generation time). The downside is maintenance, you have to maintain the full list of __all__.

Do it in __init__.py.j2 retrospectively is more expensive but lower maintenance, you inspect actual available symbols, then filter it. You maintain only a small blacklist - which in this case tend to be stable. Since the imports tend to be only few times per process, I chose to do it in init.

Each approach has its own risks though. The static explicit list in model can under-export. The dynamic filter in init can over-export.