Tuna

Common errors

• tuna: command not found

  cause The `tuna` executable is not in your system's PATH. This often happens if `pip install tuna` was run with `--user` and the user's bin directory is not in PATH, or if the virtual environment is not activated.
  fix Ensure your virtual environment is activated. If installed with `--user`, add `~/.local/bin` (or equivalent for your OS) to your system's PATH. On Linux/macOS, this typically involves adding `export PATH="$HOME/.local/bin:$PATH"` to your shell's configuration file (e.g., `.bashrc`, `.zshrc`).

• Error: profile file 'program.prof' not found.

  cause The `tuna` command was run with a profile file name that does not exist in the current directory or the specified path is incorrect.
  fix Verify that the profile file (e.g., `program.prof` or `import.log`) exists at the specified path. Double-check the filename and its location. Ensure the profiling command (e.g., `python -mcProfile -o ...` or `python -X importtime ...`) executed successfully and created the output file.

• TypeError: unsupported operand type(s) for +: 'int' and 'str'

  cause This is a general Python error, but if encountered during profiling or within the profiled code, it's typically an issue within the application logic being profiled, not `tuna` itself.
  fix Debug your application code directly to identify the type mismatch. Tuna visualizes *how* your code performs, but it doesn't prevent or diagnose application-level runtime errors. Use standard Python debugging techniques.

Warnings

• gotcha Tuna's visualization of the call tree is intentionally incomplete compared to some other profilers (e.g., older SnakeViz versions). It only displays the part of the timed call tree that can be directly deduced from the profile data, as Python's profilers (like cProfile) do not store the full contextual call hierarchy (e.g., differentiating calls to the same function from different parents).
  Fix: This is a design choice for accuracy. Understand that the displayed call tree reflects what's reliably measurable from `cProfile` output. If you need a full, but potentially less accurate, call tree, other profilers might be necessary, but Tuna prioritizes accurate timings within its scope.
• gotcha When using `tuna` as an IPython magic (e.g., in Jupyter notebooks), you must explicitly load the extension first.
  Fix: Always run `%load_ext tuna` at the beginning of your IPython session or notebook before attempting to use `%tuna` or `%%tuna` magics.

Install

• pip install tuna Install latest version

Imports

• tuna CLI
  wrong:

  from tuna import visualize

  correct:

  tuna your_profile.prof

  Tuna is primarily a command-line tool or an IPython magic, not a library meant for direct Python imports for its core visualization functionality. It operates on profile files generated by cProfile or importtime.
• %tuna IPython magic
  wrong:

  %tuna your_code() (without loading extension)

  correct:

  %load_ext tuna
  %tuna your_code()

  The IPython magic must be loaded first in a session before it can be used.

Quickstart

Generate a runtime profile using Python's built-in `cProfile` module, saving the output to a file. Then, visualize the profile by running the `tuna` command-line tool with the generated profile file. Alternatively, you can profile import times by redirecting `python -X importtime` output to a log file and viewing it with `tuna`.

import cProfile
import time

def func_a():
    time.sleep(0.1)

def func_b():
    func_a()
    time.sleep(0.05)

def main():
    func_a()
    func_b()

profile_file = 'my_program.prof'
cProfile.run('main()', profile_file)

print(f"Profile saved to {profile_file}. View with: tuna {profile_file}")

# To view import profile (run from terminal):
# python -X importtime -c "import pandas" 2> import.log
# print("Import profile saved to import.log. View with: tuna import.log")