Deprecation warnings to streamline migration from 0.3 to 0.4

[smmaurer]

Pandana 0.4 made some changes to the API that cause older user code to crash. We're still running into this in UrbanSim models, and it's hard for people to diagnose the errors if they're not expecting them.

In the next point release, I think we should make some small adjustments to allow older code to continue running, raising deprecation warnings to explain the changes that need to be made:

1. pandana.network.reserve_num_graphs()

This was removed in 0.4 because improvements to the memory management mean that it's no longer necessary. But it appears frequently in older user code.

Current behavior:

• code that calls this function crashes, usually with an AttributeError, because the function no longer exists

Proposed behavior:

• allow the function call, but ignore it and raise a DeprecationWarning alerting users that it's no longer necessary

2. pandana.Network().init_pois() and set_pois()

In 0.4 init_pois() was removed, and two of its arguments were shifted to set_pois().

Current behavior:

• code that calls init_pois() crashes
• code that calls set_pois() expecting the older API crashes with a TypeError because not enough arguments are provided

Proposed behavior:

• one of the shifted arguments is currently saved as a class attribute, and i don't see a problem with saving the other one as well
• i think we should allow calls to init_pois(), save the two relevant arguments as class attributes, and raise a DeprecationWarning alerting users of the API change
• set_pois() should read those two arguments from the class attributes if they're not provided, and raise a DeprecationWarning explaining that they shouldn't be provided through init_pois() any more

Discussion

Making these changes would allow code written for Pandana 0.3 to continue running, while explaining to users how to make the appropriate updates. I think this would be pretty valuable and save some headaches.

For example, it looks like urbansim itself still pins its pandana requirement at 0.3, presumably because of the API changes -- this should make migration easier.

[smmaurer]

More info from @sablanchard: UrbanSim is pinned at Pandana v0.3 in part because 0.4.0 had installation problems in Windows. v0.4.1. fixed this, but UrbanSim hasn't been updated yet to reflect that.

[smmaurer]

Fixed in PR #116, thanks @alephcero!