Possible backwards-incompatible change between 2.1.1 and 2.2.3

[yhoiseth]

Today, I upgraded from version 2.1.1 to version 2.2.3. The following code started throwing an exception on our queue worker:

    def allowed_hosts(self) -> List[str]:
        allowed_hosts: List[str] = ["localhost", "127.0.0.1", "[::1]"]
        if self.is_valid_platform() and self.in_runtime():
            try:
                for url, route in self.routes().items():
                    host: str = urlparse(url).netloc
                    if (
                        host not in allowed_hosts
                        and route["type"] == "upstream"
                        and route["upstream"] == self.applicationName
                    ):
                        allowed_hosts.append(host)
            except AttributeError:
                """
                The Huey worker doesn't have access to routes.
                """
                pass
        return allowed_hosts

The following exception was raised:

platformshconfig.config.NotValidPlatformException: No routes are defined.  Are you sure you are running on Platform.sh?

By replacing AttributeError with NotValidPlatformException (and adding the required import statement), the problem was resolved.

This caused our transactional emails to not be taken out of the queue while I fixed the issue. Not a huge issue this time because I tested manually and discovered the problem quickly, but not ideal either.

[yhoiseth]

I'd like to share some thoughts on this. First, I'd like to point out that our code is a lot more elegant and easy to maintain thanks to this library. I find it very useful and I am grateful that you made it.

That said, I think it leaves some things to be desired which would make using it easier and less error-prone.

1. Reserve backwards-incompatible changes to major versions. (I think this is a backwards-incompatible change because the type of exception isn't documented, as far as I can see.)
2. Provide some kind of changelog for new versions.
3. Improve the handling of worker instances. For example, on our Redis worker, the NotValidPlatformException with the message "Are you sure you are running on Platform.sh?" does not make much sense.
4. Ideally, worker instances would have access to routes. Currently, we have to hard-code our URL in order to generate links in transactional emails. (This is, as far as I can tell, not an issue with the library, but with Platform.sh itself.)

I think avoiding backwards-incompatible changes is especially important in an infrastructure library like this, because it's quite difficult to test automatically, especially when using outside services like email. And in any case, a changelog (e.g. on https://github.com/platformsh/config-reader-python/releases) would be very helpful. See https://github.com/facebook/create-react-app/releases for an example of how breaking changes can be highlighted.

[yhoiseth]

After looking at the library code, I realized that I could simplify my code by catching RuntimeError:

    def allowed_hosts(self) -> List[str]:
        allowed_hosts: List[str] = ["localhost", "127.0.0.1", "[::1]"]
        try:
            for url, route in self.routes().items():
                host: str = urlparse(url).netloc
                if (
                    host not in allowed_hosts
                    and route["type"] == "upstream"
                    and route["upstream"] == self.applicationName
                ):
                    allowed_hosts.append(host)
        except RuntimeError:
            pass
        return allowed_hosts