Imports in the tutorial
Andrew Godwin
I noticed today that the tutorial still does imports like "from
mysite.polls.models import Poll", and URLs like "(r'^polls/$',
'mysite.polls.views.index')".
At least in the places and projects I've worked with, the standard has
been not to use the project name as part of the import, for various reasons:
- It makes apps more reuseable and not tied to the one project
- It means you can't run two copies of the same application if they're
direct neighbours (as, to get the imports running, you need to add the
directory the project is contained in to the Python path, and thus you
can't rename the directory from its import name).
I realise both of these can be worked around (and I do a lot), but it
would seem common sense to start encouraging people to do imports like
"from polls.models import Poll" from day one. There might well be
something I'm missing - please say - but this has bugged me for ages.
(The previous threads I can find on this topic seems to end pretty
inconclusively, and were in 2007 and 2009, so I feel partially justified
in bringing this up again.)
I'm happy to write a patch for the docs to change it to match should
people agree - I just feel like I'm missing something here, as it's not
been done yet.
Andrew
Harro
just point to urls instead of project_name.urls
Kevin Howerton
just point to urls instead of project_name.urls"
Indeed, always the first thing I change when I start a project...
Having the project_name there means you are including the directory
above your project in the python path in your wsgi setup, which is not
needed and can cause name collisions and what-not.
-k
Peter Baumgartner
> Hi all,
>
> I noticed today that the tutorial still does imports like "from
> mysite.polls.models import Poll", and URLs like "(r'^polls/$',
> 'mysite.polls.views.index')".
>
> At least in the places and projects I've worked with, the standard has been
> not to use the project name as part of the import, for various reasons:
>
> - It makes apps more reuseable and not tied to the one project
In my experience, almost every project has domain-specific
applications that don't get reused. If you have a reusable app, you
bundle it separately (like South).
> - It means you can't run two copies of the same application if they're
> direct neighbours (as, to get the imports running, you need to add the
> directory the project is contained in to the Python path, and thus you can't
> rename the directory from its import name).
Why do you need to change the Python path at all? Just drop your
project on the existing Python path and import from there. This is
easy enough with a symlink or better yet give it a setup.py and
install it like you would any other Python package.
>
> I realise both of these can be worked around (and I do a lot), but it would
> seem common sense to start encouraging people to do imports like "from
> polls.models import Poll" from day one. There might well be something I'm
> missing - please say - but this has bugged me for ages.
>
I agree that it is confusing that it will work either way, but I'd
argue in favor of using the project name everywhere. It is explicit
instead of mucking around with the Python path behind the scenes.
-- Pete
Andrew Godwin
On 11/06/2010 03:28, Peter Baumgartner wrote:
> In my experience, almost every project has domain-specific
> applications that don't get reused. If you have a reusable app, you
> bundle it separately (like South).
>
I entirely agree, but there's also a lot of domain-specific apps people
make that get used in more than one project. If you're in the business
of writing (say) CMS-backed sites, you're going to have a lot of apps
matching that pattern, and as far as I'm aware, there's no downside to
switching away from having project names in imports.
> Why do you need to change the Python path at all? Just drop your
> project on the existing Python path and import from there. This is
> easy enough with a symlink or better yet give it a setup.py and
> install it like you would any other Python package.
>
But that doesn't work. Say I have my nice shiny project "andrewblog". I
want to deploy a staging version and a live version of this on my server.
If I had local imports, I could just put both projects on the python
path / install them / egg-link them, or whatever. But because they use
module names for imports, if I install one site as a package
"andrewblog" and the other as "andrewblog_staging", say, staging is
actually going to be running off of the live models, URLs, etc, since it
has code that goes "from andrewblog.posts.models import Post".
> I agree that it is confusing that it will work either way, but I'd
> argue in favor of using the project name everywhere. It is explicit
> instead of mucking around with the Python path behind the scenes.
>
Explicitness is good. I like being explicit, that's one of the reasons I
love Python. But I'd argue that having to separate installations of the
same app because they _have_ to have the same package name involves more
python path mucking around than just installing them on the global path
with different names.
Andrew
Javier Guerra Giraldez
>> I agree that it is confusing that it will work either way, but I'd
>> argue in favor of using the project name everywhere. It is explicit
>> instead of mucking around with the Python path behind the scenes.
>>
>
> Explicitness is good. I like being explicit, that's one of the reasons I
> love Python. But I'd argue that having to separate installations of the same
> app because they _have_ to have the same package name involves more python
> path mucking around than just installing them on the global path with
> different names.
there's a difference between being explicit and introducing unneeded
dependencies.
--
Javier
Peter Baumgartner
>
>
> On 11/06/2010 03:28, Peter Baumgartner wrote:
>>
>> In my experience, almost every project has domain-specific
>> applications that don't get reused. If you have a reusable app, you
>> bundle it separately (like South).
>>
>
> I entirely agree, but there's also a lot of domain-specific apps people make
> that get used in more than one project. If you're in the business of writing
> (say) CMS-backed sites, you're going to have a lot of apps matching that
> pattern, and as far as I'm aware, there's no downside to switching away from
> having project names in imports.
>
>> Why do you need to change the Python path at all? Just drop your
>> project on the existing Python path and import from there. This is
>> easy enough with a symlink or better yet give it a setup.py and
>> install it like you would any other Python package.
>>
>
> But that doesn't work. Say I have my nice shiny project "andrewblog". I want
> to deploy a staging version and a live version of this on my server.
>
> If I had local imports, I could just put both projects on the python path /
> install them / egg-link them, or whatever. But because they use module names
> for imports, if I install one site as a package "andrewblog" and the other
> as "andrewblog_staging", say, staging is actually going to be running off of
> the live models, URLs, etc, since it has code that goes "from
> andrewblog.posts.models import Post".
Why do your two sites need to share the same python path? Virtualenv
solves this problem quite gracefully.
-- Pete
Andrew Godwin
> Why do your two sites need to share the same python path? Virtualenv
> solves this problem quite gracefully.
>
They don't have to, but bear in mind that:
a) The tutorial is aimed at people new to Django, and often new to
Python. Virtualenv isn't even on their radar at this point.
b) Bugs from this issue can be really tricky to track down, and I've
seen it happen several times on both developer workstations and servers.
I'm not saying that removing them is entirely a win, but for the target
audience of that document, I really think it's appropriate to teach it
from the start. I've seen new Django developers make the mistake of
importing from the project name countless times in
supposedly-reuseable-internally apps, and I've spent many hours going
through with grep and fixing it.
The way I see it, if we remove them, the worst bug that could happen is
if someone manages to get two different project directories on their
python path at the same time (thus the app namespace clashes).
Compared to the alternative, and the unlikeliness of this scenario, I
really feel it's the best move, unless we try to teach new users about
virtualenv, pip, dependency files, and the whole stack that a lot of
more advanced Django developers use. We certainly need to think about
teaching that stuff - it came up as a topic during djangocon.eu, but I
don't think any consensus was reached - but you need to walk before you
can run.
Andrew
Lawrence, Gabriel
Just a reference point.
Cheers,
gabe
Russell Keith-Magee
> Hi all,
>
> I noticed today that the tutorial still does imports like "from
> mysite.polls.models import Poll", and URLs like "(r'^polls/$',
> 'mysite.polls.views.index')".
It also says "coming soon" at the end of tutorial 4. It has said that
for a while now :-)
You're not missing anything specific -- it's really just a matter of
time. Good documentation take time to write; doubly so for good
tutorials.
The issue you raise - that the current tutorial is exclusively "app
inside project" has been raised as a ticket more times than I care to
count. I would certainly welcome anybody that wants to fix it so that
it never gets raised again :-)
It's not as simple as just rewriting the existing 4 steps of the
tutorial, though. As Peter points out, there is a legitimate use case
for "project-specific apps" -- as a way of namespacing apps that truly
are project specific.
Where the current tutorial fails is that it doesn't take the next step
by and demonstrate how (and when) an app can (or should) be broken out
from the project structure. The simple step of making the 'poll' a
truly reusable app, and explaining why this is a good idea, would be a
great tutorial 5 IMHO. Part of this tutorial may be to point out
exactly how unnecessary the 'project' directory really is in the
purist sense -- at the end of the day, all you really need is a
settings file and a bunch of apps in your PYTHONPATH.
Yours,
Russ Magee %-)
Andrew Godwin
On 11/06/2010 17:38, Russell Keith-Magee wrote:
> You're not missing anything specific -- it's really just a matter of
> time. Good documentation take time to write; doubly so for good
> tutorials.
>
> The issue you raise - that the current tutorial is exclusively "app
> inside project" has been raised as a ticket more times than I care to
> count. I would certainly welcome anybody that wants to fix it so that
> it never gets raised again :-)
>
> It's not as simple as just rewriting the existing 4 steps of the
> tutorial, though. As Peter points out, there is a legitimate use case
> for "project-specific apps" -- as a way of namespacing apps that truly
> are project specific.
>
> Where the current tutorial fails is that it doesn't take the next step
> by and demonstrate how (and when) an app can (or should) be broken out
> from the project structure. The simple step of making the 'poll' a
> truly reusable app, and explaining why this is a good idea, would be a
> great tutorial 5 IMHO. Part of this tutorial may be to point out
> exactly how unnecessary the 'project' directory really is in the
> purist sense -- at the end of the day, all you really need is a
> settings file and a bunch of apps in your PYTHONPATH.
>
Right, I remember the whole "Part 5" and virtualenv thing being
discussed before. If we can come to some consensus on what should go in
there, I'm happy to write more tutorial parts/edit the current ones and
have someone who doesn't, write, like they, speak, go over it in an
editorial role.
Problem is there's several things that could go in a part 5 (in addition
to all of those there currently), like:
- Making your apps reuseable (so things like removing project name
imports, adding a setup.py, general python packaging theory)
- Using virtualenv to run multiple copies of apps/projects/Django
side-by-side on a development box
- Basic deployment onto servers (this is kind of covered elsewhere, so
perhaps just a pointer, or refine those docs with more common pitfalls)
There's also the risk of guiding people down too narrow a path. I'm
really not very good at deciding the order and layout of documentation,
just at generating it in large amounts (see the mass of mostly
unnavigable words that is the South docs).
Andrew
Russell Keith-Magee
>
>
> On 11/06/2010 17:38, Russell Keith-Magee wrote:
>
> You're not missing anything specific -- it's really just a matter of
> time. Good documentation take time to write; doubly so for good
> tutorials.
>
> The issue you raise - that the current tutorial is exclusively "app
> inside project" has been raised as a ticket more times than I care to
> count. I would certainly welcome anybody that wants to fix it so that
> it never gets raised again :-)
>
> It's not as simple as just rewriting the existing 4 steps of the
> tutorial, though. As Peter points out, there is a legitimate use case
> for "project-specific apps" -- as a way of namespacing apps that truly
> are project specific.
>
> Where the current tutorial fails is that it doesn't take the next step
> by and demonstrate how (and when) an app can (or should) be broken out
> from the project structure. The simple step of making the 'poll' a
> truly reusable app, and explaining why this is a good idea, would be a
> great tutorial 5 IMHO. Part of this tutorial may be to point out
> exactly how unnecessary the 'project' directory really is in the
> purist sense -- at the end of the day, all you really need is a
> settings file and a bunch of apps in your PYTHONPATH.
>
>
>
> Right, I remember the whole "Part 5" and virtualenv thing being discussed before. If we can come to some consensus on what should go in there, I'm happy to write more tutorial parts/edit the current ones and have someone who doesn't, write, like they, speak, go over it in an editorial role.
What - very very quickly? I don't see the problem :-)
> Problem is there's several things that could go in a part 5 (in addition to all of those there currently), like:
>
> - Making your apps reuseable (so things like removing project name imports, adding a setup.py, general python packaging theory)
> - Using virtualenv to run multiple copies of apps/projects/Django side-by-side on a development box
> - Basic deployment onto servers (this is kind of covered elsewhere, so perhaps just a pointer, or refine those docs with more common pitfalls)
That sounds like three potential tutorials to me. Better get your
pencil nice and sharp :-)
> There's also the risk of guiding people down too narrow a path. I'm really not very good at deciding the order and layout of documentation, just at generating it in large amounts (see the mass of mostly unnavigable words that is the South docs).
Honestly - getting a good first draft is the hardest part. Working out
a good example, working out a seizable order for presentation within
he tutorial, and getting even a rough first cut at the text is the
biggest hurdle. Once we have that, it's relatively simple to knock a
draft into shape and fit it into a bigger picture.
Yours,
Russ Magee %-)
Andrew Godwin
On 12/06/2010 01:03, Russell Keith-Magee wrote:
> What - very very quickly? I don't see the problem :-)
>
Well, that wasn't quite the quality I was going for, but you never know.
>> Problem is there's several things that could go in a part 5 (in addition to all of those there currently), like:
>>
>> - Making your apps reuseable (so things like removing project name imports, adding a setup.py, general python packaging theory)
>> - Using virtualenv to run multiple copies of apps/projects/Django side-by-side on a development box
>> - Basic deployment onto servers (this is kind of covered elsewhere, so perhaps just a pointer, or refine those docs with more common pitfalls)
>>
> That sounds like three potential tutorials to me. Better get your
> pencil nice and sharp :-)
>
> Honestly - getting a good first draft is the hardest part. Working out
> a good example, working out a seizable order for presentation within
> he tutorial, and getting even a rough first cut at the text is the
> biggest hurdle. Once we have that, it's relatively simple to knock a
> draft into shape and fit it into a bigger picture
Right, but I really think reuseability, packaging and virtualenv is a
combination that could be worked into one tutorial part (they tend to be
quite long, but I'm not sure if that's an overwhelmingly good thing).
If nobody has any particular suggestions, I'll try to cook up a very
basic outline/first draft this week, and see what people think. I'm
unfortunately not that much of a heavy virtualenv user, so I might just
take a stab at the first part, but I feel like there really does need to
be a bit more tutorial after all these years. I find it even funnier
that the section I'm proposing to add isn't one of those in the "Coming
Soon" section.
Andrew
Brian Luft
Kudos to Andrew for showing initiative.
Short of new tutorials, I think the best service we could do for the
(beginner) community is to at least call out a sidebar that provides
some brief context around whether or not to namespace by project.
Since this is a matter of personal preference the responsible thing is
for the documentation to make people aware of the choices and what the
associated trade-offs are. It seems like this could be done in a few
paragraphs and would serve to concisely indicate that:
* there are different ways to do it
* each has its (subjective) pros/cons
* Django isn't endorsing a particular style but has chosen one for the
sake of convenience in the tutorial
-Brian
.
Andrew Godwin
On 15/06/2010 20:52, Brian Luft wrote:
> Short of new tutorials, I think the best service we could do for the
> (beginner) community is to at least call out a sidebar that provides
> some brief context around whether or not to namespace by project.
> Since this is a matter of personal preference the responsible thing is
> for the documentation to make people aware of the choices and what the
> associated trade-offs are. It seems like this could be done in a few
> paragraphs and would serve to concisely indicate that:
>
> * there are different ways to do it
> * each has its (subjective) pros/cons
> * Django isn't endorsing a particular style but has chosen one for the
> sake of convenience in the tutorial
>
This I like - there's only two ways, so it won't be very long, and if I
do get a part 5 out we can say "part 5 shows you the other option in
more detail".
When I get around to my first attempt at part 5, I'll include an
interjection somewhere in the other parts in the patch, and people can
see if they feel like it's not too much of a distraction.
Andrew