How should I format a long url in a python comment and still be PEP8 compliant

Question

In a block comment, I want to reference a URL that is over 80 characters long.

What is the preferred convention for displaying this URL?

I know bit.ly is an option, but the URL itself is descriptive. Shortening it and then having a nested comment describing the shortened URL seems like a crappy solution.

score 91 · Accepted Answer · edited May 11 '23 at 19:48

91

Don't break the url:

Some other good reasons to ignore a particular guideline:

When applying the guideline would make the code less readable, even for someone who is used to reading code that follows this PEP. ...

Source:

# A Foolish Consistency is the Hobgoblin of Little Minds [1]
# [1]: http://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds

You can use the # noqa at the end of the line to stop PEP8/pycodestyle/Flake8 from running that check. Should also avoid warnings in your IDE.

# [1]: http://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds # noqa

edited May 11 '23 at 19:48

Julian Obrecht

3
3

answered May 24 '12 at 14:56

jfs

399,953
195
994
1,670

Can't understand why this is upvoted so many times. Doesn't work for me. – Dmitrii Sorin Nov 02 '16 at 09:50
1

@DmitrySorin: if "don't break the url" is unclear; follow the link in the answer. Or if you can't open the url; read the direct quote from it in [@Christian Witts' answer](http://stackoverflow.com/a/10739989/4279). – jfs Nov 02 '16 at 09:56
7

I agree; however, PyCharm does not make it easy to ignore (without litering your code with ugly '# noinspection LongLine' (and similar) references all over the place. I think the bigger problem is that the RST format has the limitation of not being able to have a line break (that is not displayed) within the URL. – Feb 20 '17 at 20:25
11

The answer doesn't answer how to be compliant, so if you have a linter, it remains with warnings. – Efren Feb 13 '18 at 06:47
@Efren how to suppress a linter depends on the linter. – jfs Feb 13 '18 at 06:49
@jfs OP asked how to make it compliant, this answer does not make a URL compliant – Efren Feb 13 '18 at 06:50
1

@Efren It seems you've missed the point. Read PEP-8 (in particular, the part from the link in the answer). Your linker is not pep-8 compliant if it doesn't allow to suppress warnings when it is justified. – jfs Feb 13 '18 at 07:17
@jfs I read the link, this last comment you put seems a more suitable answer: "It can not be made to comply to the rule, so the code needs to silence the warnings" - Just stating to break the rule doesn't make the line compliant, as per the question. The only real world use case of PEP8 is to apply it through linters, so the accepted answer should at least mention that. Leaving linter warnings scattered by breaking a rule only contribute to spending more time reviewing or tending to ignore linters. – Efren Feb 13 '18 at 07:31
1

@Efren your linter is not pep-8. The comment in the answer is PEP-8 compliant. The question is not how to appease your linter (it is relevant of cause but it is not the answer). To avoid the exactly this type of confusion a popular tool was renamed. – jfs Feb 13 '18 at 07:42
7

@jfs so the answer should really be: "a long line is PEP8 compliant in this case" – Efren Feb 13 '18 at 07:48
2

@Efren it is exactly my answer:*"how should I format.. and be pep-8 compliant"* -> "don't break the url" – jfs Feb 13 '18 at 08:17
3

I just discovered **control-click**!! Now THAT'S why you don't want to break a URL in a comment. – Bob Stein Apr 22 '18 at 21:36
@BobStein: in my case (emacs), it is **"o" + letter** to follow a link I'm looking at: [screencast](https://github.com/abo-abo/ace-link#usage) – jfs Feb 16 '20 at 05:52

score 79 · Answer 2 · edited Jun 20 '20 at 09:12

From PEP8

But most importantly: know when to be inconsistent -- sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!

Two good reasons to break a particular rule:

When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules.

Personally, I would use that advice, and rather leave the full descriptive URL in your comment for people.

Sardathrion - against SE abuse · Answer 3 · 2016-02-29T13:04:03.587

59

You can use the # noqa at the end of the line to stop PEP8/Flake8 from running that check. This is allowed by PEP8 via:

Special cases aren't special enough to break the rules.

edited Feb 29 '16 at 13:04

answered Jul 30 '14 at 10:43

Sardathrion - against SE abuse

17,269
27
101
156

3

Elegant. I use pyflakes in Vim and won't commit a change until it returns zero warnings from the agreed upon set of rules (maccabe requirement is looser in our case, but not the 80 lines limit). Shortest way to tell co-workers : I did not split multiline because it makes no sense to do so. – Peter Host Aug 25 '14 at 04:08
4

Thanks @Sardathrion, should have more votes since it actually contributes a practical solution. – ezdazuzena Jan 14 '16 at 11:25
1

In PyCharm `# noqa` is the only way I've found to disable the warning about a long line when it's a comment. Along with several other pesky warnings where `# noinspection` doesn't do the trick. Very helpful. – Bob Stein Aug 28 '21 at 02:03
Just to be clear : should it be `# very_long_url.com noqa` or `# very_long_url.com # noqa`? Pylint seems to ignore them either way, and [apparently requires](https://github.com/PyCQA/pylint/issues/2493) `# pylint: disable=line-too-long # noqa: E501`. – Eric Duminil Mar 22 '23 at 08:21

score 22 · Answer 4 · edited Jun 20 '20 at 09:12

22

I'd say leave it...

PEP20:

Special cases aren't special enough to break the rules.

Although practicality beats purity.

It's more practical to be able to quickly copy/paste an url then to remove linebreaks when pasting into the browser.

edited Jun 20 '20 at 09:12

Community

1
1

answered May 24 '12 at 14:55

mata

67,110
10
163
162

score 21 · Answer 5 · answered Sep 29 '16 at 10:41

21

If your are using flake8:

"""
long-url: http://stackoverflow.com/questions/10739843/how-should-i-format-a-long-url-in-a-python-comment-and-still-be-pep8-compliant
"""  # noqa

answered Sep 29 '16 at 10:41

guyskk

2,468
1
15
13

Edward Spencer · Answer 6 · 2023-03-27T11:20:23.550

1

Adding '# noqa' to the entire docstring works, but it means you lose introspection on the entire docstring, so you could miss other issues.

if you want to narrow your noqa to just the long line you can add it to the long line only, but '# noqa' shows up in the docs when built with sphinx.

In this case, you can build a custom autodoc process method. See this answer.

Here's my adapted version of that,

from sphinx.application import Sphinx
import re

def setup(app):

    noqa_regex = re.compile('^(.*)\s\s#\snoqa.*$')

    def trim_noqa(app, what_, name, obj, options):
        for i, line in enumerate(lines):
            if noqa_regex.match(line):
                new_line = noqa_regex.sub(r'\1', line)
                lines[i] = new_line

    app.connect('autodoc-process-docstring', trim_noqa)
    return app

edited Mar 27 '23 at 11:20

answered Feb 24 '22 at 13:12

Edward Spencer

448
8
10

Are you sure about your claim? https://stackoverflow.com/a/39768096/6419007 – Eric Duminil Mar 22 '23 at 08:23
1

that applies noqa to the entire docstring, however this solution applies noqa only to the long line. If you apply noqa to the entire docstring you would miss other issues. Notice I said if noqa is *in* the docstring. I've edited my response to make this clear. – Edward Spencer Mar 27 '23 at 11:16

score -4 · Answer 7 · answered Apr 08 '13 at 06:42

-4

You use a url shortener like google's so from this:

http://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds

you get:

http://goo.gl/93ZLQ

answered Apr 08 '13 at 06:42

Muhammad Lukman Low

8,177
11
44
54

12

The risk of course is the link shortener disappears and we have no way of knowing the link. ArchiveTeam (led by leadership affiliated with Archive.org) has a whole effort dedicated to saving link shorteners… – Ahmed Fasih Apr 20 '17 at 13:03
3

And not only that but the original URL has information pertaining to what it is. URL shorteners lose that information. – Julien Chastang Mar 20 '19 at 21:56

score -6 · Answer 8 · edited Jul 14 '12 at 03:33

-6

My option would be:

URL = ('http://stackoverflow.com/questions/10739843/'
       'how-should-i-format-a-long-url-in-a-python-'
       'comment-and-still-be-pep8-compliant')

edited Jul 14 '12 at 03:33

Kijewski

25,517
12
101
143

answered May 24 '12 at 22:54

Medardo Rodriguez

81
2

5

Too painful to copy paste in a usable fashion this way. – Kel Solaar Aug 26 '14 at 07:10
That's not bad at all if you're not trying to copy and paste, works great when engineering requests to APIs. Saddens me to see how a perfectly good solution that does exactly what the OP asked is being downvoted... that's what's wrong with the software industry... – A Campos Apr 14 '22 at 16:19

How should I format a long url in a python comment and still be PEP8 compliant

8 Answers8

Linked