yes, #10 covers this a bit, but yes, I agree more could be done.

a start maybe would be to add a "Do I need a requirements file?" section to the Packaging guide, that covers the distinction

another way to describe the distincton is between a library, and a project that owns the python environment and manages the requirements file.

I was thinking of starting out simply by defining terms for the two cases, so that the terms could be used elsewhere in the guide, e.g. in a requirements file section like you suggested. The distinction is important also for installers of projects, because it helps installers understand why pip install -r requirements.txt is used for some projects and not others.

Can you think of names for these two types of projects (for the purposes of the Guide)? My initial thought was "library project" and "application project," but maybe there is language that is more to-the-point.

Library vs application are the traditional names (in this context, frameworks are just opinionated libraries that exert a lot of influence on the overall architecture of your application).

Okay, thanks. I will take a crack at the kind of PR I was thinking of after issue #97 is addressed.

Library vs application are the traditional names (in this context, frameworks are just opinionated libraries that exert a lot of influence on the overall architecture of your application).

@ncoghlan, and how about the word "project"? Are we taking this to be a synonym of "library" (in the general sense of the word), or is project the umbrella term that encompasses both libraries and applications? The latter seems to make more sense from an English perspective. If the former, when should we use the word library and when the word project? Thanks.

Project is the umbrella term. Depending on context, it may also encompasses the folks working on it (and their ways of working), not just the software itself.

Okay, then if that's the case, it seems like we should change the Tutorial on Packaging and Distributing Projects to say "library" in most places instead of "project" (after defining library appropriately in the glossary). It seems like everything in that tutorial is specific to packaging libraries and isn't applicable to packaging applications.

Respecting that distinction in the tutorial will help a lot in our efforts to educate people about libraries and applications and why their dependencies are handled differently, etc.

Hmm, I tend to see "applications" as one of 3 things:

1. A one-file .py script that has to be run with Python, and may need the user to have certain libraries installed.
2. A library that includes console_scripts entry points. I tend to think of these more in terms of "library" than "application", although they may well have little or no library API (pip is a good example here).
3. Standalone applications. On Windows that usually means py2exe style bundled applications, although "executable zip" solutions like pyzzer would often be better (I don't think there's much in the way of good practice established for executable zips, though).

While I'd love to see documentation/advice on developing all of these (except maybe the first :-)) I'm not sure it's in scope for the PUG.

Oh, I didn't mean to suggest that the scope should be changed. I just wanted the tutorial to be clearer that it is a guide for packaging "libraries" (e.g. your (2) above) and not "applications" (e.g. your (3) above). In particular, I'm suggesting that the title of the tutorial be changed to, "Tutorial on Packaging and Distributing Libraries."

(This wouldn't preclude us though from adding guidance at a later date on packaging stand-alone applications, etc.)

Or even "Tutorial on Creating Distribution Packages." :) The main point is not to use the umbrella word "project" when we really mean "library."

Right, PyPUG is mostly aimed at creating, sharing and consuming building
blocks as Python developers, rather than being about distributing
software to the general public. The latter is well out of scope for PyPUG.

I think "distribution packages" is the best term we have, though. It's the
only one that allows distutils, distlib, sdist and bdist to make sense,
without being too ambiguous :)

-1 on changing "project" to "library". that feels odd to me.
I do think it's important for people to understand these distinctions, specifically in the context of requirements files vs install_requires. You could write an "Advanced" section in the "Concepts and Analyses" section that tries to break all this down, and reference that in a few places where it comes up