[Django] #23860: Document the preferred imports order
Django
-------------------------------+--------------------
Reporter: wrwrwr | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
I think it would be nice to have the (soft?) convention on imports order
documented. It's said that Django has one, but I've recently spent some
time trying to figure out what it is and couldn't find any precise info or
get a consistent view based on the source.
[https://www.python.org/dev/peps/pep-0008#imports PEP 8] only asks to put
imports on separate lines at the top of the file, guides to make "standard
library", "related" and "local" groups, recommends absolute imports
(unless dealing with complex package layouts), and discourages the use of
"*" in most cases.
A short example on the
[https://docs.djangoproject.com/en/dev/internals/contributing/writing-code
/coding-style/ coding style] page would be enough. Things to mention:
* alphabetical order for modules, classes and objects (within groups);
* modules before classes, other objects after classes?
* "import" before "from ... import"?
* line breaking of lengthy imports.
Some conventions from other projects: [http://google-
styleguide.googlecode.com/svn/trunk/pyguide.html#Imports_formatting
Google], [https://github.com/reddit/reddit/wiki/PythonImportGuidelines
reddit], [http://docs.openstack.org/developer/hacking/#real-world-import-
order-examples OpenStack],
[http://docs.plone.org/external/plone.api/docs/contribute/conventions.html
#about-imports Plone].
--
Ticket URL: <https://code.djangoproject.com/ticket/23860>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: wrwrwr | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by aaugustin):
* needs_better_patch: => 0
* needs_docs: => 0
* needs_tests: => 0
* stage: Unreviewed => Accepted
Comment:
Yes, whatever convention is chosen, it would be good to have on for new or
refactored code.
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:1>
Django
Reporter: wrwrwr | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by wrwrwr):
Here's a [https://github.com/wrwrwr/django/compare/ticket_23860
preliminary docs addition] with an example chosen to demonstrate what
there is to consider. Some highlights: -- blank line after `__future__`?
-- not grouping imported objects? -- ignore case within words?
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:2>
Django
Reporter: wrwrwr | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by carljm):
Replying to [comment:2 wrwrwr]:
> Here's a [https://github.com/wrwrwr/django/compare/ticket_23860
preliminary docs addition] with an example chosen to demonstrate what
there is to consider. Some highlights: -- blank line after `__future__`?
-- not grouping imported objects? -- ignore case within words?
If you create a pull-request, that would allow in-line comments.
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:3>
Django
Reporter: wrwrwr | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by wrwrwr):
Here's a [https://github.com/django/django/pull/3566 pull request] for
more convenient discussion.
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:4>
Django
Reporter: wrwrwr | Owner: nobody
Type: New feature | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Ready for
Has patch: 0 | checkin
Needs tests: 0 | Needs documentation: 0
Easy pickings: 0 | Patch needs improvement: 0
| UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by carljm):
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:5>
Django
Reporter: wrwrwr | Owner: timgraham
Type: New feature | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* owner: nobody => timgraham
* needs_better_patch: 0 => 1
* has_patch: 0 => 1
* status: new => assigned
* stage: Ready for checkin => Accepted
Comment:
As I mentioned on the mailing list, I'd like to take a look at
[https://pypi.python.org/pypi/isort isort] and see if it'll work for us so
we can automate this and not have to think about it very much.
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:6>
Django
Reporter: wrwrwr | Owner: timgraham
Type: New feature | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Comment (by wrwrwr):
Good idea. I've been playing with `isort` a bit and prepared some `flake8`
/ `isort` [https://github.com/wrwrwr/django/compare/feature/git-hooks pre-
commit hooks] for those on the other side of the looking-glass. Maybe
you'll find the
[https://github.com/wrwrwr/django/commit/702be04564d107673c7dee2e116292f612761c03
isort config] useful. The convention would need some amending to make it
work: -- putting "import" before "from" statements, -- choosing a slightly
different line breaking style, -- sorting objects into constants, classes,
modules & other objects (case based).
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:7>
Django
Reporter: wrwrwr | Owner: timgraham
Type: New feature | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Comment (by Tim Graham <timograham@…>):
In [changeset:"0ed7d155635da9f79d4dd67e4889087d3673c6da"]:
{{{
#!CommitTicketReference repository=""
revision="0ed7d155635da9f79d4dd67e4889087d3673c6da"
Sorted imports with isort; refs #23860.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:8>
Django
Reporter: wrwrwr | Owner: timgraham
Type: New feature | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* needs_better_patch: 1 => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:9>
Django
Reporter: wrwrwr | Owner: timgraham
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"cd155c7c7160f5178833593713727f013d3ed36d"]:
{{{
#!CommitTicketReference repository=""
revision="cd155c7c7160f5178833593713727f013d3ed36d"
Fixed #23860 -- Documented import order convention.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:10>
Django
Reporter: wrwrwr | Owner: timgraham
Type: New feature | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"a8b70d251d238b4e6cfc7bb4296da15494f8dff3"]:
{{{
#!CommitTicketReference repository=""
revision="a8b70d251d238b4e6cfc7bb4296da15494f8dff3"
[1.8.x] Sorted imports with isort; refs #23860.
Backport of 0ed7d155635da9f79d4dd67e4889087d3673c6da from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/23860#comment:11>