Reorder Stereographic args to avoid API breaking 0.15 -> 0.16.

[pp-mo]

In #929 a new argument was added into Stereographic.__init__, but not at the end.
This affects the meaning of usages that rely on argument-order, and broke a couple of tests in Iris.
See : SciTools/iris#2971

So, it is a breaking API change in 0.16.

Can we consider putting this back ?

Although, I realise

1. it may look neater to put globe last ? (though other classes now don't)
2. fix will compound problems #by being another breaking change (!)

[dopplershift]

Oops. I think we need @pelson to weigh in on which to break things.

[pelson]

Oops. I think we need @pelson to weigh in on which to break things.

Hmmm. If we were living in a non-legacy world, all of these would be keyword only arguments. I'd be happy enough to make that a general case (documented but un-inforced) rule about the cartopy API and keywords...

I hadn't realised how close keyword-only args got to py2.7... https://bugs.python.org/issue1745. If only 😢

In terms of the current situation - I don't think we should introduce a breaking change to undo the breaking change in this case, because in reality the current order is preferable (if only for documentation purposes).

@pp-mo - I'm not even sure if we should have this entry in our what's new - it is definitely too much detail in some regards, but for those that get caught out by it (Iris) it is a pretty painful one to diagnose. 😕 Thoughts?

[pelson]

Closing this out. For consistency, I'm very happy having globe as the last keyword (for consistency in docs etc.). I'm also quite comfortable in saying that the kwarg order is not part of the guaranteed API. Essentially, when we transition to py3 we will move these kwargs to keyword-only kwargs, thus preventing this happening again (because you won't be able to use these in a positional way).