How should I format a long url in a python comment and still be PEP8 compliant
PythonPep8Python Problem Overview
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.
Python Solutions
Solution 1 - Python
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
Solution 2 - Python
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.
Solution 3 - Python
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.
Solution 4 - Python
I'd say leave it...
> 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.
Solution 5 - Python
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
Solution 6 - Python
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
Solution 7 - Python
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:
Solution 8 - Python
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')