putting current class as return type annotation

So now after a while I can say that decision I took was using -> 'Graph' instead of -> Graph. It does not make my IDE (PyCharm) able to recognize a type this way but it just works well enough for documentation purposes.

Another possible solution I could use was changing annotation at runtime but that doesn't solve the problem with documentation - you won't want to look for type declarations somewhere in the middle of sources...

The problem has roots in recognizing class object before the class was actually defined. That is simply impossible to do in python.

In python-3.7 this issue has been resolved by not evaluating the annotations at function definition time. Instead, they are preserved in __annotations__ in string form. This is called Postponed Evaluation of Annotations, introduced in PEP 563.

Also note:

Deprecation policy

Starting with Python 3.7, a __future__ import is required to use the described functionality. No warnings are raised.

In Python 3.8 a PendingDeprecationWarning is raised by the compiler in the presence of type annotations in modules without the __future__ import.

Starting with Python 3.9 the warning becomes a DeprecationWarning.

In Python 4.0 this will become the default behavior. Use of annotations incompatible with this PEP is no longer supported.

Here is an example:

In [7]: from __future__ import annotations

In [8]: class C:
   ...:     def func(cls, arg:str) -> C:
   ...:         pass
   ...:     

In [9]: c = C()