<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Jul 14, 2013 at 4:23 AM, Noah Kantrowitz <span dir="ltr"><<a href="mailto:noah@coderanger.net" target="_blank">noah@coderanger.net</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5"><br>
On Jul 14, 2013, at 12:35 AM, Nick Coghlan wrote:<br>
<br>
> On 14 July 2013 17:13, Donald Stufft <<a href="mailto:donald@stufft.io">donald@stufft.io</a>> wrote:<br>
> I think it would be reasonable for the pip maintainers to be asked to declare a public API (even if that's "None") using the naming scheme or an import warning and declare a backwards compatibility policy for pip itself so that people can know what to expect from pip. I do not however, believe it is reasonable to bind pip to the same policy that CPython uses nor the same schedule. (If you weren't suggesting that I apologize).<br>


><br>
> The main elements of CPython's backwards compatibility policy that I consider relevant are:<br>
><br>
> * Use leading underscores to denote private APIs with no backwards compatibility guarantees<br>
> * Be conservative with deprecating public APIs that aren't fundamentally broken<br>
> * Use DeprecationWarning to give at least one (pip) release notice of an upcoming backwards incompatible change<br>
><br>
> We *are* sometimes quite aggressive with deprecation and removal even in the standard library - we removed contextlib.nested from Python 3.2 as a problematic bug magnet well before I came up with the contextlib.ExitStack API as a less error prone replacement in Python 3.3. It's only when it comes to core syntax and builtin behaviour that we're likely to hit issues that simply don't have a sensible deprecation strategy, so we decide we have to live with them indefinitely.<br>


><br>
> That said, I think the answer to this discussion also affects the answer to whether or not CPython maintenance releases should update to newer versions of pip: if pip chooses to adopt a faster deprecation cycle than CPython, then our maintenance releases shouldn't bundle updated versions. Instead, they should follow the policy:<br>


><br>
> * if this is a new major release, or the first maintenance release to bundle pip, bundle the latest available version of pip<br>
> * otherwise, bundle the same version of pip as the previous release<br>
><br>
> This would mean we'd be asking the pip team to help out by providing security releases for the bundled version, so we can get that without breaking the public API that's available by default.<br>
><br>
> On the other hand, if the pip team are willing to use long deprecation cycles then we can just bundle the updated versions and not worry about security releases (I'd prefer that, but it only works if the pip team are willing to put up with keeping old APIs around for a couple of years before killing them off once the affected CPython branches go into security fix only mode).<br>


<br>
</div></div>If I can surmise your worry here, it is that people will open an interactive terminal, import pip, reflect out the classes/methods/etc, see that despite being mentioned no-where in the Python or pip documentation the methods and classes don't start with an underscore, and thus conclude that this is a stable API to build against?</blockquote>

<div><br></div><div>Yes, and to make that statement even stronger: all of that happening with a freshly installed copy of Python with no external packages installed. Nick's worry stems from experience (which I have also had) where people simply don't check docs as to whether something is public in the stdlib and so it ends up being considered such by users to the point that we feel obliged to support it.</div>

<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> I agree that conventions are good, but I have to say this sounds like a bit of a stretch and certainly anyone complaining that their undocumented API that they only found via reflection (or reading the pip source) was broken basically gets what they deserve.</blockquote>

<div><br></div><div>That's what we typically say for older modules, especially when we are cranky. =) But it doesn't stop the wingeing and bug reports. Luckily I think we have gotten better about this.</div><div>
 </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> The point I was trying to make is that a major shift in thinking is needed here. pip is not part of CPython, regardless of this bundling neither this mailing list nor the CPython team will have any control (aside from the nuclear option that the CPython team can elect to stop bundling pip). If you think it would be good for the code-health of pip to be clearer about what their public API is, I will suppor<br>


 t that all the way and in fact have an open ticket against pip to that effect already, but that is something for the pip team to decide. This does very much mean that the CPython team is not just backing the pip codebase, but the PyPA/pip team. I think the past few years have shown them deserving of this trust, and they should be allowed to run things as they see fit. These lines get blurry since several people move back and forth between CPython and PyPA (and distutils and PyPI, etc) hats, so I think this must be stated clearly up front that what the CPython team thinks is "reasonable" for an API policy will be nothing more than a recommendation from very knowledgable colleagues and will be given the appropriate consideration and respect it deserves based on that. Hopefully that makes my point-of-view a little clearer.<br>

</blockquote><div><br></div><div>I think it's all going to come down to messaging. It will have to be yelled form the top of every mountain that pip is being bundled with Python as a convenience to the community, but that it is **NOT** part of the (C)Python project and thus has it's own development process, issue tracker, etc. If Python bundles pip then python-dev will make promises about what versions we include in bugfix releases, how it's bundled, etc., but otherwise it's a separate project with its own rules.</div>

</div></div></div>