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-. 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/

-- 
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+unsubscr...@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/20161207103930.4idy6pqh3i2iw2xa%40home.ouaza.com.
For more options, visit https://groups.google.com/d/optout.

Re: Guidelines to name python modules of Django applications?

[Aymeric Augustin]

Hello Raphael,

> On 7 Dec 2016, at 11:39, Raphael Hertzog  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
".apps.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.

-- 
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+unsubscr...@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/19E4A2A8-E152-446B-9938-007CF317033B%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.

Re: Guidelines to name python modules of Django applications?

[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.

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

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

-- 
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+unsubscr...@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/20161207115211.vzjefmdxpn4db2k4%40home.ouaza.com.
For more options, visit https://groups.google.com/d/optout.

Re: Guidelines to name python modules of Django applications?

[Aymeric Augustin]

> On 7 Dec 2016, at 12:52, Raphael Hertzog  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.

-- 
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+unsubscr...@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/29427EC1-5751-46AA-99A6-6FB87D94BB25%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.

Good morning Django team!

[Adonys Alea Boffill]

I have a ticket #26543  ready
for make the last review a week ago, I added the pull-request
 to the ticket. I know you have
a lot of task to complete, this email is only to make a reminder.
Thanks in advance and good day for every members!!!
Adonys

-- 
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+unsubscr...@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/CAMwFES-ActOg6EobrW-22fWkXQRrn4VH0cOo2p84USvCcVavsg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: Good morning Django team!

[Tim Graham]

Hi Adonys,

If you want to help out, you can look at the "Patches needing review" queue 
(currently 28 issues) at https://dashboard.djangoproject.com/ and help to 
review those patches using the patch review checklist [0]. Reviewing 
patches isn't a task limited to members of the Django team. Anyone from the 
community is welcome to review patches and mark the ticket as "patch needs 
improvement" or "ready for checkin" as appropriate.

Thanks!

[0] 
https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/submitting-patches/#patch-review-checklist

On Wednesday, December 7, 2016 at 9:52:04 AM UTC-5, Adonys Alea Boffill 
wrote:
>
> I have a ticket #26543  ready 
> for make the last review a week ago, I added the pull-request 
>  to the ticket. I know you 
> have a lot of task to complete, this email is only to make a reminder.
> Thanks in advance and good day for every members!!!
> Adonys
>

-- 
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+unsubscr...@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/36eb908b-d683-4fe9-9da2-a0993de58161%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Guidelines to name python modules of Django applications?

[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

-- 
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+unsubscr...@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.

Re: Guidelines to name python modules of Django applications?

[Marc Tamlyn]

What Aymeric and Florian sayid.

On 7 December 2016 at 15:58, Florian Apolloner 
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-developers+unsubscr...@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.
>

-- 
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+unsubscr...@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/CAMwjO1Goo0er0UfRVWe3P0vbdPdJZxzzV8L50PjrRvFi0R8gYA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: Template-based widget rendering

[Tim Graham]

This scheme seems to be working well so far.

One thing you may not have thought of is that switching 
to JinjaTemplateRenderer is incompatible with the admin because jinja2 
templates aren't provided for those widgets. I think the reasoning was that 
they're complicated to convert due to the use of the i18n and static 
template tags and (under the old rendering scheme) a DjangoTemplates 
backend had to be available anyway for rendering the main admin templates. 
So I think JinjaTemplateRenderer may not be that useful in practice as it 
requires your project and all its third-party apps to provide Jinja2 
templates for all widgets.

I used these steps to use Jinja2 and allow the admin to continue using 
DjangoTemplates:
1. Prepend this to the default settings.TEMPLATES:
 {
'BACKEND': 'django.template.backends.jinja2.Jinja2',
'APP_DIRS': True,
}
2. Add 'django.forms' to INSTALLED_APPS.
3. Add settings.FORM_RENDERER = 
'django.forms.renderers.templates.ProjectTemplateRenderer'

On Saturday, December 3, 2016 at 12:41:13 PM UTC-5, Preston Timmons wrote:
>
> Carl,
>
> The default renderer is backwards-compatible with no settings changes, 
>> and does not require Jinja2, but it still allows overrides/additions of 
>> widget templates. It's also standalone-compatible, in that it is 
>> self-contained and has no dependency on TEMPLATES config. 
>
>
> I like this idea. It's explicit and predictable. A lot simpler than our 
> current approach.
>
> Preston
>

-- 
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+unsubscr...@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/6fd84f7b-3f8a-474d-bc9f-50919d21b5dd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Template-based widget rendering

[Carl Meyer]

Hi Tim,

On 12/07/2016 08:41 AM, Tim Graham wrote:
> This scheme seems to be working well so far.

Great, thanks for working on implementation. I did have intentions of
putting together the implementation once I'd gotten your feedback on the
design, but I won't complain if you've already done it :-)

> One thing you may not have thought of is that switching
> to JinjaTemplateRenderer is incompatible with the admin because jinja2
> templates aren't provided for those widgets. I think the reasoning was
> that they're complicated to convert due to the use of the i18n and
> static template tags and (under the old rendering scheme) a
> DjangoTemplates backend had to be available anyway for rendering the
> main admin templates. So I think JinjaTemplateRenderer may not be that
> useful in practice as it requires your project and all its third-party
> apps to provide Jinja2 templates for all widgets.
> 
> I used these steps to use Jinja2 and allow the admin to continue using
> DjangoTemplates:
> 1. Prepend this to the default settings.TEMPLATES:
>  {
> 'BACKEND': 'django.template.backends.jinja2.Jinja2',
> 'APP_DIRS': True,
> }
> 2. Add 'django.forms' to INSTALLED_APPS.
> 3. Add settings.FORM_RENDERER =
> 'django.forms.renderers.templates.ProjectTemplateRenderer'

Makes sense. I still think we may as well provide JinjaTemplateRenderer,
for completeness, and because not all projects use the admin. But the
docs should be clear about the limitations, and point to
ProjectTemplateRenderer for more flexible setups.

Let me know once you have a PR that you feel is ready for review, happy
to review it.

Carl

-- 
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+unsubscr...@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/6768a102-edc7-ae69-ceec-32aab4beedbb%40oddbird.net.
For more options, visit https://groups.google.com/d/optout.


signature.asc
Description: OpenPGP digital signature

Re: Guidelines to name python modules of Django applications?

[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  > 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.
>> 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.
>>
>
>

-- 
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+unsubscr...@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.