Guidelines to name python modules of Django applications?

[Raphael Hertzog]

Hello,

in Debian we recently had a discussion about the package name we use for
Django applications/extensions, it's usually python-django-<foo>. But the
generic naming policy we have for all Python modules implies that this
package would provide a "django_foo" Python module and this is not always
the case.

That said we do believe that it is a sort of best-practice and that
as such it should be documented somewhere in the Django documentation.

See the thread on the Debian side here:
https://lists.debian.org/debian-python/2016/11/threads.html#00082

In general, the python module name should match the name on pypi
(except for conversion between "-" and "_") and it should be prefixed with
"django_" to make it clear that this module is for use within the Django
framework.

Would you agree to add this recommendation somewhere in the official
Django doc?

Looking at https://docs.djangoproject.com/en/1.10/intro/reusable-apps/
it already recommends a "django-" prefix, so the only missing
recommendation is really that the "polls" module should be renamed into
"django_polls" when included in a PyPi package to avoid namespace
pollution and have a direct match between the package name and the module
name.

Cheers,
--
Raphaël Hertzog ◈ Writer/Consultant ◈ Debian Developer

Discover the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/

[Aymeric Augustin]

Hello Raphael,

On 7 Dec 2016, at 11:39, Raphael Hertzog <rap...@ouaza.com> wrote:

Would you agree to add this recommendation somewhere in the official
Django doc? 

In my experience:

- many Django-related packages use a django- prefix in the name of the package

  on PyPI

- very few use a django_ prefix in the name of the Python module, because this

  module can only be used in the context of Django and the longer name makes

  imports less readable

For example here’s a typical INSTALLED_APPS settings:

INSTALLED_APPS = [

    # redacted project-specific apps…

    'allauth',                      # provides templates and translations

    'allauth.account',              # provides email-related models

    'allauth.socialaccount',        # provides social-related models

    'allauth.socialaccount.providers.facebook',

    'allauth.socialaccount.providers.google',

    'allauth.socialaccount.providers.linkedin_oauth2',

    'allauth.socialaccount.providers.twitter',

    'django_rq',

    'django_s3_storage',

    'impersonate',

    'localflavor',

    'modelcluster',                 # required by wagtail

    'overextends',                  # to customize wagtail

    'phonenumber_field',

    'raven.contrib.django.raven_compat',

    'rest_framework',

    'sequences.apps.SequencesConfig',

    'taggit',                       # required by wagtail

    'waffle',

    # Work around https://github.com/torchbox/wagtail/issues/1824

    'wagtail.contrib.wagtailsearchpromotions',

    'wagtail.contrib.wagtailstyleguide',

    'wagtail.wagtailadmin',

    'wagtail.wagtailcore',

    'wagtail.wagtaildocs',

    'wagtail.wagtailembeds',

    'wagtail.wagtailforms',

    'wagtail.wagtailimages',

    'wagtail.wagtailredirects',

    'wagtail.wagtailsearch',

    'wagtail.wagtailsites',

    'wagtail.wagtailsnippets',

    'wagtail.wagtailusers',

    'webpack_loader',

    'whitenoise.runserver_nostatic',    # before django.contrib.staticfiles

    'django.contrib.admin',

    'django.contrib.auth',

    'django.contrib.contenttypes',

    'django.contrib.messages',

    'django.contrib.postgres',

    'django.contrib.sessions',

    'django.contrib.sites',

    'django.contrib.staticfiles',

]

Two packages follow your idea: django_rq and django_s3_storage.

django_rq is called like that because rq exists independently of Django and

django_rq is a separate project.

django_s3_storage could be called s3_storage. This may be an oversight or a

choice of the maintainer. It's an isolated case though.

Considering the backwards-compatibility issues — if you change a package name

all imports needs updating — I don’t think it’s realistic to go against the

established practice of the ecosystem at this point, and for this reason I'm

not in favor of making that recommandation.

Since changes I made in 1.7, the documentation recommends to use the

"<app_label>.apps.<AppName>Config" convention in INSTALLED_APPS. We're at

1.10, and as you can see in the example above, this isn't a resounding

success... The only app using that convention in the list is one I wrote.

I believe recommending a django_ prefix would be even less successful.

To sum up, I’m afraid that your suggestion priorizes the needs of packagers

over those of developers and, unfortunately for you, developers are the

heavier users there.

Best regards,

-- 

Aymeric.

[Raphael Hertzog]

Le mercredi 07 décembre 2016, Aymeric Augustin a écrit :
> In my experience:
>
> - many Django-related packages use a django- prefix in the name of the package
> on PyPI

And the mismatch between package name and module name means that we have
many packages which are not co-installable because they use the same
python module name.

At least using a matching package/module name means that those conflicts
are detected when you try to submit your package.

Here's a concrete example found in a few seconds:
https://pypi.python.org/pypi/cep/0.1.1
https://pypi.python.org/pypi/django-cep/1.1.2

> - very few use a django_ prefix in the name of the Python module, because this
> module can only be used in the context of Django and the longer name makes
> imports less readable

It's hard to know the reason. Maybe they do because they follow the
documentation to the letter?

I agree with your assessment of the current situation. A majority of
packages do not follow this recommendation, but a non-trivial part
of the packages do follow it correctly. I have seen many examples in
Debian and it's easy to find many more on PyPi.

> Considering the backwards-compatibility issues — if you change a package name
> all imports needs updating — I don’t think it’s realistic to go against the
> established practice of the ecosystem at this point, and for this reason I'm
> not in favor of making that recommandation.

I'm not asking to rename existing modules, I'm just asking to update
the recommendation in the documentation so that new Django applications do
follow the best practice that avoid namespace conflicts and namespace
pollution.

While the mismatch affects the majority of Django packages, and it's
an established practice for some Django developers, I don't see how
making this recommendation goes against anything. It's not like
we will break anything by making this recommendation.

> To sum up, I’m afraid that your suggestion priorizes the needs of packagers
> over those of developers and, unfortunately for you, developers are the
> heavier users there.

I don't think that developers have much to loose here and as you know,
developers and packagers work hand in hand pretty well.

[Aymeric Augustin]

> On 7 Dec 2016, at 12:52, Raphael Hertzog <rap...@ouaza.com> wrote:
>
> And the mismatch between package name and module name means that we have
> many packages which are not co-installable because they use the same
> python module name.

Yes that’s an issue. While it isn't specific to Django, the current practice
make such problems somewhat more likely for Django apps.

Surely the Python Packaging Authority has some thoughts on this problem?

> At least using a matching package/module name means that those conflicts
> are detected when you try to submit your package.

Indeed. I suppose Debian also checks for packages that try to install the same
files, but that happens further down the line and needs manual work to resolve
i.e. declare packages as conflicting?

> While the mismatch affects the majority of Django packages, and it's
> an established practice for some Django developers, I don't see how
> making this recommendation goes against anything. It's not like
> we will break anything by making this recommendation.

At least we could describe this problem to help developers of pluggable apps
make an informed decision there.

I still think I wouldn't use a django_ prefix when I create new apps because
it adds a small but pervasive overhead to prevent conflicts that aren't common
in practice.

> I don't think that developers have much to loose here.

Well, 7 characters on every import statement, which needs to fit in a 79
characters line. It may seem small but these small things add up.

> and as you know,
> developers and packagers work hand in hand pretty well.

Yes!

--
Aymeric.

[Florian Apolloner]

On Wednesday, December 7, 2016 at 1:10:48 PM UTC+1, Aymeric Augustin wrote:

I still think I wouldn't use a django_ prefix when I create new apps because
it adds a small but pervasive overhead to prevent conflicts that aren't common
in practice.

Same here, I am certainly against making that a recommendation from/in Django itself.

Cheers,
Florian

[Marc Tamlyn]

What Aymeric and Florian sayid.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscribe@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/ba0114d9-0baa-4662-8fff-f7c9b03b90d3%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Robert Roskam]

+1

On Wednesday, December 7, 2016 at 11:25:05 AM UTC-5, Marc Tamlyn wrote:

What Aymeric and Florian sayid.

On 7 December 2016 at 15:58, Florian Apolloner <f.apo...@gmail.com> wrote:

On Wednesday, December 7, 2016 at 1:10:48 PM UTC+1, Aymeric Augustin wrote:

I still think I wouldn't use a django_ prefix when I create new apps because
it adds a small but pervasive overhead to prevent conflicts that aren't common
in practice.

Same here, I am certainly against making that a recommendation from/in Django itself.

Cheers,
Florian

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.

To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.

Visit this group at https://groups.google.com/group/django-developers.

[Adam Johnson]

+1 (to what Aymeric and Florian said)

To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscribe@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.

Visit this group at https://groups.google.com/group/django-developers.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/b6258a98-2f7e-4617-bb44-e7bc14952327%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Adam

[Michael Manfre]

As some one who maintains django packages, I wouldn't use "django_" and don't think it should be an official recommendation. I do support documenting the potential collisions to let package maintainers make a more informed decision.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/b6258a98-2f7e-4617-bb44-e7bc14952327%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Adam

--

You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.

To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/CAMyDDM1jBb50Rw74sEP8Ot7ykTDop7pn8Xr6kZw4uqgJmzot3Q%40mail.gmail.com.

[Raphaël Barrois]

If I understand correctly the input, would the following proposal be an acceptable middle ground?

Replace:
> It’s often useful to prepend django- to your module name when creating a package to distribute. This helps others
> looking for Django apps identify your app as Django specific

With:
> It's often useful to use the "Framework :: Django" setup.py classifiers when creating a package to distribute.
> This helps others looking for Django apps identify your app as Django specific.
>
> On a related note, using a different name between your PyPI package and the actual module to import increases the risk
> of namespace collisions: if your package is called "django_foo" but imported as "foo", it might conflict with a
> package named "foo". If possible, use the same name for the "module to import" and the "packaged application".


I also think that the current tutorial is slightly confusing for newcomers: it suggests to use different names for the
package and the module — a distinction which might not be quite beginner-friendly.


--
Raphaël

> > <https://groups.google.com/d/msgid/django-developers/ba0114d9-0baa-4662-8fff-f7c9b03b90d3%40googlegroups.com?utm_medium=email&utm_source=footer>
> > .

> >
> > For more options, visit https://groups.google.com/d/optout.
> >
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "Django developers (Contributions to Django itself)" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email to django-develop...@googlegroups.com.
> > To post to this group, send email to django-d...@googlegroups.com.
> > Visit this group at https://groups.google.com/group/django-developers.
> > To view this discussion on the web visit
> > https://groups.google.com/d/msgid/django-developers/b6258a98-2f7e-4617-bb44-e7bc14952327%40googlegroups.com

> > <https://groups.google.com/d/msgid/django-developers/b6258a98-2f7e-4617-bb44-e7bc14952327%40googlegroups.com?utm_medium=email&utm_source=footer>
> > .

> >
> > For more options, visit https://groups.google.com/d/optout.
> >
> >
> >
> >
> > --
> > Adam
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "Django developers (Contributions to Django itself)" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email to django-develop...@googlegroups.com.
> > To post to this group, send email to django-d...@googlegroups.com.
> > Visit this group at https://groups.google.com/group/django-developers.
> > To view this discussion on the web visit
> > https://groups.google.com/d/msgid/django-developers/CAMyDDM1jBb50Rw74sEP8Ot7ykTDop7pn8Xr6kZw4uqgJmzot3Q%40mail.gmail.com

> > <https://groups.google.com/d/msgid/django-developers/CAMyDDM1jBb50Rw74sEP8Ot7ykTDop7pn8Xr6kZw4uqgJmzot3Q%40mail.gmail.com?utm_medium=email&utm_source=footer>
> > .

[Raphael Hertzog]

Le jeudi 08 décembre 2016, Raphaël Barrois a écrit :
> If I understand correctly the input, would the following proposal be an acceptable middle ground?

It would certainly be an improvement from my point of view, yes.