Fix pep257 errors

[dpursehouse]

In these commits I've removed all the pep257 violations from pep257.py and converted the test module to use the built-in python unit test library.

Still to do:

• Make the test module pass pep8.
• Add new unit tests to cover the errors removed from pep257.py
• Add unit tests for the rest of the functionality

[keleshev]

It looks like we misunderstood each other a bit—I meant it would be great if you add tests that cover check_* functions functionality into test_pep257.py (which are now tested with invalid docstrings in code itself), not convert py.test-tests to unittest-tests.

I hate unittest framework with passion :-) and use py.test for all my python tests. So I will not pull 17fd8de74a0b218f0ee52e45c801f98d8daff1d1.

Otherwise it all looks good and I will pull other commits, when I get home.

[keleshev]

Ok now I read your "Still to do" :-)

Glad that you are about to add those test, but anyway, py.test is what is used for this project. Try it, I'm sure you will love it.

[dpursehouse]

@halst Sorry, I missed that "py.test" is a unit test framework. I'll have a look into that and try to add some new tests.

I'm using the built-in unittest framework in my environment so I'll move the changes that I made into a separate file and maintain that separately on my fork.

[dpursehouse]

OK, I've cleaned this up a bit. Removed the unwanted commits related to unittest, and moved the other completely unrelated commits to separate pull requests.

I'll continue with this one later, adding py.test tests to replace the tests removed in 93b8308.

[dpursehouse]

I haven't forgotten about this; I'm just busy with other work. I'll try to make time for it in the next weeks.

[keleshev]

@dpursehouse ok, good to know that you're on it.

[dpursehouse]

This is almost done. There are still 2 test cases to be implemented - marked as TODO in test_pep257.py

[keleshev]

Sorry for taking so long.

I merged this, but I found something funny in case of:

r"""PEP257 Use \"\"\"triple double quotes\"\"\".

For consistency, always use \"\"\"triple double quotes\"\"\" around
docstrings. Use r\"\"\"raw triple double quotes\"\"\" if you use any
backslashes in your docstrings. For Unicode docstrings, use
u\"\"\"Unicode triple-quoted strings\"\"\".

"""

The problem with this is when you do:

>>> import pep257
>>> help(pep257.check_triple_double_quotes)

you get this:

Help on function check_triple_double_quotes in module pep257:

check_triple_double_quotes(docstring, context, is_script)
    PEP257 Use \"\"\"triple double quotes\"\"\".

    For consistency, always use \"\"\"triple double quotes\"\"\" around
    docstrings. Use r\"\"\"raw triple double quotes\"\"\" if you use any
    backslashes in your docstrings. For Unicode docstrings, use
    u\"\"\"Unicode triple-quoted strings\"\"\".

And I don't know how te get around of this without breaking PEP 257 rules.

[dpursehouse]

I didn't know about the help method before.

I guess you want it to display without the escaping on the quote characters? I don't see how that could be done without violating pep257. One way would be to remove the quote characters from the docstring:

r"""PEP257 Use triple double quotes.

For consistency, always use triple double quotes around
docstrings. Use raw triple double quotes if you use any
backslashes in your docstrings. For Unicode docstrings, use
Unicode triple-quoted strings.

"""

[keleshev]

I wanted the quote characters in the error message to aid quick recognizability of errors. If we remove all occurrences of """, r""", u""", the error messages will be much less readable.

Do you think it will be suboptimal to use ''' instead for those docstrings?
Maybe pep257 itself should allow ''' in case the docstring has """ in it?

[dpursehouse]

Right, it will be less readable if we remove them. If we want to keep them, and not use escaping, the only way to do it is to use '''.

How about making an update suggestion to pep257? I guess that would need to be sent to doc-sig at python.org according to the page:

http://www.python.org/dev/peps/pep-0257/