search

scaleway / postal-address

:postal_horn: Parse, normalize and render postal addresses.
https://postal-address.readthedocs.io
Other
181 stars 16 forks source link

Document stability policy #8

Closed EvaSDK closed 9 years ago

EvaSDK commented 9 years ago

0.3.0 release moved some code around and thus breaks components using the symbols where they were located resulting in this sample backtrace:

[...]
   from postal_address.address import supported_territory_codes
ImportError: cannot import name supported_territory_codes

This specific break occurs when upgrading from 0.2.1 to 0.3.0 and the CHANGES.rst did not make any mention of that.

There is no such thing as private symbols in python, except for well documented _ or __ class or module members so please write a little something about the stability or lack thereof of the module.

kdeldycke commented 9 years ago

That's unfortunately the only backward-incompatible change between the 0.2 to 0.3 series. All others have been marked with a proper deprecation warning.

@EvaSDK : do you have an idea how to create a transition path in such cases ? I'm thinking of hard-coded imports of postal_address.territory.* in postal_address.address and a deprecation warning in postal_address.address. Is that enough in your opinion ?

EvaSDK commented 9 years ago

That would work. You can also have wrapper functions that do the actual import and raise the warning only when appropriate.

kdeldycke commented 9 years ago

@EvaSDK : See my brand new PR at https://github.com/online-labs/postal-address/pull/9