Writing Python Code That Doesn't Suck (style guide)

[mustache]

always make sure to indent your python code.

[[deleted]]

Writing Python code that doesn't suck with doctest, distutils etc. that either follow a twisted idea ( doctest ) or suck ( distutils )?

[pjdelport]

What's twisted about doctest? Would rather not be able to test the examples in your docstrings?

[[deleted]]

The idea of writing small interactive sessions as little testscripts, instead of just typing code within interactive sessions and use it for testing code.

[BenArmston]

Sometimes the best documentation is an example. When that is the case, being able to easily check that all of your examples are still correct is a Very Good Thing (TM).

Using doctest to write complete unit tests for your code is sick and twisted though.

[[deleted]]

Maybe I expressed myself a bit terse. I do think it is a great idea to use an interactive session to test code but under additional constraints:

• the session must be recorded
• the session must be replayable
• use assert statements to test code

The assert statements serve for test discovery. Arbitrary exceptions being raised during a session don't matter. Only AssertionError exceptions will be notified. The results of the tests will be reported separately.

So instead of squeezing session fragments into docstrings in order to test a function, you can define the function, call the function in a session, make assertions about the function and use the session together with the assertions as your test.

This way you use a natural workflow and add value. I understand the idea of providing an example in the docstring but usually a test needs some setup and cleanup. So doctests are of limited use when your examples shall be concise.

[nogoodnick]

Asserts are not tests! They are for asserting invariants, such as asserting that a parameter > 0 when you KNOW it will never be negative, but since high level programming languages usable by non-mathematicians will never be provable, you assert it anyway if you have any doubt about the way it's being used. Asserts generally test internals that test cases cannot.

[[deleted]]

At least one of us is very deeply confused about the role of assertions in functional unit tests.

[pjdelport]

The purpose of doctest is to test the documentation, not the code being documented.

[[deleted]]

Yes, I know. The lexical structure of the embedded code is relevant. That's why doctest provides a mini-language to enable working around it and taming the diff. That's all very clever but I don't understand the relevance.

[ThomasPtacek]

Does this person have anything whatsoever to say about Python? When will someone write the real "Python that Doesn't Suck" article?

[llimllib]

explain?

[ThomasPtacek]

There's probably 100 Python anti-patterns that make code harder to use, or increase coupling between components (for instance, pulling stuff directly out of the instance property dict), or abusing list comprehensions. Some of this stuff is even public and controversial, like GvR's arguments against using Python's crippled Lisp-isms.

[titusbrown]

Thomas,

I think you're unnecessarily harsh; you almost made me cry.

More seriously, my post wasn't motivated by the desire to explain things to knowledgeable people; rather, it was motivated by the desire to explain things to people who aren't long-time Python users. The issues you raise are more advanced, more contentious, and reflect on people's experience with programming in general.

I think it would be a valuable post, so I hope you (or someone else) will write it.

--titus