Update NSAPI to 3.0.2

[YarmoM]

Breaking Change:

The "RetrieveTripInformationPublic" API ("Public-Travel-Information" product) will be deprecated on 31-01-2020. All users MUST create a new API token for the "Reisinformatie" API ("Ns-App" product) and use that one instead.

Description:

The NSAPI dependency was updated to 3.0.2. Changes include:

• fix the API URLs deprecated on 31-01-2020 (IMPORTANT)
• fix a minor inconsistency in train times and platforms

Related issue (if applicable): not applicable

Pull request with documentation for home-assistant.io (if applicable): home-assistant/home-assistant.io#11843

Example entry for configuration.yaml (if applicable):

sensor:
- platform: nederlandse_spoorwegen
  api_key: !secret NS_API_KEY
  routes:
    - name: Amsterdam-Den Haag
      from: Asd
      to: Gvc

Checklist:

• The code change is tested and works locally.
• Local tests pass with tox. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated in home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly. Update and include derived files by running python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt by running python3 -m script.gen_requirements_all.
• Untested files have been added to .coveragerc.

If the code does not interact with devices:

• Tests have been added to verify that the new code works.

[aquatix]

Are you planning on updating https://github.com/home-assistant/home-assistant.io/blob/current/source/_integrations/nederlandse_spoorwegen.markdown too?

[YarmoM]

Yes. As soon as NSAPI 3.0.2 (or whatever is the next version) launches, I will update the documentation. Technically, the current documentation is correct for 3.0.1, even though it will become obsolete and incorrect as of 31st of Jannuary 2020.

[b10m]

Could we maybe get a warning in place when email and/or password configuration settings are found? This (well, the previous MR) is a breaking change and instructing people to get a new API key might be pleasant.

[b10m]

I also see departure_platform and arrival_platform have been replaced by _planned and _actual counterparts. Could we please get the old keys back as well? It makes notifications a lot easier (I often don't mind whether it has been changed or updated, I want to see where I have to go).

E.g.:

"departure_platform": self._trips[0].trip_parts[0].stops[0].actual_platform if self._trips[0].trip_parts[0].stops[0].platform_changed else self._trips[0].trip_parts[0].stops[0].planned_platform,

[YarmoM]

@b10m
Regarding email/password, does Home-Assistant have any warning system for this use? I guess the changelog might have to suffice. Also, if my understanding of NS' changes is correct, anyone with a now-working setup will see error messages as of 31st of January. I only came across this integration about a month ago, it wasn't working and NS had already said it was planned to not work for anyone starting February. Trying to meet the deadline. I'm expecting a whole influx of complaints starting February.

Regarding platforms, well then _actual is the one you will want to use since it represents the "actual" platform whether changed or not.

[YarmoM]

And by the way, I have also already changed the documentation (and will update more soon, hopefully today) with instructions on getting api tokens, NS no longer accepts email and password.

[b10m]

@b10m
Regarding email/password, does Home-Assistant have any warning system for this use? I guess the changelog might have to suffice.

We can detect these old configs easily, so why not? It's really simple, e.g.:

def setup_platform(hass, config, add_entities, discovery_info=None):
    """Set up the departure sensor."""

    if config.get(CONF_EMAIL):
        hass.components.persistent_notification.create(
            'The Nederlandse Spoorwegen component requires a new API key now, please see <link> for upgrade instructions.',
            title='NS Upgrade error',
            notification_id='nederlandse_spoorwegen_upgrade_error')

This gives a nice informative message like:

Regarding platforms, well then _actual is the one you will want to use since it represents the "actual" platform whether changed or not.

Please document that change as well, since people may use these attributes in their templates.

Nevertheless, thanks for the upgrade. I should've pushed my local changes through long time ago, so thanks for doing that instead!

[YarmoM]

@b10m that's a clever solution, I will add it to the current PR. Thing is, until we integrate 3.0.2 (just released), all solutions will fail on 31st of January. Hopefully we can merge this PR as soon as possible.

[aquatix]

@YarmoM are you going to update this PR to 3.0.2? That would save the trouble of opening yet another one for just a version bump.

[YarmoM]

Good solution, going with that, assuming this is ok with the core devs.

[MartinHjelmare]

It seems the state attributes are changing slightly. Should we mention that in the breaking change paragraph?

Regarding changing api key as stated in the breaking change paragraph, is that on top of last PR that required the api key instead of username and password or is it the same change?

[YarmoM]

It seems the state attributes are changing slightly. Should we mention that in the breaking change paragraph?

Theoretically, nothing has changed. #30599 pulled NS-api v3.0.0 which inadvertently introduced a consistency error, which I in turn corrected for in that PR. NS-API v3.0.2 fixes these errors and this is now reflected in this PR (code is a lot simpler now). Since #30599 hasn't made it into a release yet, if #30599 and #30971 make a release together, the behavior should not have changed.

I did just notice that #30599 failed to mention the renaming of a few attributes in the breaking changes... My bad :( These changes were made for naming consistency. Could this then be added here in Breaking Changes?

Regarding changing api key as stated in the breaking change paragraph, is that on top of last PR that required the api key instead of username and password or is it the same change?

No, this is a separate change on top of the last PR. NS made two changes: email/password is no longer accepted and a new API supersedes an old API. #30599 fixed the email/password change. #30971 fixes the change of API.

[MartinHjelmare]

We can still adjust the breaking change paragraph in #30599. Please do that or if it's locked, post it here and I'll change there.

[YarmoM]

It is locked indeed. Something like this for the #30599 breaking changes (first line already exists):

The `nederlandse_spoorwegen` sensor now requires a single API token instead of username and password credentials.

The following `platform` attributes are renamed for consistency with `time` naming:
- `departure_platform` becomes `departure_platform_planned`
- `departure_platform_changed` becomes `departure_platform_actual`
- `arrival_platform` becomes `arrival_platform_planned`
- `arrival_platform_changed` becomes `arrival_platform_actual`

[MartinHjelmare]

Thanks! I've updated #30599.

[MartinHjelmare]

Tagging this for 0.105 since we want both breaking changes go out in the same release and the upstream api has already changed.