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.
Answers:
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.
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.
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
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')
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:
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.
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’ 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('^(.*)ss#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
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.
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.
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.
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
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')
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:
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.
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’ 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('^(.*)ss#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