Mu API Reference

This API reference is automatically generated from the docstrings found within the source code. It’s meant as an easy to use and easy to share window into the code base.

Take a look around! The code is simple and short.

mu.app

The Mu application is created and configured in this module.

mu.app.debug()

Create a debug runner in a new process.

This is what the Mu debugger will drive. Uses the filename and associated args found in sys.argv.

mu.app.excepthook(*exc_args)

Log exception and exit cleanly.

mu.app.run()

Creates all the top-level assets for the application, sets things up and then runs the application. Specific tasks include:

• set up logging

• create an application object

• create an editor window and status bar

• display a splash screen while starting

• close the splash screen after startup timer ends

mu.app.setup_logging()

Configure logging.

mu.app.setup_modes(editor, view)

Create a simple dictionary to hold instances of the available modes.

PREMATURE OPTIMIZATION ALERT This may become more complex in future so splitting things out here to contain the mess. ;-)

mu.logic

Most of the fundamental logic for Mu is in this module.

class mu.logic.Editor(view, status_bar=None)

Application logic for the editor itself.

autosave()

Cycles through each tab and, if changed, saves it to the filesystem.

change_mode(mode)

Given the name of a mode, will make the necessary changes to put the editor into the new mode.

check_code()

Uses PyFlakes and PyCodeStyle to gather information about potential problems with the code in the current tab.

check_for_shadow_module(path)

Check if the filename in the path is a shadow of a module already in the Python path. For example, many learners will save their first turtle based script as turtle.py, thus causing Python to never find the built in turtle module because of the name conflict.

If the filename shadows an existing module, return True, otherwise, return False.

check_usb()

Ensure connected USB devices are polled. If there’s a change and a new recognised device is attached, inform the user via a status message. If a single device is found and Mu is in a different mode ask the user if they’d like to change mode.

debug_toggle_breakpoint(margin, line, modifiers)

How to handle the toggling of a breakpoint.

direct_load(path)

for loading files passed from command line or the OS launch

find_replace()

Handle find / replace functionality.

If find/replace dialog is dismissed, do nothing.

Otherwise, check there’s something to find, warn if there isn’t.

If there is, find (and, optionally, replace) then confirm outcome with a status message.

get_dialog_directory(default=None)

Return the directory folder in which a load/save dialog box should open into. In order of precedence this function will return:

0. If not None, the value of default.

1. The last location used by a load/save dialog.

2. The directory containing the current file.

3. The mode’s reported workspace directory.

get_tab(path)

Given a path, returns either an existing tab for the path or creates / loads a new tab for the path.

load(*args, default_path=None)

Loads a Python (or other supported) file from the file system or extracts a Python script from a hex file.

load_cli(paths)

Given a set of paths, passed in by the user when Mu starts, this method will attempt to load them and log / report a problem if Mu is unable to open a passed in path.

new()

Adds a new tab to the editor.

quit(*args, **kwargs)

Exit the application.

rename_tab(tab_id=None)

How to handle double-clicking a tab in order to rename the file. If activated by the shortcut, activate against the current tab.

restore_session(paths=None)

Attempts to recreate the tab state from the last time the editor was run. If paths contains a collection of additional paths specified by the user, they are also “restored” at the same time (duplicates will be ignored).

save(*args, default=None)

Save the content of the currently active editor tab.

save_tab_to_file(tab, show_error_messages=True)

Given a tab, will attempt to save the script in the tab to the path associated with the tab. If there’s a problem this will be logged and reported and the tab status will continue to show as Modified.

select_mode(event=None)

Select the mode that editor is supposed to be in.

setup(modes)

Define the available modes and ensure there’s a default working directory.

show_admin(event=None)

Cause the editor’s admin dialog to be displayed to the user.

Ensure any changes to the envars is updated.

show_help()

Display browser based help about Mu.

show_status_message(message, duration=5)

Displays the referenced message for duration seconds.

sync_package_state(old_packages, new_packages)

Given the state of the old third party packages, compared to the new third party packages, ensure that pip uninstalls and installs the packages so the currently available third party packages reflects the new state.

tidy_code()

Prettify code with Black.

toggle_comments()

Ensure all highlighted lines are toggled between comments/uncommented.

toggle_theme()

Switches between themes (night, day or high-contrast).

zoom_in()

Make the editor’s text bigger

zoom_out()

Make the editor’s text smaller.

class mu.logic.MuFlakeCodeReporter

The class instantiates a reporter that creates structured data about code quality for Mu. Used by the PyFlakes module.

flake(message)

PyFlakes found something wrong with the code.

syntaxError(filename, message, line_no, column, source)

Records a syntax error in the file called filename.

The message argument contains an explanation of the syntax error, line_no indicates the line where the syntax error occurred, column indicates the column on which the error occurred and source is the source code containing the syntax error.

unexpectedError(filename, message)

Called if an unexpected error occured while trying to process the file called filename. The message parameter contains a description of the problem.

class mu.logic.REPL(port)

Read, Evaluate, Print, Loop.

Represents the REPL. Since the logic for the REPL is simply a USB/serial based widget this class only contains a reference to the associated port.

mu.logic.check_flake(filename, code, builtins=None)

Given a filename and some code to be checked, uses the PyFlakesmodule to return a dictionary describing issues of code quality per line. See:

https://github.com/PyCQA/pyflakes

If a list symbols is passed in as “builtins” these are assumed to be additional builtins available when run by Mu.

mu.logic.check_pycodestyle(code, config_file=False)

Given some code, uses the PyCodeStyle module (was PEP8) to return a list of items describing issues of coding style. See:

https://pycodestyle.readthedocs.io/en/latest/intro.html

mu.logic.extract_envars(raw)

Returns a list of environment variables given a string containing NAME=VALUE definitions on separate lines.

mu.logic.get_admin_file_path(filename)

Given an admin related filename, this function will attempt to get the most relevant version of this file (the default location is the application data directory, although a file of the same name in the same directory as the application itself takes preference). If this file isn’t found, an empty one is created in the default location.

mu.logic.get_session_path()

The session file stores details about the state of Mu from the user’s perspective (tabs open, current mode etc…).

The session file default location is the application data directory. However, a session file in the same directory as the application itself takes preference.

If no session file is detected a blank one in the default location is automatically created.

mu.logic.get_settings_path()

The settings file stores details about the configuration of Mu from an administrators’ perspective (default workspace etc…).

The settings file default location is the application data directory. However, a settings file in the same directory as the application itself takes preference.

If no settings file is detected a blank one in the default location is automatically created.

mu.logic.installed_packages()

List all the third party modules installed by the user.

mu.logic.read_and_decode(filepath)

Read the contents of a file,

mu.logic.save_and_encode(text, filepath, newline='\n')

Detect the presence of an encoding cookie and use that encoding; if none is present, do not add one and use the Mu default encoding. If the codec is invalid, log a warning and fall back to the default.

mu.logic.sniff_encoding(filepath)

Determine the encoding of a file:

• If there is a BOM, return the appropriate encoding

• If there is a PEP 263 encoding cookie, return the appropriate encoding

• Otherwise return None for read_and_decode to attempt several defaults

mu.logic.sniff_newline_convention(text)

Determine which line-ending convention predominates in the text.

Windows usually has U+000D U+000A Posix usually has U+000A But editors can produce either convention from either platform. And a file which has been copied and edited around might even have both!

mu.logic.write_and_flush(fileobj, content)

Write content to the fileobj then flush and fsync to ensure the data is, in fact, written.

This is especially necessary for USB-attached devices

mu.debugger

The debugger consists of two parts:

• Client - used by Mu to process messages from the process being debugged.

• Runner - created in a new process to run the code to be debugged.

Messages are passed via inter-process communication.

mu.debugger.client

Code used by the Mu application to communicate with the process being debugged.

class mu.debugger.client.Breakpoint(bpnum, filename, line, enabled=True, temporary=False, funcname=None)

Represents a breakpoint, identified by a breakpoint number (bpnum). Users set breakpoints to stop the debugger at a certain line (potentially in a named function) in a file.

class mu.debugger.client.CommandBufferHandler(debugger)

Represents the work to be done on a separate thread for connecting and processing incoming messages.

Emits signals to indicate when messages are receievd or the connection fails at appropriate moments during the lifetime of a debug session.

on_command

Signal emitted when a command is received.

on_fail

Emitted when there was a connection failure.

worker()

Buffer input from a socket, emit complete debugger commands as signals.

exception mu.debugger.client.ConnectionNotBootstrapped

The connection to the runner hasn’t been completed.

class mu.debugger.client.Debugger(host, port, proc=None)

Represents the networked debugger client.

breakpoint(breakpoint)

Given a breakpoint number or (filename, line), return an object representing the referenced breakpoint.

breakpoints(filename)

Return all the breakpoints associated with the referenced file.

clear_breakpoint(breakpoint)

Clear an existing breakpoint.

create_breakpoint(filename, line, temporary=False)

Create a new, enabled breakpoint at the specified line of the given file.

disable_breakpoint(breakpoint)

Disable an existing breakpoint.

do_next()

Go to the next line in the current stack frame.

do_return()

Return to the previous stack frame.

do_run()

Run the debugger until the next breakpoint.

do_step()

Step through one stack frame.

enable_breakpoint(breakpoint)

Enable an existing breakpoint.

ignore_breakpoint(breakpoint, count)

Ignore an existing breakpoint for “count” iterations.

(N.B. Use a count of 0 to restore the breakpoint.

on_bootstrap(breakpoints)

The runner has finished setting up.

on_breakpoint_clear(bpnum)

The runner has cleared the referenced breakpoint.

on_breakpoint_create(**bp_data)

The runner has created a breakpoint.

on_breakpoint_disable(bpnum)

The runner has disabled a breakpoint referenced by breakpoint number.

on_breakpoint_enable(bpnum)

The runner has enabled the breakpoint referenced by breakpoint number.

on_breakpoint_ignore(bpnum, count)

The runner will ignore the referenced breakpoint “count” iterations.

on_call(args)

The runner has called a function with the specified arguments.

on_command(command)

Handle a command emitted by the client thread.

on_error(message)

The runner has sent an error message.

on_exception(name, value)

The runner has encountered a named exception with an associated value.

on_fail(message)

Handle if there’s a connection failure with the debug runner.

on_finished()

The debug runner has finished running the script to be debugged.

on_info(message)

The runner has sent an informative message.

on_line(filename, line)

The runner has moved to the specified line in the referenced file.

on_postmortem(*args, **kwargs)

The runner encountered a fatal error and has died.

on_restart()

The runner has restarted.

on_return(retval)

The runner has returned from a function with the specified return value.

on_stack(stack)

The runner has sent an update to the stack.

on_warning(message)

The runner has sent a warning message.

output(event, **data)

Send a command to the debug runner.

start()

Start the debugger session.

stop()

Shut down the debugger session.

exception mu.debugger.client.UnknownBreakpoint

The client encountered an unknown breakpoint.

mu.debugger.runner

The runner code controls the debug process.

exception mu.debugger.runner.ClientClose

Cause the debugger to wait for a new client to connect.

class mu.debugger.runner.DebugState

Enumerates the three possible states of a debugging session.

class mu.debugger.runner.Debugger(socket, host, port, skip=None)

Instances of this class represent and drive the debugging process.

do_break(filename, line, temporary=False)

Set a breakpoint.

do_clear(bpnum)

Handle how a breakpoint must be removed when it is a temporary one.

do_close()

Respond to a closed socket (not a user commend, but needs handling).

do_continue()

Stop only at breakpoints or when finished. If there are no breakpoints on script start, do a set_trace to stop at the first available line. However, use the continue_flag to ensure set_continue is always called thereafter.

do_disable(bpnum)

Disable the breakpoint referenced by its breakpoint number (bpnum).

do_enable(bpnum)

Enables the breakpoint referenced by its breakpoint number (bpnum).

do_ignore(bpnum, count)

Ignore the breakpoint referenced by its breakpoint number (bpnum), count number of times.

do_next()

Stop on the next line in or below the given frame.

do_quit()

Set the quitting attribute to True. This raises BdbQuit in the next call to one of the dispatch_*() methods.

do_restart()

Restart the program by raising an exception to be caught by the debugger.

do_return()

Stop when returning from the current frame.

do_step()

Stop after one line of code.

interact(frame, traceback)

Contains the loop processing interactions with the debugger.

output(event, **data)

Dumps data related to a referenced event to the socket.

output_stack()

Dump the current stack.

If this is a normal situation, the top two frames are BDB and the runner executing the program. If there is an exception, there are two further extra frames. All these frames can be ignored.

reset()

Reset state.

setup(frame, traceback)

Start state should be set correctly.

user_call(frame, argument_list)

This method is called from dispatch_call() when there is the possibility that a break might be necessary anywhere inside the called function.

user_exception(frame, exc_info)

This method is called from dispatch_exception() when stop_here() yields True.

For when an exception occurs, but only if we are to stop at or just below this level.

user_line(frame)

This method is called from dispatch_line() when either stop_here() or break_here() yields True.

For when we stop or break at this line.

user_return(frame, return_value)

This method is called from dispatch_return() when stop_here() yields True.

For when a return trap is set here.

exception mu.debugger.runner.Restart

Cause the debugger to restart for the target Python program.

mu.debugger.runner.command_buffer(debugger)

Buffer input from a socket, yield complete debugger commands.

mu.debugger.runner.run(hostname, port, filename, *args)

Run a Python script identified by “filename” with the specified arguments in a debugger session that’s listening at hostname/port.

mu.interface

This module contains all the PyQt related code needed to create the user interface for Mu. All interaction with the user interface is done via the Window class in mu.interface.main.

All the other sub-modules contain different bespoke aspects of the user interface.

mu.interface.main

Contains the core user interface assets used by other parts of the application.

class mu.interface.main.ButtonBar(parent)

Represents the bar of buttons across the top of the editor and defines their behaviour.

addAction(name, display_name, tool_text)

Creates an action associated with an icon and name and adds it to the widget’s slots.

connect(name, handler, shortcut=None)

Connects a named slot to a handler function and optional hot-key shortcuts.

reset()

Resets the button states.

set_responsive_mode(width, height)

Compact button bar for when window is very small.

class mu.interface.main.FileTabs

Extend the base class so we can override the removeTab behaviour.

change_tab(tab_id)

Update the application title to reflect the name of the file in the currently selected tab.

removeTab(tab_id)

Ask the user before closing the file.

class mu.interface.main.StatusBar(parent=None, mode='python')

Defines the look and behaviour of the status bar along the bottom of the UI.

connect_logs(handler, shortcut)

Connect the mouse press event and keyboard shortcut for the log widget to the referenced handler function.

connect_mode(handler, shortcut)

Connect the mouse press event and keyboard shortcut for the mode widget to the referenced handler function.

set_message(message, pause=5000)

Displays a message in the status bar for a certain period of time.

set_mode(mode)

Updates the mode label to the new mode.

class mu.interface.main.Window

Defines the look and characteristics of the application’s main window.

add_debug_inspector()

Display a debug inspector to view the call stack.

add_filesystem(home, file_manager, board_name='board')

Adds the file system pane to the application.

add_jupyter_repl(kernel_manager, kernel_client)

Adds a Jupyter based REPL pane to the application.

add_micropython_plotter(port, name, mode)

Adds a plotter that reads data from a serial connection.

add_micropython_repl(port, name, force_interrupt=True)

Adds a MicroPython based REPL pane to the application.

add_plotter(plotter_pane, name)

Adds the referenced plotter pane to the application.

add_python3_plotter(mode)

Add a plotter that reads from either the REPL or a running script. Since this function will only be called when either the REPL or a running script are running (but not at the same time), it’ll just grab data emitted by the REPL or script via data_received.

add_python3_runner(script_name, working_directory, interactive=False, debugger=False, command_args=None, runner=None, envars=None, python_args=None)

Display console output for the referenced Python script.

The script will be run within the workspace_path directory.

If interactive is True (default is False) the Python process will run in interactive mode (dropping the user into the REPL when the script completes).

If debugger is True (default is False) the script will be run within a debug runner session. The debugger overrides the interactive flag (you cannot run the debugger in interactive mode).

If there is a list of command_args (the default is None) then these will be passed as further arguments into the command run in the new process.

If runner is given, this is used as the command to start the Python process.

If envars is given, these will become part of the environment context of the new chlid process.

If python_args is given, these will be passed as arguments to the Python runtime used to launch the child process.

add_repl(repl_pane, name)

Adds the referenced REPL pane to the application.

add_tab(path, text, api, newline)

Adds a tab with the referenced path and text to the editor.

annotate_code(feedback, annotation_type)

Given a list of annotations about the code in the current tab, add the annotations to the editor window so the user can make appropriate changes.

change_mode(mode)

Given a an object representing a mode, recreates the button bar with the expected functionality.

close_serial_link()

Close and clean up the currently open serial link.

connect_find_replace(handler, shortcut)

Create a keyboard shortcut and associate it with a handler for doing a find and replace.

connect_tab_rename(handler, shortcut)

Connect the double-click event on a tab and the keyboard shortcut to the referenced handler (causing the Save As dialog).

connect_toggle_comments(handler, shortcut)

Create a keyboard shortcut and associate it with a handler for toggling comments on highlighted lines.

connect_zoom(widget)

Connects a referenced widget to the zoom related signals and sets the zoom of the widget to the current zoom level.

property current_tab

Returns the currently focussed tab.

focus_tab(tab)

Force focus on the referenced tab.

get_load_path(folder, extensions='*', allow_previous=True)

Displays a dialog for selecting a file to load. Returns the selected path. Defaults to start in the referenced folder unless a previous folder has been used and the allow_previous flag is True (the default behaviour)

get_microbit_path(folder)

Displays a dialog for locating the location of the BBC micro:bit in the host computer’s filesystem. Returns the selected path. Defaults to start in the referenced folder.

get_save_path(folder)

Displays a dialog for selecting a file to save. Returns the selected path. Defaults to start in the referenced folder.

highlight_text(target_text)

Highlight the first match from the current position of the cursor in the current tab for the target_text. Returns True if there’s a match.

property modified

Returns a boolean indication if there are any modified tabs in the editor.

on_serial_read()

Called when the connected device is ready to send data via the serial connection. It reads all the available data, emits the data_received signal with the received bytes and, if appropriate, emits the tuple_received signal with the tuple created from the bytes received.

on_stdout_write(data)

Called when either a running script or the REPL write to STDOUT.

open_directory_from_os(path)

Given the path to a directory, open the OS’s built in filesystem explorer for that path. Works with Windows, OSX and Linux.

open_serial_link(port)

Creates a new serial link instance.

remove_debug_inspector()

Removes the debug inspector pane from the application.

remove_filesystem()

Removes the file system pane from the application.

remove_plotter()

Removes the plotter pane from the application.

remove_python_runner()

Removes the runner pane from the application.

remove_repl()

Removes the REPL pane from the application.

replace_text(target_text, replace, global_replace)

Given target_text, replace the first instance after the cursor with “replace”. If global_replace is true, replace all instances of “target”. Returns the number of times replacement has occurred.

reset_annotations()

Resets the state of annotations on the current tab.

resizeEvent(resizeEvent)

Respond to window getting too small for the button bar to fit well.

screen_size()

Returns an (width, height) tuple with the screen geometry.

select_mode(modes, current_mode)

Display the mode selector dialog and return the result.

set_read_only(is_readonly)

Set all tabs read-only.

set_theme(theme)

Sets the theme for the REPL and editor tabs.

set_timer(duration, callback)

Set a repeating timer to call “callback” every “duration” seconds.

set_usb_checker(duration, callback)

Sets up a timer that polls for USB changes via the “callback” every “duration” seconds.

set_zoom()

Sets the zoom to current zoom_position level.

setup(breakpoint_toggle, theme)

Sets up the window.

Defines the various attributes of the window and defines how the user interface is laid out.

show_admin(log, settings, packages)

Display the administrative dialog with referenced content of the log and settings. Return a dictionary of the settings that may have been changed by the admin dialog.

show_annotations()

Show the annotations added to the current tab.

show_confirmation(message, information=None, icon=None)

Displays a modal message to the user to which they need to confirm or cancel.

If information is passed in this will be set as the additional informative text in the modal dialog.

Since this mechanism will be used mainly for warning users that something is awry the default icon is set to “Warning”. It’s possible to override the icon to one of the following settings: NoIcon, Question, Information, Warning or Critical.

show_find_replace(find, replace, global_replace)

Display the find/replace dialog. If the dialog’s OK button was clicked return a tuple containing the find term, replace term and global replace flag.

show_message(message, information=None, icon=None)

Displays a modal message to the user.

If information is passed in this will be set as the additional informative text in the modal dialog.

Since this mechanism will be used mainly for warning users that something is awry the default icon is set to “Warning”. It’s possible to override the icon to one of the following settings: NoIcon, Question, Information, Warning or Critical.

size_window(x=None, y=None, w=None, h=None)

Makes the editor 80% of the width*height of the screen and centres it when none of x, y, w and h is passed in; otherwise uses the passed in values to position and size the editor window.

stop_timer()

Stop the repeating timer.

sync_packages(to_remove, to_add, module_dir)

Display a modal dialog that indicates the status of the add/remove package management operation.

property tab_count

Returns the number of active tabs.

toggle_comments()

Toggle comments on/off for all selected line in the currently active tab.

update_debug_inspector(locals_dict)

Given the contents of a dict representation of the locals in the current stack frame, update the debug inspector with the new values.

update_title(filename=None)

Updates the title bar of the application. If a filename (representing the name of the file currently the focus of the editor) is supplied, append it to the end of the title.

wheelEvent(event)

Trap a CTRL-scroll event so the user is able to zoom in and out.

property widgets

Returns a list of references to the widgets representing tabs in the editor.

zoom_in()

Handles zooming in.

zoom_out()

Handles zooming out.

mu.interface.dialogs

Bespoke modal dialogs required by Mu.

class mu.interface.dialogs.AdminDialog(parent=None)

Displays administrative related information and settings (logs, environment variables, third party packages etc…).

settings()

Return a dictionary representation of the raw settings information generated by this dialog. Such settings will need to be processed / checked in the “logic” layer of Mu.

class mu.interface.dialogs.EnvironmentVariablesWidget

Used for editing and displaying environment variables used with Python 3 mode.

class mu.interface.dialogs.FindReplaceDialog(parent=None)

Display a dialog for getting:

• A term to find,

• An optional value to replace the search term,

• A flag to indicate if the user wishes to replace all.

find()

Return the value the user entered to find.

replace()

Return the value the user entered for replace.

replace_flag()

Return the value of the global replace flag.

class mu.interface.dialogs.LogWidget

Used to display Mu’s logs.

class mu.interface.dialogs.MicrobitSettingsWidget

Used for configuring how to interact with the micro:bit:

• Minification flag.

• Override runtime version to use.

class mu.interface.dialogs.ModeItem(name, description, icon, parent=None)

Represents an available mode listed for selection.

class mu.interface.dialogs.ModeSelector(parent=None)

Defines a UI for selecting the mode for Mu.

get_mode()

Return details of the newly selected mode.

select_and_accept()

Handler for when an item is double-clicked.

class mu.interface.dialogs.PackageDialog(parent=None)

Display a dialog to indicate the status of the packaging related changes currently run by pip.

append_data(msg)

Add data to the end of the text area.

end_state()

Set the UI to a valid end state.

finished()

Called when the subprocess that uses pip to install a package is finished.

read_process()

Read data from the child process and append it to the text area. Try to keep reading until there’s no more data from the process.

remove_package()

Take a package from the pending packages to be removed, delete all its assets and schedule the removal of the remaining packages. If there are no packages to remove, move to the finished state.

remove_packages()

Work out which packages need to be removed and then kick off their removal.

run_pip()

Run a pip command in a subprocess and pipe the output to the dialog’s text area.

setup(to_remove, to_add, module_dir)

Create the UI for the dialog.

class mu.interface.dialogs.PackagesWidget

Used for editing and displaying 3rd party packages installed via pip to be used with Python 3 mode.

mu.interface.editor

Contains the customised Scintilla based editor used for textual display and entry.

class mu.interface.editor.CssLexer

Fixes problems with comments in CSS.

description(style)

Ensures “Comment” is returned when the lexer encounters a comment (this is due to a bug in the base class, for which this is a work around).

class mu.interface.editor.EditorPane(path, text, newline='n')

Represents the text editor.

annotate_code(feedback, annotation_type='error')

Given a list of annotations add them to the editor pane so the user can act upon them.

configure()

Set up the editor component.

connect_margin(func)

Connect clicking the margin to the passed in handler function, via a filtering handler that ignores clicks on margin 4.

debugger_at_line(line)

Set the line to be highlighted with the DEBUG_INDICATOR.

dropEvent(event)

Run by Qt when something is dropped on this editor

find_next_match(text, from_line=-1, from_col=-1, case_sensitive=True, wrap_around=True)

Finds the next text match from the current cursor, or the given position, and selects it (the automatic selection is the only available QsciScintilla behaviour). Returns True if match found, False otherwise.

highlight_selected_matches()

Checks the current selection, if it is a single word it then searches and highlights all matches.

Since we’re interested in exactly one word: * Ignore an empty selection * Ignore anything which spans more than one line * Ignore more than one word * Ignore anything less than one word

property label

The label associated with this editor widget (usually the filename of the script we’re editing).

If the script has been modified since it was last saved, the label will end with an asterisk.

range_from_positions(start_position, end_position)

Given a start-end pair, such as are provided by a regex match, return the corresponding Scintilla line-offset pairs which are used for searches, indicators etc.

NOTE: Arguments must be byte offsets into the underlying text bytes.

reset_annotations()

Clears all the assets (indicators, annotations and markers).

reset_check_indicators()

Clears all the text indicators related to the check code functionality.

reset_debugger_highlight()

Reset all the lines so the DEBUG_INDICATOR is no longer displayed.

We need to check each line since there’s no way to tell what the currently highlighted line is. This approach also has the advantage of resetting the whole editor pane.

reset_search_indicators()

Clears all the text indicators from the search functionality.

selection_change_listener()

Runs every time the text selection changes. This could get triggered multiple times while the mouse click is down, even if selection has not changed in itself. If there is a new selection is passes control to highlight_selected_matches.

set_api(api_definitions)

Sets the API entries for tooltips, calltips and the like.

set_theme(theme=<class 'mu.interface.themes.DayTheme'>)

Connect the theme to a lexer and return the lexer for the editor to apply to the script text.

set_zoom(size='m')

Sets the font zoom to the specified base point size for all fonts given a t-shirt size.

show_annotations()

Display all the messages to be annotated to the code.

toggle_comments()

Iterate through the selected lines and toggle their comment/uncomment state. So, lines that are not comments become comments and vice versa.

toggle_line(raw_line)

Given a raw_line, will return the toggled version of it.

wheelEvent(event)

Stops QScintilla from doing the wrong sort of zoom handling.

class mu.interface.editor.PythonLexer(*args, **kwargs)

A Python specific “lexer” that’s used to identify keywords of the Python language so the editor can do syntax highlighting.

keywords(flag)

Returns a list of Python keywords.

mu.interface.panes

Contains code used to populate the various panes found in the user interface (REPL, file list, debug inspector etc…).

class mu.interface.panes.DebugInspector

Presents a tree like representation of the current state of the call stack to the user.

set_font_size(new_size=14)

Sets the font size for all the textual elements in this pane.

set_zoom(size)

Set the current zoom level given the “t-shirt” size.

class mu.interface.panes.DebugInspectorItem(*args)

class mu.interface.panes.FileSystemPane(home)

Contains two QListWidgets representing the micro:bit and the user’s code directory. Users transfer files by dragging and dropping. Highlighted files can be selected for deletion.

disable()

Stops interaction with the list widgets.

enable()

Allows interaction with the list widgets.

on_delete_fail(filename)

Fired when a deletion on the device for the given file failed.

on_get_fail(filename)

Fired when getting the referenced file on the device failed.

on_ls(microbit_files)

Displays a list of the files on the micro:bit.

Since listing files is always the final event in any interaction between Mu and the micro:bit, this enables the controls again for further interactions to take place.

on_ls_fail()

Fired when listing files fails.

on_put_fail(filename)

Fired when the referenced file cannot be copied onto the device.

set_font_size(new_size=14)

Sets the font size for all the textual elements in this pane.

set_zoom(size)

Set the current zoom level given the “t-shirt” size.

show_message(message)

Emits the set_message signal.

show_warning(message)

Emits the set_warning signal.

class mu.interface.panes.JupyterREPLPane(theme='day', parent=None)

REPL = Read, Evaluate, Print, Loop.

Displays a Jupyter iPython session.

setFocus()

Override base setFocus so the focus happens to the embedded _control within this widget.

set_font_size(new_size=14)

Sets the font size for all the textual elements in this pane.

set_theme(theme)

Sets the theme / look for the REPL pane.

set_zoom(size)

Set the current zoom level given the “t-shirt” size.

class mu.interface.panes.LocalFileList(home)

Represents a list of files in the Mu directory on the local machine.

contextMenuEvent(self, QContextMenuEvent)

dropEvent(self, QDropEvent)

on_get(microbit_file)

Fired when the get event is completed for the given filename.

class mu.interface.panes.MicroPythonDeviceFileList(home)

Represents a list of files on a MicroPython device.

contextMenuEvent(self, QContextMenuEvent)

dropEvent(self, QDropEvent)

on_delete(microbit_file)

Fired when the delete event is completed for the given filename.

on_put(microbit_file)

Fired when the put event is completed for the given filename.

class mu.interface.panes.MicroPythonREPLPane(serial, theme='day', parent=None)

REPL = Read, Evaluate, Print, Loop.

This widget represents a REPL client connected to a device running MicroPython.

The device MUST be flashed with MicroPython for this to work.

clear()

Clears the text of the REPL.

context_menu()

Creates custom context menu with just copy and paste.

execute(commands)

Execute a series of commands over a period of time (scheduling remaining commands to be run in the next iteration of the event loop).

keyPressEvent(data)

Called when the user types something in the REPL.

Correctly encodes it and sends it to the connected device.

paste()

Grabs clipboard contents then sends down the serial port.

process_bytes(data)

Given some incoming bytes of data, work out how to handle / display them in the REPL widget.

send_commands(commands)

Send commands to the REPL via raw mode.

set_font_size(new_size=14)

Sets the font size for all the textual elements in this pane.

set_zoom(size)

Set the current zoom level given the “t-shirt” size.

class mu.interface.panes.MuFileList

Contains shared methods for the two types of file listing used in Mu.

show_confirm_overwrite_dialog()

Display a dialog to check if an existing file should be overwritten.

Returns a boolean indication of the user’s decision.

class mu.interface.panes.PlotterPane(parent=None)

This plotter widget makes viewing sensor data easy!

This widget represents a chart that will look for tuple data from the MicroPython REPL, Python 3 REPL or Python 3 code runner and will auto-generate a graph.

add_data(values)

Given a tuple of values, ensures there are the required number of line series, add the data to the line series, update the range of the chart so the chart displays nicely.

process_bytes(data)

Takes raw bytes and, if a valid tuple is detected, adds the data to the plotter.

The the length of the bytes data > 1024 then a data_flood signal is emitted to ensure Mu can take action to remain responsive.

set_theme(theme)

Sets the theme / look for the plotter pane.

class mu.interface.panes.PythonProcessPane(parent=None)

Handles / displays a Python process’s stdin/out with working command history and simple buffer editing.

append(msg)

Append text to the text area.

backspace()

Removes a character from the current buffer – to the left of cursor.

clear_input_line()

Remove all the characters currently in the input buffer line.

context_menu()

Creates custom context menu with just copy and paste.

delete()

Removes a character from the current buffer – to the right of cursor.

finished(code, status)

Handle when the child process finishes.

history_back()

Replace the current input line with the next item BACK from the current history position.

history_forward()

Replace the current input line with the next item FORWARD from the current history position.

insert(msg)

Insert text to the text area at the current cursor position.

keyPressEvent(data)

Called when the user types something in the REPL.

on_process_halt()

Called when the the user has manually halted a running process. Ensures that the remaining data from the halted process’s stdout is handled properly.

When the process is halted the user is dropped into the Python prompt and this method ensures the UI is updated in a clean, non-blocking way.

parse_input(key, text, modifiers)

Correctly encodes user input and sends it to the connected process.

The key is a Qt.Key_Something value, text is the textual representation of the input, and modifiers are the control keys (shift, CTRL, META, etc) also used.

parse_paste(text)

Recursively takes characters from text to be parsed as input. We do this so the event loop has time to respond to output from the process to which the characters are sent (for example, when a newline is sent).

Yes, this is a quick and dirty hack, but ensures the pasted input is also evaluated in an interactive manner rather than as a single-shot splurge of data. Essentially, it’s simulating someone typing in the characters of the pasted text really fast but in such a way that the event loop cycles.

paste()

Grabs clipboard contents then writes to the REPL.

read_from_stdout()

Process incoming data from the process’s stdout.

replace_input_line(text)

Replace the current input line with the passed in text.

set_font_size(new_size=14)

Sets the font size for all the textual elements in this pane.

set_start_of_current_line()

Set the flag to indicate the start of the current line (used before waiting for input).

This flag is used to discard the preceeding text in the text entry field when Mu parses new input from the user (i.e. any text beyond the self.start_of_current_line).

set_zoom(size)

Set the current zoom level given the “t-shirt” size.

start_process(script_name, working_directory, interactive=True, debugger=False, command_args=None, envars=None, runner=None, python_args=None)

Start the child Python process.

Will run the referenced Python script_name within the context of the working directory.

If interactive is True (the default) the Python process will run in interactive mode (dropping the user into the REPL when the script completes).

If debugger is True (the default is False) then the script will run within a debug runner session.

If there is a list of command_args (the default is None), then these will be passed as further arguments into the script to be run.

If there is a list of environment variables, these will be part of the context of the new child process.

If runner is given, this is used as the command to start the Python process.

If python_args is given, these are passed as arguments to the Python runtime used to launch the child process.

try_read_from_stdout()

Ensure reading from stdout only happens if there is NOT already current attempts to read from stdout.

write_to_stdin(data)

Writes data from the Qt application to the child process’s stdin.

mu.interface.themes

Theme related code so Qt changes for each pre-defined theme.

class mu.interface.themes.ContrastTheme

Defines a Python related theme including the various font colours for syntax highlighting.

This is the high contrast theme.

class mu.interface.themes.DayTheme

Defines a Python related theme including the various font colours for syntax highlighting.

This is a light theme.

class mu.interface.themes.Font(color='#181818', paper='#FEFEF7', bold=False, italic=False)

Utility class that makes it easy to set font related values within the editor.

classmethod get_database()

Create a font database and load the MU builtin fonts into it. This is a cached classmethod so the font files aren’t re-loaded every time a font is refereced

load(size=14)

Load the font from the font database, using the correct size and style

property stylename

Map the bold and italic boolean flags here to a relevant font style name.

class mu.interface.themes.NightTheme

Defines a Python related theme including the various font colours for syntax highlighting.

This is the dark theme.

class mu.interface.themes.Theme

Defines a font and other theme specific related information.

mu.interface.themes.should_patch_osx_mojave_font()

OSX mojave and qt5/qtscintilla has a bug where non-system installed fonts are always rendered as black, regardless of the theme color.

This is inconvenient for light themes, but makes dark themes unusable.

Using a system-installed font doesn’t exhibit this behaviour, so update FONT_NAME to use the default terminal font in OSX on mojave.

This patch should be removed once the underlying issue has been resolved

github issue #552

mu.modes

Contains the definitions of the various modes Mu into which Mu can be put. All the core functionality is in the mu.modes.base module.

mu.modes.base

Core functionality and base classes for all Mu’s modes. The definitions of API autocomplete and call tips can be found in the mu.modes.api namespace.

class mu.modes.base.BaseMode(editor, view)

Represents the common aspects of a mode.

actions()

Return an ordered list of actions provided by this module. An action is a name (also used to identify the icon) , description, and handler.

add_plotter()

Mode specific implementation of adding and connecting a plotter to incoming streams of data tuples.

api()

Return a list of API specifications to be used by auto-suggest and call tips.

builtins = None

Symbols to assume as builtins when checking code style.

on_data_flood()

Handle when the plotter is being flooded by data (which usually causes Mu to become unresponsive). In this case, remove the plotter and display a warning dialog to explain what’s happened and how to fix things (usually, put a time.sleep(x) into the code generating the data).

open_file(path)

Some files are not plain text and each mode can attempt to decode them.

When overridden, should return the text and newline convention for the file.

remove_plotter()

If there’s an active plotter, hide it.

Save any data captured while the plotter was active into a directory called ‘data_capture’ in the workspace directory. The file contains CSV data and is named with a timestamp for easy identification.

return_focus_to_current_tab()

After, eg, stopping the plotter or closing the REPL return the focus to the currently-active tab is there is one.

save_timeout = 5

Number of seconds to wait before saving work.

set_buttons(**kwargs)

Given the names and boolean settings of buttons associated with actions for the current mode, toggles them into the boolean enabled state.

stop()

Called if/when the editor quits when in this mode. Override in child classes to clean up state, stop child processes etc.

workspace_dir()

Return the location on the filesystem for opening and closing files.

The default is to use a directory in the users home folder, however in some network systems this in inaccessible. This allows a key in the settings file to be used to set a custom path.

class mu.modes.base.FileManager(port)

Used to manage filesystem operations on connected MicroPython devices in a manner such that the UI remains responsive.

Provides an FTP-ish API. Emits signals on success or failure of different operations.

delete(device_filename)

Delete the referenced file on the device’s filesystem. Emit the name of the file when complete, or emit a failure signal.

get(device_filename, local_filename)

Get the referenced device filename and save it to the local filename. Emit the name of the filename when complete or emit a failure signal.

ls()

List the files on the micro:bit. Emit the resulting tuple of filenames or emit a failure signal.

on_start()

Run when the thread containing this object’s instance is started so it can emit the list of files found on the connected device.

put(local_filename)

Put the referenced local file onto the filesystem on the micro:bit. Emit the name of the file on the micro:bit when complete, or emit a failure signal.

class mu.modes.base.MicroPythonMode(editor, view)

Includes functionality that works with a USB serial based REPL.

add_plotter()

Check if REPL exists, and if so, enable the plotter pane!

add_repl()

Detect a connected MicroPython based device and, if found, connect to the REPL and display it to the user.

find_device(with_logging=True)

Returns the port and serial number for the first MicroPython-ish device found connected to the host computer. If no device is found, returns the tuple (None, None).

on_data_flood()

Ensure the REPL is stopped if there is data flooding of the plotter.

remove_repl()

If there’s an active REPL, disconnect and hide it.

toggle_plotter(event)

Toggles the plotter on and off.

toggle_repl(event)

Toggles the REPL on and off.

mu.modes.base.get_default_workspace()

Return the location on the filesystem for opening and closing files.

The default is to use a directory in the users home folder, however in some network systems this in inaccessible. This allows a key in the settings file to be used to set a custom path.

mu.modes.adafruit

Adafruit mode for CircuitPython.

mu.modes.debugger

The Python 3 debugger mode.

class mu.modes.debugger.DebugMode(editor, view)

Represents the functionality required by the Python 3 visual debugger.

actions()

Return an ordered list of actions provided by this module. An action is a name (also used to identify the icon) , description, and handler.

api()

Return a list of API specifications to be used by auto-suggest and call tips.

button_continue(event)

Button clicked to continue running the script.

button_step_in(event)

Button clicked to step into the current block of code.

button_step_out(event)

Button clicked to step out of the current block of code.

button_step_over(event)

Button clicked to step over the current line of code.

button_stop(event)

Button clicked to stop the current script and return to Python3 mode.

debug_on_bootstrap()

Once the debugger is bootstrapped ensure all the current breakpoints are set. Do not set breakpoints (and remove the marker) if:

• The marker is not visible (the line is -1)

• The marker is not a duplicate of an existing line.

• The line with the marker is not a valid breakpoint line.

debug_on_breakpoint_clear(breakpoint)

Handle the clearing of the referenced breakpoint. Currently an unimplemented extra feature.

debug_on_breakpoint_disable(breakpoint)

Handle when a breakpoint is disabled.

debug_on_breakpoint_enable(breakpoint)

Handle when a breakpoint is enabled.

debug_on_breakpoint_ignore(breakpoint, count)

Handle when a breakpoint is to be ignored by the debugger. Currently an unimplemented extra feature.

debug_on_call(args)

Handle when the debugger has called a function with the referenced args. Make sure the debugger steps into the function.

debug_on_error(message)

Handle when the debugger sends an error message.

debug_on_exception(name, value)

Handle when the debugger encounters a named exception with an associated value. Clear the highlighted line and allow the script to run until the end so the error message is printed to stdout.

debug_on_fail(message)

Called when, for any reason, the debug client was unable to connect to the debug runner. On a Raspberry Pi this is usually because it’s an underpowereed machine and it takes time to start the debug runner process. (However, the debug client waits for 10 seconds for the runner to start.)

debug_on_finished()

Called when the runner has completed running the script to be debugged.

debug_on_info(message)

Handle when the debugger sends an informative textual message.

debug_on_line(filename, line)

Handle when the debugger has moved to the referenced line in the file.

debug_on_postmortem(args, kwargs)

Handle when something catastrophic happens to the debugger.

debug_on_restart()

Handle when the debugger restarts. Currenty an unimplemented extra feature.

debug_on_return(return_value)

Handle when the debugger returns from a function call with the referenced return value. Make sure the debugger steps out of the function to the caller.

debug_on_stack(stack)

Handle when the debugger sends an updated stack.

debug_on_warning(message)

Handle when the debugger sends a warning message.

finished()

Called when the debugged Python process is finished.

start()

Start debugging the current script.

stop()

Stop the debug runner and reset the UI.

toggle_breakpoint(line, tab)

Toggle a breakpoint in the debugger.

mu.modes.microbit

The original BBC micro:bit mode.

class mu.modes.microbit.DeviceFlasher(paths_to_microbits, python_script, path_to_runtime)

Used to flash the micro:bit in a non-blocking manner.

run()

Flash the device.

class mu.modes.microbit.MicrobitMode(editor, view)

Represents the functionality required by the micro:bit mode.

actions()

Return an ordered list of actions provided by this module. An action is a name (also used to identify the icon) , description, and handler.

add_fs()

Add the file system navigator to the UI.

api()

Return a list of API specifications to be used by auto-suggest and call tips.

copy_main()

If the attribute self.python_script contains any code, copy it onto the connected micro:bit as main.py, then restart the board (CTRL-D).

flash()

Takes the currently active tab, compiles the Python script therein into a hex file and flashes it all onto the connected device.

WARNING: This method is getting more complex due to several edge cases. Ergo, it’s a target for refactoring.

flash_failed(error)

Called when the thread used to flash the micro:bit encounters a problem.

flash_finished()

Called when the thread used to flash the micro:bit has finished.

fs = None

Reference to filesystem navigator.

on_data_flood()

Ensure the Files button is active before the REPL is killed off when a data flood of the plotter is detected.

open_file(path)

Tries to open a MicroPython hex file with an embedded Python script.

Returns the embedded Python script and newline convention.

remove_fs()

Remove the file system navigator from the UI.

toggle_files(event)

Check for the existence of the REPL or plotter before toggling the file system navigator for the micro:bit on or off.

toggle_plotter(event)

Check for the existence of the file pane before toggling plotter.

toggle_repl(event)

Check for the existence of the file pane before toggling REPL.

mu.modes.pygamezero

The Pygame Zero / pygame mode.

class mu.modes.pygamezero.PyGameZeroMode(editor, view)

Represents the functionality required by the PyGameZero mode.

actions()

Return an ordered list of actions provided by this module. An action is a name (also used to identify the icon) , description, and handler.

api()

Return a list of API specifications to be used by auto-suggest and call tips.

play_toggle(event)

Handles the toggling of the play button to start/stop a script.

run_game()

Run the current game.

show_fonts(event)

Open the directory containing the font assets used by PyGame Zero.

This should open the host OS’s file system explorer so users can drag new files into the opened folder.

show_images(event)

Open the directory containing the image assets used by PyGame Zero.

This should open the host OS’s file system explorer so users can drag new files into the opened folder.

show_music(event)

Open the directory containing the music assets used by PyGame Zero.

This should open the host OS’s file system explorer so users can drag new files into the opened folder.

show_sounds(event)

Open the directory containing the sound assets used by PyGame Zero.

This should open the host OS’s file system explorer so users can drag new files into the opened folder.

stop_game()

Stop the currently running game.

mu.modes.python3

The Python 3 editing mode.

class mu.modes.python3.KernelRunner(cwd, envars)

Used to control the iPython kernel in a non-blocking manner so the UI remains responsive.

start_kernel()

Create the expected context, start the kernel, obtain a client and emit a signal when both are started.

stop_kernel()

Clean up the context, stop the client connections to the kernel, affect an immediate shutdown of the kernel and emit a “finished” signal.

class mu.modes.python3.PythonMode(editor, view)

Represents the functionality required by the Python 3 mode.

actions()

Return an ordered list of actions provided by this module. An action is a name (also used to identify the icon) , description, and handler.

add_plotter()

Add a plotter pane.

add_repl()

Create a new Jupyter REPL session in a non-blocking way.

api()

Return a list of API specifications to be used by auto-suggest and call tips.

debug(event)

Debug the script using the debug mode.

on_data_flood()

Ensure the process (REPL or runner) causing the data flood is stopped before the base on_data_flood is called to turn off the plotter and tell the user what to fix.

on_kernel_start(kernel_manager, kernel_client)

Handles UI update when the kernel runner has started the iPython kernel.

on_kernel_stop()

Handles UI updates for when the kernel runner has shut down the running iPython kernel.

remove_plotter()

Remove the plotter pane, dump data and clean things up.

remove_repl()

Remove the Jupyter REPL session.

run_script()

Run the current script.

run_toggle(event)

Handles the toggling of the run button to start/stop a script.

stop_script()

Stop the currently running script.

toggle_plotter()

Toggles the plotter on and off.

toggle_repl(event)

Toggles the REPL on and off

mu.resources

Contains utility functions for working with binary assets used by Mu (mainly images).

mu.resources.load_font_data(name)

Load the (binary) content of a font as bytes

mu.resources.load_icon(name)

Load an icon from the resources directory.

mu.resources.load_pixmap(name)

Load a pixmap from the resources directory.

mu.resources.load_stylesheet(name)

Load a CSS stylesheet from the resources directory.

mu.resources.path(name, resource_dir='images/')

Return the filename for the referenced image.