#16671: 5th tutorial on turning Polls into a reusable app
-------------------------------+------------------------------------
Reporter: stumbles | Owner: ben@…
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------+------------------------------------
Comment (by carljm):
Some comments on the updated draft:
* Per its author, setuptools is not defunct, and he has made fixes in it
since the distribute fork, so I think it's needlessly partisan to refer to
it as "defunct" and claim that it has "bugs which will never be fixed." I
recommend this alternative description of distribute: "It's a community-
maintained fork of the older setuptools project." (Also, there's a
mismatched parenthesis at the end of that sentence currently).
* I'm -0.5 on linking to the "state of Python packaging" diagram from the
Hitchhiker's Guide, as it has some factual errors (pip doesn't work
directly with distutils, it relies on setuptools/distribute) and makes
assertions which at this point remain far from clear (i.e. that
setuptools/distribute are headed for the dustbin, even though today they
remain by far the most-used Python packaging tools, or even that
distutils2 is headed for the stdlib - it was removed from Python 3.3 and
so far there's been no movement to reintroduce it for Python 3.4, rather
pieces of it are being rewritten under yet another name, "distlib"). On
the other hand, I appreciate the attractiveness of having something simple
to link to that demonstrates just how muddled things are, and I don't have
a replacement link target to recommend in that role.
* Including distribute (or setuptools) in the `install_requires` in
`setup.py` is wrong (unless your package actually imports and uses
"setuptools" or "pkg_resources" at runtime - not in setup.py but in the
actual packaged code - which the "polls" app does not). The note below
claims that "the install_requires line ensure that distribute will be
installed for anyone who is installing our package" but this is not true -
if someone doesn't have setuptools or distribute installed to begin with,
setup.py won't even run long enough to get to the `install_requires`,
it'll raise `ImportError` on the first line. And having `distribute` in
`install_requires` means that if a user has setuptools installed,
installing your package will forcibly replace it with distribute, which is
really unfriendly - the point of distribute being a drop-in replacement is
that your package should work equally well for people using setuptools or
distribute, and should not enforce one choice or the other on your users.
* Using `open('README.txt').read()` as the value of `long_description`
will break if `setup.py` is executed from outside the current directory
(e.g. `python django-polls/setup.py install`). For this to be reliable, an
`import os` is needed up top, then a `here =
os.path.dirname(os.path.abspath(__file__))`, then
`long_description=open(os.path.join(here, 'README.txt')).read()`.
* The line "only a limited set of files are included in the package by
default" could be made more specific: "only Python modules and packages
are included in the package by default."
Otherwise, looks good to me!
--
Ticket URL: <https://code.djangoproject.com/ticket/16671#comment:29>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
