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.
> 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.
"I agree, and while we're at it also change the settings.py template to 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.
On Thu, Jun 10, 2010 at 11:21 AM, Andrew Godwin <and...@aeracode.org> wrote: > 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.
> 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.
On Fri, Jun 11, 2010 at 10:16 AM, Andrew Godwin <and...@aeracode.org> wrote: >> 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.
On Fri, Jun 11, 2010 at 9:16 AM, Andrew Godwin <and...@aeracode.org> wrote:
> 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.
> 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.
Speaking as someone who got up to speed on both Django and python in the last year or so, I'd have loved to have been pointed to virtualenv, pip and the stack early on in the learning process. I will say that I am an experienced developer, so I was used to these kinds of technologies and wanting them as I went through, so I'm not a good reference point as a total newb. I took a roundabout route, but I got there eventually.
-----Original Message----- From: django-developers@googlegroups.com [mailto:django-developers@googlegroups.com] On Behalf Of Andrew Godwin Sent: Friday, June 11, 2010 9:11 AM To: django-developers@googlegroups.com Subject: Re: Imports in the tutorial
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.
On Fri, Jun 11, 2010 at 1:21 AM, Andrew Godwin <and...@aeracode.org> wrote: > 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.
> 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).
On Saturday, June 12, 2010, Andrew Godwin <and...@aeracode.org> wrote:
> 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.
> 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.
This topic came up in discussion today and Peter pointed us here.
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
.
On Jun 12, 7:34 am, Andrew Godwin <and...@aeracode.org> 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.
> 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.
