Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#22639 closed Cleanup/optimization (fixed)

Fix inconsistency with imports in documentation

Reported by: niclas.ahden Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Tim Graham, Daniele Procida, tibidat Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


We've noticed that imports are not always included in code snippets which means that snippets are not always safe to copy and paste. It's fine to not have them copy-paste safe, but it should be consistent.

For example
The tutorial includes imports in all of the snippets (eg. "from django.contrib import admin"). Except for at the very bottom where the imports are skipped.

This section has two snippets: one with imports and one without.

The imports for this snippet are quite far away in a previous section.

TL;DR should all code snippets be safe to copy and paste?

Change History (7)

comment:1 Changed 10 years ago by Tim Graham

I don't mind the current state of things. There was a couple of patches a while back that added a lot of imports, e.g. 1fe587d80bfcf062a94252fb532c8ac035c833b9 08b501e7d314e9c45dd51d3ba27b2ecb0287df3b 1d543949d7acc93a172e8a2c9272d8b983a421ef.

The first time a concept is introduced in a section, it probably makes sense to include all imports, but if the example is tweaked later, I don't think the imports need to be repeated.

If there are spots that bother you right now, feel free to send a PR. Otherwise, I don't think we need to keep a ticket open for this.

We'll never be able to make all code snippets safe to copy and paste because examples have example dependencies like from myapp.models import Article.

comment:2 Changed 10 years ago by niclas.ahden

Before your comment we had a short discussion with bmispelon about this and agreed that adding a brief guideline to the contributor documentation would be good. The general rule being that snippets should preferably be safe to copy and paste.

What do you think?

Version 0, edited 10 years ago by niclas.ahden (next)

comment:3 Changed 10 years ago by Tim Graham

Sure, we could use dot imports. I guess it would be good to encourage that.

I don't think it's true that snippets should be safe to copy and paste. We use ... in a lot of places where, for example purposes, the contents of a function don't matter. Adding the rest of the method body or whatever the ellipses are replacing is just going to obfuscate the purpose of the example. For example:

from django.forms.models import BaseInlineFormSet

class CustomInlineFormSet(BaseInlineFormSet):
    def clean(self):
        super(CustomInlineFormSet, self).clean()
        # example custom validation across forms in the formset
        for form in self.forms:
            # your custom formset validation

comment:4 Changed 10 years ago by Tim Graham

Triage Stage: UnreviewedAccepted

comment:5 Changed 10 years ago by Niclas Åhdén <niclas@…>

Resolution: fixed
Status: newclosed

In 64ee097b3b33716b10837644f9e18b87f25d606e:

Fixed #22639 -- Added missing imports in docs

Added ModelForm and NON_FIELD_ERRORS imports.

comment:6 Changed 10 years ago by Tim Graham <timograham@…>

In aa9a146a69655849d588da7eba4a71a2ea4b6361:

[1.7.x] Fixed #22639 -- Added missing imports in docs

Added ModelForm and NON_FIELD_ERRORS imports.

Backport of 64ee097b3b from master

comment:7 Changed 10 years ago by niclas.ahden

After a brief discussion on IRC we agreed that a rough guideline is:

  • Include all imports the first time that a concept is introduced in a section. If the example is tweaked within the section the imports should not be repeated.

An example where that wasn't true:

Which benefitted from importing ModelForm since it's included in the section above and below.

PR: (also includes the missing NON_FIELD_ERRORS import in the same snippet)

Similar occurrences will be handled in their own tickets.

Thank you Tim!

Note: See TracTickets for help on using tickets.
Back to Top