Starting new project -- version 1.10

[Rich Shepard]

I'm working my way through the tutorial and creating the application I
want rather than the articles example. I've become stuck between two
sections of the tutorial.

Creating the project (section 2.3.1 worked fine from the TLD,
~/development/:

django-admin startproject crm

created ~/development/crm/ containing the files it should (page 14).

Moving to section 2.3.2 I start the runserver and, sure enough, I can see
the web page it created.

The problem occurs in section 2.3.3 when I try to create the crm
application. I cannot do this while the development server is running; there
is no system or python prompt. When I kill the running development server
(^C), and issue the command
python3 manage.py startapp crm

I'm told that application already exists:
~/development/crm]$ python3 manage.py startapp crm
CommandError: 'crm' conflicts with the name of an existing Python module and
cannot be used as an app name. Please try another name.
but I have no idea where django thinks it exists.

Not all the files are found:
~/development/crm/crm]$ ls
__init__.py __pycache__/ settings.py urls.py wsgi.py

These were created by the startproject command.

Now knowing how I dug this hole I'm in I'd appreciate your teaching me how
to get out of the hole and move on.

Rich

[Tim Graham]

Don't use the same name for your app and project. When you "startproject crm", the project settings.py, urls.py, and wsgi.py are placed in a module named "crm" so you can't use the same name for an app.

[Rich Shepard]

On Fri, 19 Aug 2016, Tim Graham wrote:

> Don't use the same name for your app and project. When you "startproject
> crm", the project settings.py, urls.py, and wsgi.py are placed in a module
> named "crm" so you can't use the same name for an app.

Tim,

I read that but overlooked the implications.

Thanks very much,

Rich

[Michal Petrucha]

Hi Rich,

Just to add to what Tim wrote, there's no reason why you couldn't use
the crm package created by startproject as an “app”, too – all you
have to do is create a models.py file in there (next to the existing
urls.py, if you need any models), views.py (if you need views), and
add 'crm' to ``INSTALLED_APPS``. That's pretty much the same thing as
what startapp would have done, anyway.

Good luck,

Michal

[Rich Shepard]

On Mon, 22 Aug 2016, Michal Petrucha wrote:

> Just to add to what Tim wrote, there's no reason why you couldn't use the
> crm package created by startproject as an “app”, too – all you have to do
> is create a models.py file in there (next to the existing urls.py, if you
> need any models), views.py (if you need views), and add 'crm' to
> ``INSTALLED_APPS``. That's pretty much the same thing as what startapp
> would have done, anyway.

Michal,

Thanks for the insight.

Seems to me that models and views are essential to a django application.
Regardless, I saw why startapp failed: I overlooked the requirement to
create a postgres database from the commandline prior to asking django to
use it.

INSTALLED_APPS now has 'crm' at the end of the django.contrib.* list.

One clarification on projects vs applications will help my learning.
Rather than using the same name for both (based on prior advice), the
project name is clientmanagment and that directory contains
clientmanagement/ crm/ manage.py*

The clientmanagement/ subdirectory contains
__init__.py __pycache__/ settings.pyc wsgi.py
__init__.pyc settings.py urls.py

and I wonder why the project-related files in this subdirectory are not
under the parent project directory. In other words, why is there a project
subdirectory under the project directory?

Thanks,

Rich

[Michal Petrucha]

On Mon, Aug 22, 2016 at 07:48:44AM -0700, Rich Shepard wrote:
> One clarification on projects vs applications will help my learning.
> Rather than using the same name for both (based on prior advice), the
> project name is clientmanagment and that directory contains
> clientmanagement/ crm/ manage.py*
>
> The clientmanagement/ subdirectory contains
> __init__.py __pycache__/ settings.pyc wsgi.py
> __init__.pyc settings.py urls.py
>
> and I wonder why the project-related files in this subdirectory are not
> under the parent project directory. In other words, why is there a project
> subdirectory under the project directory?

This is mostly an issue with how we name things. You have a project,
which is a CRM application. That's the entire thing, which consists of
a bunch of different Python packages. So, each of the subdirectories
in the top-level “clientmanagement” directory is one Python package.
For better or for worse, Python packages containing Django models,
views, URL patterns, and whatnot, are referred to as “Django apps”.

So you have a project named “clientmanagement”, which contains two
Python packages (in other words Django apps), called “crm”, and
“clientmanagement”.

Usually, it's a good practice to split your project into smaller
self-contained packages. Those all live together inside the project
directory, and each of them can have its own URL patterns, models,
views, static files, templates, and pretty much anything else. They
can even depend on each other, although it's often a good idea to keep
the coupling between as low as possible.

Finally, you need one Python package that serves as the “app” that
glues all the other packages together. This is the package (or app)
that contains the settings module, the root URL configuration, the
WSGI entry point, and often also static files, templates, views and
other stuff that only make sense in the context of the project itself,
and cannot reasonably be spun out into a separate package (that would
be things like the base template, or sometimes the landing page view).
This is what you referred to as the “project-under-the-project”.

The reason why this is inside a separate subdirectory is that you want
Python to be able to import it. In theory, you could just put
everything one level higher (and, in fact, that used to be the default
layout created by startproject until a few years ago), but it's
troublesome in practice, because with such layout, all of those files
end up in the global Python import namespace, which can easily lead to
conflicts.

As a final note, if your entire project is really small, and only does
one single thing, it's not entirely unreasonable to use a single
Python package (Django app) for everything – if there are no more than
a couple-three models in the entire project, and just a handful of
views and forms, I just stuff everything into the single package
created by startproject.

I hope this explanation makes sense, and feel free to ask if there's
anything unclear.

Cheers,

Michal

[Carsten Fuchs]

Am 23.08.2016 um 14:11 schrieb Michal Petrucha:
> Finally, you need one Python package that serves as the “app” that
> glues all the other packages together. This is the package (or app)
> that contains the settings module, the root URL configuration, the
> WSGI entry point, and often also static files, templates, views and
> other stuff that only make sense in the context of the project itself,
> and cannot reasonably be spun out into a separate package (that would
> be things like the base template, or sometimes the landing page view).
> This is what you referred to as the “project-under-the-project”.
>
> The reason why this is inside a separate subdirectory is that you want
> Python to be able to import it.

I cannot remember where is was stated, but iirc another reason for the
“project-under-the-project” subdirectory was that it is considered not as app,
but rather as “site”.

That is, if you deployed the same project in a different context (with different
configuration), you would have another such “site” directory, e.g.
clientmanagement/clientmanagement-internal/ or
clientmanagement/test-other-webserver/ etc.

Best regards,
Carsten

[Rich Shepard]

On Tue, 23 Aug 2016, Carsten Fuchs wrote:

> I cannot remember where is was stated, but iirc another reason for the
> “project-under-the-project” subdirectory was that it is considered not as
> app, but rather as “site”.

Carsten,

Thanks for the clarification. That helps.

Rich

[Rich Shepard]

On Tue, 23 Aug 2016, Michal Petrucha wrote:

> This is mostly an issue with how we name things. You have a project, which
> is a CRM application. That's the entire thing, which consists of a bunch
> of different Python packages. So, each of the subdirectories in the
> top-level “clientmanagement” directory is one Python package. For better
> or for worse, Python packages containing Django models, views, URL
> patterns, and whatnot, are referred to as “Django apps”.

Michal,

Yesterday evening I started reading a book I bought several years ago
(when django was at version 1.5) for a project that got sidelined. With your
explanation and the book I'm starting to understand the django terminology
and project organization.

> Usually, it's a good practice to split your project into smaller
> self-contained packages. Those all live together inside the project
> directory, and each of them can have its own URL patterns, models, views,
> static files, templates, and pretty much anything else. They can even
> depend on each other, although it's often a good idea to keep the coupling
> between as low as possible.

Let me test my understanding by explaining my crm project. Getting it
right from the beginning will help me a lot.

First, this is a single-user project for my business; I'm not a
professional application developer but have built scientific and business
tools for my use for several decades. Since this, and the other django
application that has been put off for a while, are the only two that I plan
to develop I am not convinced that I need virtualenv and its wrapper. Each
will use python3 and I'll keep django upgraded to the latest version.

Second, now that I better understand the project/app design and disk
layout I'll rename some directories so the distinctions are clearer. Which
leads to my question about apps in a project.

Yesterday, in models.py, I set up the schema based on what I want. The crm
has several components: companies, contacts, activities, opportunities, etc.
Each of these is a single class within models.py. My question is whether
each should be a separate app since there will be methods for adding,
modifying, and deleting rows in the database tables as well as report
generation and views that incorporate data from multiple tables. If so, is
each named as a distinct python module and imported into the main models.py?

Or, should they all remain in models.py with separate modules for adding,
editing, deleting, and reporting that are imported to models.py?

My python2/wxPython applications have an organization that makes sense to
me and works. Since building a browser-based django application is a new
experience I want to learn how best to organize everything.

Thanks for the insights,

Rich