ipython and doc tests. Cutting and pasting doctests into your shell.

-
Doc tests are a kind of literate programming for python. Where you type tests like you're typing stuff into an interpreter. In fact, it's easy to just type stuff into the interpreter and once you've finished playing around, copy the results from your terminal into a test file. This is a great, fairly low effort way of writing tests.

However, what if you have written them in your source code file, and not in the interpreter? Ok, so you've written some doc tests and you want to paste doc tests into your interpreter?

With the normal python interpreter you can't paste doc tests in(I don't think).

However the advanced ipython interpreter can. It has a special mode from writing doc tests. The command is called '%doctest_mode'.

The %doctest_mode command allows you to paste in doc tests, into the interpreter... and have them run. The normal python shell fails at this, as the '>>>' is not valid python syntax. The ipython ignores the '>>>' and the '...' which are normally used for doc tests.

It also changes the ipython prompt to look like the normal python prompt. This is useful for when you're writing doc tests. As the '>>>' is required for doc test.

The other useful command with ipython, to extract the code from your ipython session, to paste back into a file, is the %history command. Using '%history -tn 100' will show you the last 100 lines without any prompt. So then you can just copy/paste your shell session into a text editor.


ipython and %doctest_mode makes writing and reading doctests possible in your shell and your text editor. It makes it a two way process, not a one way process. You can go from your editor into your interpreter... or the other way around from your interpreter into your editor.

The other major use case %doctest_mode allows is to paste examples from documentation, into your interpreter. This is one of the main use cases with doc tests... but the normal python interpreter fails at this. So much documentation uses doc tests these days... so making it easy for people to actually paste that code in is very useful.

Double cheek kiss for ipython!

Comments

bcw said…
thank you thank you thank you! I already thought about hacking up django-extensions so that it uses ipython with the "-classic" flag (which also gives you doctype'able output) on "./manage.py shell_plus", but this is so much better!

Just a quick note: in my ipython, the command is called %doctest_mode, not %doctest, but that may be something Ubuntu-specific.
4:07 PM
René Dudfield said…
Hi,

yeah, oops! Not sure how I didn't get the name of the command right. Maybe because I just type '%doc+tab' all the time :) That's updated now. Thanks.


cu,
6:27 PM
Post a Comment

Popular posts from this blog

Draft 3 of, ^Let's write a unit test!^

-
Image
So, I started writing this for people who want to 'contribute' to Community projects, and also Free Libre or Open source projects. Maybe you'd like to get involved, but are unsure of where to begin? Follow along with this tutorial, and peek at the end in the "what is a git for?" section for explanations of what some of the words mean. Draft 1, 2018/07/18 - initial draft. Draft 2, 2019/11/04 - two full unit test examples, assertions, making a pull request, use python 3 unittest substring search, "good first issue" is a thing now. Started "What is a git for? Jargon" section. Draft 3, 2020/12/12 - default branch name is main. What's first? A test is first. A unit test is a piece of code which tests one thing works well in isolation from other parts of software. In this guide, I'm going to explain how to write one using the standard python unittest module, for the pygame game library. You can apply this advice to most python pr
Read more

Is PostgreSQL good enough?

-
Image
tldr; you can do jobs, queues, real time change feeds, time series, object store, document store, full text search with PostgreSQL. How to, pros/cons, rough performance and complexity levels are all discussed. Many sources and relevant documentation is linked to. Your database is first. But can PostgreSQL be second? Web/app projects these days often have many distributed parts. It's not uncommon for groups to use the right tool for the job. The right tools are often something like the choice below. Redis for queuing, and caching. Elastic Search for searching, and log stash. Influxdb or RRD for timeseries. S3 for an object store. PostgreSQL for relational data with constraints, and validation via schemas. Celery for job queues. Kafka for a buffer of queues or stream processing. Exception logging with PostgreSQL (perhaps using Sentry) KDB for low latency analytics on your column oriented data. Mongo/ZODB for storing documents JSON (or mangodb for /dev/null replacemen
Read more

post modern C tooling - draft 6

-
Image
Contemporary C tooling for making higher quality C, faster or more safely. DRAFT 0 - 10/11/18,  DRAFT 1 - 9/16/19, 7:19 PM, I'm still working on this, but it's already useful and I'd like some feedback - so I decided to share it early. DRAFT 2 - 10/1/19, mostly additions to static analysis tools. DRAFT 3 - 10/4/19, updates on build systems, package management, and complexity analysis.  DRAFT 4 - 10/6/19, run time dynamic verification and instrumentation, sanitizers (asan/ubsan/etc), performance tools, static analyzers. DRAFT 5 - C interpreter(s).  DRAFT 6 - 11/6/19 , mention TermDebug vim,  more windows debugging tools, C drawing for intro. In 2001 or so people started using the phrase "Modern C++". So now that it's 2019, I guess we're in the post modern era? Anyway, this isn't a post about C++ code, but some of this information applies there too. No logo, but it's used everywhere. Welcome to the post modern era. S
Read more