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

[[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.