unsupported-features.md

Python Tutor's server and live chat service may go down at any time and lose your code! There is NO on-call technical support available.

This is a free service that is provided as-is with no quality or uptime guarantees. Your issue is probably listed here. If you're sure it's not here, file a GitHub issue and use the "Generate permanent link" button to include a URL of your code.

• If you don't get a reply, assume your issue will NOT be addressed. Please do not add duplicate issues.
• "Get live help!" is down periodically due to heavy server loads; do not ask about when it may be back up.
• We can't provide support for Python Tutor code embedded in other websites. Contact those site owners for help.

Unsupported features

Read this first!

Python Tutor is designed to imitate what an instructor in an introductory programming class draws on the blackboard:

(source: UC Berkeley's CS61B course)

It's meant to illustrate small pieces of self-contained code that runs for not too many steps. After all, an instructor can't write hundreds of lines of code, draw hundreds of data structures and pointers, or walk through hundreds of execution steps on the board! Also, code in introductory classes usually doesn't access external libraries. If your code can't fit on a blackboard or a single presentation slide, it's probably too long to visualize effectively in Python Tutor.

Due to this ultra-focused design, the following features are not supported and will likely never be supported:

• Code that is too large in size.
  • shorten your code to what fits on a blackboard or presentation slide!
  • Python Tutor is not for debugging arbitrary code that you paste into it; you'll need to shorten your code to isolate what you want to debug
• Code that runs for too many steps (e.g., > 1,000 steps) or for a long time
  • shorten your code to isolate exactly what operations you want to visualize
  • e.g., make your numbers and strings smaller, your data structures contain fewer items, and your loops/functions run fewer times
  • or set Python breakpoints using #break comments
• Code that defines too many variables or objects
  • shorten your code to isolate what variables you want to visualize
  • remove unnecessary variables and objects
  • for Python, use pythontutor_hide to selectively hide variables
• Advanced language features or subtleties that only experts need to know (this is a tool for teaching novices)
• Visualizing custom data structures from imported libraries; Python Tutor visualizes only built-in types and data structures
• Importing most external libraries (try "Python 3.6 with Anaconda (experimental)" to access more libraries)
• Reading data from external files (you can use strings to emulate files: examples for Python3 and Python2)
• Interfacing with databases, filesystems, networking, or other external resources
• Anything involving GUI programming or GUI/webpage components
• Multi-threaded, concurrent, or asynchronous code; Python Tutor is only for regular single-threaded execution
• Compile-time magic (e.g., macros, metaprogramming, templates) can't be visualized; Python Tutor visualizes only run-time memory state
• Editing multiple source code files (Python Tutor is not an IDE!)
• User accounts, saving code as files in the cloud, or integrating with online services like GitHub (again, Python Tutor is not an IDE!)
• Integrating with programming environments like Jupyter Notebooks, IDEs, or text editors

Python unsupported features

• for strings and numbers, you can't rely on the behaviors of id() or is matching CPython on your computer; when teaching beginners, you shouldn't rely on these behaviors since they are implementation-specific optimizations.
• some infinite loops: the server times-out without showing partial results or good error messages
  • to cut down execution times, set Python breakpoints using #break comments
• random number generators and user input (via input() or raw_input()) sometimes don't work well together
• raw_input/input might not work in iframe embeds
• more GitHub issues: https://github.com/pythontutor-dev/pythontutor/issues

C and C++ unsupported features

The visualizer compiles code with gcc 4.8 and runs it using a Valgrind Memcheck-based plugin. It currently supports C11/C++11.

• doesn't visualize when function parameters get mutated (remedy: make a copy to a new local variable to visualize)
• doesn't visualize function return values (remedy: add a temporary return variable to visualize)
• unions
• taking text input from the user using scanf(), fgets with stdin, cin >>, etc.
• code with undefined behavior may not match what happens when running on your own computer!
  • specifically, code with memory errors will fail-fast using Valgrind Memcheck
• memory leaks: leaked memory is not visualized since nothing points to it
• some complex typedefs
• function pointers
• if pointers of different types point to the same memory block, unexpected things may happen; e.g., if an int* and a char* point to the same block of memory, it may be visualized as either an int or a char array (see type punning) (see GitHub issue)
• bitfields
• alternative representations of memory like viewing individual bits or bytes
• stack arrays without compile-time sizes
• read-only memory isn't visualized separately from the heap
• struct members declared as unbounded arrays
• mixed pointer/array declared types
• static array initializers
• C++ STL containers and strings aren't visualized nicely
• haven't tested on various C++ smart pointers yet
• haven't tested on inline functions (e.g., explicitly 'inline' or implicitly inlined member functions defined within class definitions, etc)
• probably lots of untested subtleties with more advanced modern C++ features from C++11 and newer

Look at these GitHub issues for more C/C++ unsupported features: C/C++

JavaScript unsupported features

The visualizer currently supports JavaScript ES6 and TypeScript 1.4.1 (running in Node.js v6.0.0).

• asynchronous and event-driven code
  • including setTimeout, setInterval, etc.
  • promises, async/await
• anything that operates on webpages, such as DOM manipulation, alert(), prompt(), confirm(), etc.
  • this includes trying to import frontend libraries or frameworks (e.g., jQuery, React)
• Date() object
• for-loop variables show up duplicated in two nested blocks due to how the Node.js JavaScript debugger emits its values (see GitHub issue for details)
• features that novices don't usually need to know about, like adding object fields to an array, which can be confusing (example code)
• more JavaScript unsupported features: javascript

Java unsupported features

The Java 8 visualizer was made by David Pritchard and Will Gwozdz. It supports StdIn, StdOut, most other stdlib libraries, Stack, Queue, and ST. To access built-in Stack and Queue classes, write: import java.util.Stack; This won't work: import java.util.*;

Note that the Java visualizer is not maintained anymore so I am unlikely to fix reported bugs here. Known limitations:

• some data structures like ArrayList aren't visualized properly

Ruby unsupported features

The Ruby visualizer currently supports Ruby 2 (MRI 2.2.2); note that it is not maintained anymore so I am unlikely to fix reported bugs here.

• see GitHub issues: ruby

Other language-independent unsupported features

• printing to stderr might not work; use regular stdout print statements
• Python Tutor is meant for desktop/laptop computers, not for mobile devices. Some features such as live help mode simply don't work on mobile devices. The UI also looks cluttered and can be buggy on small screens.
• Stepping within a line of code to show how subexpressions get evaluated within that line; the best workaround is to split complex expressions into multiple lines and assign temporary variables on each line (example).
• Unicode doesn't well, especially for Ruby: #59, and Python 2: #76, #80, #87 (use ASCII characters when possible)
• Passing in command-line arguments via argv[] array (use hard-coded strings instead)
• If you're behind some kinds of firewalls or proxy servers, the visualizer or live chat may not work
• URL shortening (you should use your own third-party URL shortener service)
• https iframe embedding with non-Python languages (iframe embed should work for Python if you use https:// for URL)

Look at these issues for more unsupported features: https://github.com/pythontutor-dev/pythontutor/issues

FAQ

I thought all objects in Python are (conceptually) on the heap; why does Python Tutor render primitive values (e.g., numbers, strings) inside of stack frames?

This was a design decision made to keep the display less cluttered; if we were truly faithful to Python's semantics, that would result in far too many arrows (pointers) being drawn. However, note that since primitives are immutable and thus behave identically regardless of aliasing, it doesn't matter whether they're rendered in the stack or heap.

Update on 2013-01-06: I've added a drop-down menu option with two choices: "inline primitives and nested objects" versus "render all objects on the heap". If you want to render all objects on the heap, select the latter option. To avoid too many arrows being drawn, also toggle the default "draw references using arrows" option to "use text labels for references". Here is a direct link to activate those two settings:

http://pythontutor.com/visualize.html#heapPrimitives=true&textReferences=true

I don't like your default toggle options. Can I set different defaults?

Of course! Toggle options are customizable via the query string. Here are the default settings:

http://pythontutor.com/visualize.html#cumulative=false&heapPrimitives=nevernest&drawParentPointers=false&textReferences=false&showOnlyOutputs=false&py=3

For example, if you want to default to C, visit: http://pythontutor.com/visualize.html#&py=c

Or Java: http://pythontutor.com/visualize.html#&py=java

Or if you want to render all objects on the heap and use text label references, visit: http://pythontutor.com/visualize.html#heapPrimitives=true&textReferences=true

Can I iframe-embed using https?

Yes, only for Python, though. Change the embed URL from http:// to https:// and it should hopefully work.