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.

Don’t break the url:

# 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

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.

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.

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.

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

Adding ‘# noqa’ works, but if it’s in a docstring the ‘# noqa’ shows up in the docs when built with spinx. In which 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

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