Generate Python type stub - allowing more code completion in IDE by bact · Pull Request #74 · JPEWdev/shacl2code

bact · 2026-02-22T22:46:08Z

This PR improves type annotations and adds Python type stub (.pyi) generation. This will allow more code completion in IDE.

Before this PR, only few class members are shown in autocompletion list:

With this PR, more class members, including ones from its superclasses, are shown:

(example from spdx-python-model -- need spdx/spdx-python-model#18 to copy the type stub to bindings path)

--

Improve type annotations in the generated Python binding:

Add Generic[T_PropValue] to Property and ListProxy classes to allow them to define specific types, reduce the use of Any.
Add type annotations to the generated class definitions (use DATATYPE_PYTHON_ALIASES mapping)
Replace native set with typing.Set to maintain Python 3.8 compatibility

Fix lint warnings in the generated code:

Remove unnecessary global/nonlocal where the variable is not being modified locally, to fix F824 Flake8 warning in the generated Python code.
Remove unused obj_data variable in SHACLExtensibleObject.__setitem__ to fix F841 warning in Ruff
Fix black formatting

--

They generated type stub will look like below.

Generated "link-class" from the test model:

# A class to test links
@register("http://example.org/link-class", abstract=False)
class http_example_org_link_class(SHACLObject):
    NODE_KIND: NodeKind = NodeKind.BlankNodeOrIRI
    IS_DEPRECATED: bool = False
    NAMED_INDIVIDUALS: Dict[str, str] = {}

The stub for that class:

class http_example_org_link_class(SHACLObject):
    NODE_KIND: NodeKind = ...
    ID_ALIAS: Optional[str] = ...
    IS_DEPRECATED: bool = ...
    NAMED_INDIVIDUALS: Dict[str, str] = ...
    derived_prop: Optional[Union[str, "http_example_org_link_derived_class"]]
    extensible: Optional[Union[str, "http_example_org_extensible_class"]]
    link_list_prop: ListProxy[Union[str, "http_example_org_link_class"]]
    link_prop: Optional[Union[str, "http_example_org_link_class"]]
    link_prop_no_class: Optional[Union[str, "http_example_org_link_class"]]
    tag: Optional[str]

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Fix ruff, flake8, and black warning in the generated Python code (output.py in test) Fix Flake8 warning on "F824: name is never assigned in scope" by removing unnecessary global/nonlocal declarations. Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

github-actions · 2026-02-22T22:55:57Z

Coverage report

Click to see where and how coverage changed

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

_{This report was generated by python-coverage-comment-action}

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

With improved type hints some ignores are no longer needed Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

With the improved type hints and cast, the test now passed pyrefly check Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

To allow Jupyter/IPython notebook to see types, we need to keep annotations out of the block Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

bact · 2026-02-23T12:59:27Z

For code autocompletion, may need to implements two things:

stub (.pyi), for IDE to read
__dir___ overriding to export __annotations__ list, for interactive shell like Jupyter to read

Can't do default assignment to class variables because it will interfere with the existing __setattr__ and __getattr__ overrides.

JPEWdev · 2026-02-23T19:20:34Z

src/shacl2code/lang/templates/python.j2

        return (iri for iri, _ in self.context)

+    def encode(self, encoder: Encoder, value: T_PropValue, state: EncodeState) -> None:
+        encoder.write_iri(str(value))


This class (IRIProp) is intended to be abstract, which is why it didn't implement these; are they needed for typechecking for some reason?

JPEWdev · 2026-02-23T19:23:28Z

src/shacl2code/lang/templates/python.j2

+    def __eq__(self, other: Any) -> bool:
        if isinstance(other, ListProxy):
-            return self.__data == other.__data
+            return bool(self.__data == other.__data)


The bool() suprises me; I would have though a comparison operator would implicitly be a bool

I though so as well. I'm actually trying to get rid of this because it's quite ugly....

Looks like mypy is being very defensive, as == can be override with __eq__ function and that new function can return anything.

Btw, now successfully removed few # type: ignore and one remaining pytest xfail. The code is sort of working now, but there are few places that look very clumsy. I will trying to clean that up.

Have update the code to try to convert Collection to a list, and None to an empty list, and compare. -- Not sure if it's a good idea.

What I'm trying to see here is if we provide enough isinstance checks, will it give enough information for the type checker to let us go.

I will tinkering around this for a bit.

Maybe not a good idea to convert Collection to list, as list suggests order.
Will revert that.

JPEWdev · 2026-02-23T19:23:39Z

src/shacl2code/lang/templates/python.j2

+            return bool(self.__data == other.__data)

-        return self.__data == other
+        return bool(self.__data == other)


JPEWdev · 2026-02-23T19:24:28Z

src/shacl2code/lang/templates/python.j2

            v = self.prop.decode(val_d, state)
-            self.prop.validate(v)
-            data.append(v)
+            if v is not None:


hmm, is this because decode() returns Optional[...]?

JPEWdev · 2026-02-23T19:25:14Z

src/shacl2code/lang/templates/python.j2

-                v = prop.decode(prop_d, state)
-                prop.validate(v)
-                self.__dict__["_obj_data"][iri] = v
+                if prop_d is not None:


This check seems unnecessary

JPEWdev · 2026-02-23T19:25:35Z

src/shacl2code/lang/templates/python.j2

                return (obj, "", "", "")
            return (
-                obj._id or "",
+                getattr(obj, "_id", None) or "",


Why this change?

JPEWdev · 2026-02-23T19:26:17Z

src/shacl2code/lang/templates/python.j2

        # This covers custom extensions
-        reg_type(obj.TYPE, obj.COMPACT_TYPE, obj, True)
+        reg_type(
+            str(obj.TYPE),


Why this cast?

JPEWdev · 2026-02-23T19:26:33Z

src/shacl2code/lang/templates/python.j2

-        reg_type(obj.TYPE, obj.COMPACT_TYPE, obj, True)
+        reg_type(
+            str(obj.TYPE),
+            str(obj.COMPACT_TYPE) if obj.COMPACT_TYPE else None,


This also seems unnecessary

Generate stub (.pyi) for type annotations Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Convert different types to list and compare Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

bact · 2026-02-25T04:43:50Z

This PR is probably getting too big, maybe it's better to break it down.

Fix Python 3.8 compatibility issue (native type)
Add more/fix few type hints
Generate stub

Will wait for #76 to get merged (it will changed structure of how we maintain class properties) and see where to work first.

JPEWdev · 2026-02-25T15:51:14Z

This PR is probably getting too big, maybe it's better to break it down.
1. Fix Python 3.8 compatibility issue (native type)

2. Add more/fix few type hints

3. Generate stub
Will wait for #76 to get merged (it will changed structure of how we maintain class properties) and see where to work first.

Sounds good. #76 is the last big change I have planned; there will be a few smaller ones after but they shouldn't interfere too much

bact added 4 commits February 23, 2026 04:19

Add T_PropValue typevar to allow scoped type hints

5c05c36

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Merge branch 'JPEWdev:main' into typevar-propvalue

dcef5fa

Type hint _decode_properties()

3e2dd54

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

bact added the enhancement New feature or request label Feb 22, 2026

bact marked this pull request as draft February 22, 2026 22:46

bact added 6 commits February 23, 2026 06:21

Fix formatting

84dbfe4

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Fix mypy warnings and remove unused ignores

862a662

With improved type hints some ignores are no longer needed Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Add TYPE_CHECKING block

ae6d7ba

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Fix formatting

35518e0

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Remove xfail marker from test

7b532a4

With the improved type hints and cast, the test now passed pyrefly check Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Remove TYPE_CHECKING block

817f333

To allow Jupyter/IPython notebook to see types, we need to keep annotations out of the block Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Merge branch 'JPEWdev:main' into typevar-propvalue

06a1c4e

JPEWdev reviewed Feb 23, 2026

View reviewed changes

Split class member annotations to stub

b2bf9ff

Generate stub (.pyi) for type annotations Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

bact changed the title ~~Typing strictness for Property and ListProxy, using Generic TypeVar~~ Generate Python type stub - allowing code completion in IDE Feb 23, 2026

bact changed the title ~~Generate Python type stub - allowing code completion in IDE~~ Generate Python type stub - allowing more code completion in IDE Feb 23, 2026

Try to compare ListProxy

188b0ab

Convert different types to list and compare Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

bact mentioned this pull request Feb 24, 2026

Add py.typed type hint marker spdx/spdx-python-model#14

Closed

bact added 4 commits February 26, 2026 01:07

Merge branch 'main' into typevar-propvalue

155478d

Merge branch 'main' into typevar-propvalue

171ccc1

Merge branch 'main' into typevar-propvalue

a7ce248

Merge branch 'main' into typevar-propvalue

354d077

Conversation

bact commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Uh oh!

bact commented Feb 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bact Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bact commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JPEWdev commented Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bact commented Feb 22, 2026 •

edited

Loading

github-actions bot commented Feb 22, 2026 •

edited

Loading

bact Feb 24, 2026 •

edited

Loading

bact commented Feb 25, 2026 •

edited

Loading