Typehints go missing when `|` is used instead of `Union`

[1kastner]

Hello there,

first of all thank you very much for this project which you share with us! I started the module recently and it worked fantastically in many cases! Thanks again for that!

I also saw that in some cases typehints went missing without any warning or error message. One instance you can see at https://conflowgen.readthedocs.io/en/latest/api.html#conflowgen.PortCallManager where in the method add_large_scheduled_vehicle all parameters do not have typehints even though they are provided in the code. In the case of the method has_schedule everything worked out fine again.

Here is the trimmed source code:

class PortCallManager:

    def add_large_scheduled_vehicle(
            self,
            vehicle_type: ModeOfTransport,
            service_name: str,
            vehicle_arrives_at: datetime.date,
            vehicle_arrives_at_time: datetime.time,
            average_vehicle_capacity: int | float,
            average_moved_capacity: int | float,
            next_destinations: Union[List[Tuple[str, float]], None] = None,
            vehicle_arrives_every_k_days: int | None = None
    ) -> None:
        """
        Add the schedule of a ship of any size or a train. The concrete vehicle instances are automatically generated
        when :meth:`.ContainerFlowGenerationManager.generate` is invoked.

        Args:
            vehicle_type: One of
                :class:`ModeOfTransport.deep_sea_vessel`,
                :class:`ModeOfTransport.feeder`,
                :class:`ModeOfTransport.barge`, or
                :class:`ModeOfTransport.train`
            service_name:
                The name of the service, i.e. the shipping line or rail freight line
            vehicle_arrives_at:
                A date the service would arrive at the terminal. This can e.g. point at the week day for weekly
                services. In any case, this is combined with the parameter ``vehicle_arrives_every_k_days`` and only
                arrivals within the time scope between ``start_date`` and ``end_date`` are considered.
            vehicle_arrives_at_time:
                A time at the day (between 00:00 and 23:59).
            average_vehicle_capacity:
                Number of TEU that can be transported with the vehicle at most.
            average_moved_capacity:
                Number of TEU which is imported.
            next_destinations:
                Pairs of destination and frequency of the destination being chosen.
            vehicle_arrives_every_k_days:
                Defaults to weekly services (arrival every 7 days). Other frequencies are possible as well.
                In the special case of ``-1``, only a single arrival at the day ``vehicle_arrives_at`` is scheduled.
                This arrival is only part of the generated container flow if that arrival lies between ``start_date``
                and ``end_date``.
        """
        pass

    def has_schedule(
            self,
            service_name: str,
            vehicle_type: ModeOfTransport
    ) -> bool:
        """
        Args:
            service_name: The name of the service which moves to a schedule that is sought for.
            vehicle_type: The mode of transport to restrict the search to.

        Returns: Whether the requested schedule already exist in the database
        """
        pass

Once I changed the signature to Union instead of |, the documentation built again including the type hints.

    def add_large_scheduled_vehicle(
            self,
            vehicle_type: ModeOfTransport,
            service_name: str,
            vehicle_arrives_at: datetime.date,
            vehicle_arrives_at_time: datetime.time,
            average_vehicle_capacity: Union[int, float],
            average_moved_capacity: Union[int, float],
            next_destinations: Union[List[Tuple[str, float]], None] = None,
            vehicle_arrives_every_k_days: Optional[int] = None
    ) -> None:

So if the | operator is not supported, this should be stated in the Readme and most preferably some kind of warning should be issued. Better even if the | operator for type hints would be supported though. Would this be possible in one of the future releases?

[gaborbernat]

This is supported, see our test suite https://github.com/tox-dev/sphinx-autodoc-typehints/blob/main/tests/roots/test-dummy/dummy_module_future_annotations.py https://github.com/tox-dev/sphinx-autodoc-typehints/blob/main/tests/test_sphinx_autodoc_typehints.py#L580-L613

We recently also filled https://github.com/tox-dev/sphinx-autodoc-typehints/pull/184 (released a few days back) that adds support for these on older python versions than 3.10. Can you provide a reproducible with the issue you're seeing? Repo, and command how you build it, output of it.

[1kastner]

Thank you very much for the hint. After an update, the behavior has definitively changed. I will inspect the output and return if other issues pop up.

[Zethson]

@gaborbernat I think I ran into this issue.

Reproducible example (please use a fresh environment! Python 3.8 is recommended.)

pip install poetry
git clone --recursive https://github.com/theislab/ehrapy/
cd ehrapy
make install
cd docs
make clean & make html

View the docs. The type hints still exist for functions which use the former Union and not the | character.

Happy to provide assistance if required.

Thank you very much!

[gaborbernat]

A PR addressing this would be welcome.

[Zethson]

A PR addressing this would be welcome.

I am afraid that I haven't found the root cause yet.

[bryanforbes]

please use a fresh environment! Python 3.8 is recommended

@Zethson have you tried building your docs in 3.10? I wonder if 3.8 is failing to evaluate the | types which causes this extension to ignore them.

[Zethson]

No, because my project does not support Python 3.10 yet and the building of the documentation requires it to be installed (for sphinx-click etc) I think.

But I'll keep it in mind.

[bryanforbes]

The reason I ask is because if that's the issue (the typings failing to evaluate correctly on 3.9 and earlier), I could submit a PR to add | evaluation to the extension via future_typing.

[Zethson]

Yeah, I see. But @1kastner seems to use 3.9 for his RTD build and it looks fine for him now? I am not sure what is going on in my case...

[1kastner]

My case has been solved after updating to a newer Python version and the discussion faded, thus I close this stale issue.