Possible reference link: "A guided tour from the Python REPL to PyPI & beyond"

[ncoghlan]

https://veekaybee.github.io/2017/09/26/python-packaging/ is an interesting article from @veekaybee that starts from the simplest possible Python component (a single statement at the REPL), and works its way all the way through to publication of a package with multiple submodules.

(Note: the article's actual title is "Alice in Python projectland", so the quoted bit in the issue title is just how I'd summarise what it's about)

https://packaging.python.org/tutorials/distributing-packages/#configuring-your-project is deliberately very prescriptive without really answering many "Why is it so?" questions, so this could be a good "See Also:" link at the start of that section for folks that want a better understanding of the bigger picture, rather than just following a prescriptive recipe.

[ncoghlan]

It occurs to me that another possible approach we could take is to add a "Further Reading" section to the end of the tutorial, and include not only this link, but also a few other references, such as:

• https://hynek.me/articles/sharing-your-labor-of-love-pypi-quick-and-dirty/
• http://docs.python-guide.org/en/latest/shipping/packaging/
• https://github.com/audreyr/cookiecutter-pypackage

The basic idea here would be to help folks that want to go beyond the tutorial's goal of "Here's a not-wrong way of doing things" by pointing them to more opinionated recommendations.

[pfmoore]

I like the approach of article, but there are quite a few points in it that are misleading or simply wrong. For example, when discussing requirements files, the article says the following, which is basically wrong:

For example, we’ve used os, sys, and re in building this module so far. These aren’t that out of the norm and most people should have them on their systems, but if they don’t, Python will download them from PyPI.

I don't want us to get into the position of being reviewers for 3rd party articles, nor do I want to appear to be criticising people for sharing their experiences, but I do think we need to be careful that things we link to from the official documentation are accurate.

Aargh, I hated writing the above - @veekaybee I actually really liked the article, and it was extremely interesting as a perspective on how people relatively new to Python packaging progress from "my little script" to something they can publish and reuse. And we need such articles, as those of us involved in packaging are often way too close to the problem to understand where the pain points are. I just don't know if we should link to this type of article from the docs.

[veekaybee]

For example, when discussing requirements files, the article says the following, which is basically wrong:

@pfmoore Can you elaborate on what I got wrong here? More than happy to edit the post. Like I mentioned, I want it to be an accurate reference for people. Thanks!

[pfmoore]

@veekaybee Well, sys, os, and re are standard library modules, and will always be available unless your python is broken. And they don't exist on PyPI, so pip wouldn't download them anyway.

You're also confusing the module name (that you use in the "import" statement) and the package name (that you install via pip). But that's an entirely reasonable confusion, and not something I'd try to explain at this point in your discussion.

Later in your article, you actually put numpy into the requirements.txt, which is a better example. But I don't think you use numpy in your code anywhere, which sort of spoils it :smile:. The problem of course is that you're giving a simple example, and it can be handled using the stdlib only. So there's no need for you to depend on anything external, so you don't have the chance to give a good example of how to use requirements.txt.

[ncoghlan]

The point about the standard library is made a couple of paragraphs further down: "because the three modules we’ve included, os, re, and sys, are part of the standard Python library. "

So while I agree the phrasing of the earlier paragraph could be improved a bit, the discrepancy is really just the known confusion around import packages vs distribution packages that we cover in the PyPUG glossary:

• https://packaging.python.org/glossary/#term-distribution-package
• https://packaging.python.org/glossary/#term-import-package

An "in theme" example of a possible external dependency would be to point to https://pypi.org/project/nltk/ if the project was going to be extended to things like checking grammar.

As far as linking from the docs go - I figure we're better off pointing to articles like @veekaybee's and then helping their authors to iteratively improve them, rather than leaving newcomers at the mercy of internet search engines and whatever search terms they happen to choose.

Besides, if we always demanded perfection from the start, PyPUG itself wouldn't exist - it was giving ourselves permission to promote it even in its current incomplete state that made it possible to get something published and then start iterating on it :)

[theacodes]

I figure we're better off pointing to articles like @veekaybee's and then helping their authors to iteratively improve them, rather than leaving newcomers at the mercy of internet search engines and whatever search terms they happen to choose.

Totally agree - in fact, I'm always happy to review external articles about packaging. My contact info is in my profile, and if the blog is stored on github they can summon me to the PR. I know that most of us in the PyPA can't commit to that, but I'm happy to do so as part of my community outreach time.

[pfmoore]

@jonparrott Brilliant - I do agree that starting with something that can be improved and working on it is a good approach (and as I say, I really did like the style of the article). I was just very conscious that I wasn't going to have the time to help with review and improvement, and I wasn't sure we had the resources for that. Good to know we do.

(And offtopic, but thanks for all the work you've been doing on the PUG).

[theacodes]

(And offtopic, but thanks for all the work you've been doing on the PUG).

Happy to help, I'm also trying to shuffle things so I can spend more time here in a consistent fashion.

[veekaybee]

Thanks so much for the feedback! I just pushed a change that includes nltk in the requirements file, which was a great suggestion, and cleared up the reference to os and co. as being part of the standard library. Regardless of what you decide, link or not, this feedback has been helpful in improving the post. https://github.com/veekaybee/veekaybee.github.io/commit/0c278fd87bc7c11308e3a2fc5f1e9ff864806e26