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.

Mcgann

Answer 1

Don't break the url:

Some other good reasons to ignore a particular guideline:

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

Abercromby

Can't understand why this is upvoted so many times. Doesn't work for me. – Niggling

@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. – Abercromby

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. – Bailiwick

The answer doesn't answer how to be compliant, so if you have a linter, it remains with warnings. – Grisham

@Grisham how to suppress a linter depends on the linter. – Abercromby

@Abercromby OP asked how to make it compliant, this answer does not make a URL compliant – Grisham

@Grisham 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. – Abercromby

@Abercromby 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. – Grisham

@Grisham 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. – Abercromby

@Abercromby so the answer should really be: "a long line is PEP8 compliant in this case" – Grisham

@Grisham it is exactly my answer:*"how should I format.. and be pep-8 compliant"* -> "don't break the url" – Abercromby

I just discovered control-click!! Now THAT'S why you don't want to break a URL in a comment. – Uzzial

@BobStein: in my case (emacs), it is "o" + letter to follow a link I'm looking at: screencast – Abercromby

Answer 2

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.

Cassatt

Answer 3

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.

Jamnes

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. – Ustkamenogorsk

Thanks @Sardathrion, should have more votes since it actually contributes a practical solution. – Kilocalorie

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. – Uzzial

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 # pylint: disable=line-too-long # noqa: E501. – Wroth

Answer 4

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.

Maryrosemarys

Answer 5

If your are using flake8:

"""
long-url: https://mcmap.net/q/181102/-how-should-i-format-a-long-url-in-a-python-comment-and-still-be-pep8-compliant
"""  # noqa

Bathypelagic

Answer 6

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

Lenalenard

Are you sure about your claim? https://mcmap.net/q/181102/-how-should-i-format-a-long-url-in-a-python-comment-and-still-be-pep8-compliant – Wroth

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. – Lenalenard

Answer 7

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

Acceleration

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… – Suitable

And not only that but the original URL has information pertaining to what it is. URL shorteners lose that information. – Fervency

Answer 8

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')

Trautman

Too painful to copy paste in a usable fashion this way. – Rob

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... – Cree