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 - a “micro” Python editor for beginner programmers.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

Based upon work done for Puppy IDE by Dan Pope, Nicholas Tollervey and Damien George.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class mu.app.AnimatedSplash(animation, parent=None)

An animated splash screen for gifs. Includes a text area for logging output.

draw_log(text)

Draw the log entries onto the splash screen. Will only display the last self.log_lines number of log entries. The logs will be displayed at the bottom of the splash screen, justified left.

draw_text(text)

Draw text into splash screen.

failed(text)

Something has gone wrong during start-up, so signal this, display a helpful message along with instructions for what to do.

set_frame()

Update the splash screen with the next frame of the animation.

exception mu.app.MutexError

class mu.app.SharedMemoryMutex

Simple wrapper around the QSharedMemory object, adding a context handler which uses the built in Semaphore as a locking mechanism and raises an error if the shared memory object is already in use

TODO: The *nix implementation doesn’t release the shared memory if a process attached to it crashes. There is code to attempt to detect this but it doesn’t seem worth implementing for the moment: we’re only talking about a page at most.

class mu.app.StartupWorker

A worker class for running blocking tasks on a separate thread during application start-up.

The animated splash screen will be shown until this thread is finished.

run()

Blocking and long running tasks for application startup should be called from here.

mu.app.check_only_running_once()

If the application is already running log the error and exit

mu.app.excepthook(*exc_args)

Log exception and exit cleanly.

mu.app.is_linux_wayland()

Checks environmental variables to try to determine if Mu is running on wayland.

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.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

Based upon work done for Puppy IDE by Dan Pope, Nicholas Tollervey and Damien George.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class mu.logic.Device(vid, pid, port, serial_number, manufacturer, long_mode_name, short_mode_name, board_name=None)

Device object, containing both information about the connected device, the port it’s connected through and the mode it works with.

property name

Returns the device name.

class mu.logic.DeviceList(modes, parent=None)

add_device(new_device)

Add a new device to the device list, maintains alphabetical ordering

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.

data(index, role)

Reimplements QAbstractListModel.data(): returns data for the specified index and role. In this case only implmented for ToolTipRole and DisplayRole

remove_device(device)

Remove the given device from the device list

rowCount(parent)

Number of devices

class mu.logic.Editor(view)

Application logic for the editor itself.

ask_to_change_mode(new_mode, mode_name, heading)

Open a dialog asking the user, whether to change mode from mode_name to new_mode. The dialog can be customized by the heading-parameter.

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.

connect_to_status_bar(status_bar)

Connect the editor with the Window-statusbar. Should be called after Editor.setup(), to ensure modes are initialized

debug_toggle_breakpoint(margin, line, modifiers)

How to handle the toggling of a breakpoint.

device_changed(device)

Slot for receiving signals that the current device has changed. If the device change requires mode change, the user will be asked through a dialog.

direct_load(path)

For loading files passed from command line or the OS launch.

find_again(forward=True)

Handle find again (F3 and Shift+F3) functionality.

find_again_backward(forward=False)

Handle find again backward (Shift+F3) functionality.

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

has_python_extension(filename)

Check whether the given filename matches recognized Python extensions.

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.

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

A debug client for the Mu editor.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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.

A debug runner for the Mu editor.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

exception mu.debugger.runner.ClientClose

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

class mu.debugger.runner.DebugState(value)

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.

Contains the main Window definition for Mu’s UI.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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.

addTab(widget, title)

Add a new tab to the switcher

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.

device_connected(device)

Show a tooltip whenever a new device connects

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(parent=None)

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(name, connection, data_flood_handler)

Adds a plotter that reads data from a serial connection.

add_micropython_repl(name, connection)

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(interpreter, script_name, working_directory, interactive=False, debugger=False, command_args=None, envars=None, python_args=None)

Display console output for the interpreter with the referenced pythonpath running the referenced 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 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_snek_repl(name, connection, force_interrupt=True, wait_input=False)

Adds a Snek based 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.

connect_find_again(handlers, shortcut)

Create keyboard shortcuts and associate them with handlers for doing a find again in forward or backward direction. Any given shortcut will be used for forward find again, while Shift+shortcut will find again backwards.

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.

copy_to_repl()

Copies currently selected text in the editor, into the active REPL widget and sets focus to the REPL widget. The final line pasted into the REPL waits for RETURN to be pressed by the user (this appears to be the default behaviour for pasting into the REPL widget).

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.

handle_python_anywhere_complete(domain)

Displays a confirmation that all the API calls completed OK and provides a link to the user’s website.

handle_python_anywhere_error(error_message)

Display a friendly message to indicate a problem was encountered when uploading to PythonAnywhere.

hide_device_selector()

Hides the device selector in the status bar

highlight_text(target_text, forward=True)

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_context_menu()

Called when a user right-clicks on an editor pane.

If the REPL is active AND there is selected text in the current editor pane, modify the default context menu to include a paste to REPL option. Otherwise, just display the default context menu.

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.

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_checker_icon(icon)

Set the status icon to use on the check button

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, mode, device_list)

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_device_selector()

Reveals the device selector in the status bar

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.

If the X or Y value will be off the screen, these are reset to None (thus stopping the window being drawn in a hard-to-reach place). See issue #1613 for context.

stop_timer()

Stop the repeating timer.

sync_packages(to_remove, to_add)

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.

upload_to_python_anywhere(instance, username, token, app_name, files)

Show a progress dialog as the files are uploaded to PythonAnywhere.

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.

UI related code for dialogs used by Mu.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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

Used for configuring how to interact with the ESP:

• Override MicroPython.

append_data(msg)

Add data to the end of the text area.

esptool_finished(exitCode, exitStatus)

Called when the subprocess that executes ‘esptool.py 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.

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

Used for manually setting the locale (and thus the language) used by Mu.

get_locale()

Return the user-selected language code.

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 the output of the pip commands needed to remove or install packages.

Because the QProcess mechanism we’re using is asynchronous, we have to manage the pip requests via pip_queue. When one request is signalled as finished we start the next.

finish()

Set the UI to a valid end state.

next_pip_command()

Run the next pip command, finishing if there is none.

run_pip(command, packages)

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

setup(to_remove, to_add)

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.

class mu.interface.dialogs.PythonAnywhereWidget

For configuring the user’s username and API token for interacting with the PythonAnywhere API to deploy a website from web mode.

valid_instances = ['www', 'eu']

Valid server hosting instances for PythonAnywhere.

mu.interface.editor

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

UI related capabilities for the text editor widget embedded in each tab in Mu.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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.

contextMenuEvent(event)

A context menu (right click) has been actioned.

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

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.

property title

The title 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.

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…).

Contains the UI classes used to populate the various panes used by Mu.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class mu.interface.panes.DebugInspector

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

record_collapsed(index)

Remove collapsed dicts from set, so they render collapsed.

record_expanded(index)

Keep track of expanded dicts for displaying in debugger.

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(*args, **kwargs)

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(connection, 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.

delete_selection()

Returns true if deletion happened, returns false if there was no selection to delete.

insertFromMimeData(source)

Insert mime data by sending it to the REPL

keyPressEvent(data)

Called when the user types something in the REPL.

Correctly encodes it and sends it to the connected device.

mouseReleaseEvent(mouseEvent)

Called whenever a user have had a mouse button pressed, and releases it. We pass it through to the normal way Qt handles button pressed, but also sends as cursor movement signal to the device (except if a selection is made, for selections we first move the cursor on deselection)

move_cursor_to(new_position)

Move the cursor, by sending vt100 left/right signals through serial. The Qt cursor is first returned to the known location of the device cursor. Then the appropriate number of move left or right signals are send. The Qt cursor is not moved to the new_position here, but will be moved once receiving a response (in process_tty_data).

process_tty_data(data)

Given some incoming bytes of data, work out how to handle / display them in the REPL widget. If received input is incomplete, stores remainder in self.unprocessed_input.

Updates the self.device_cursor_position to match that of the device for every input received.

set_devicecursor_to_qtcursor()

Call this whenever the cursor has been moved by the user, to send the cursor movement to the device.

set_font_size(new_size=14)

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

set_qtcursor_to_devicecursor()

Resets the Qt TextCursor to where we know the device has the cursor placed.

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_tty_data(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.

insertFromMimeData(source)

Insert mime data by sending it to the REPL

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.

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(interpreter, script_name, working_directory, interactive=True, debugger=False, command_args=None, envars=None, python_args=None)

Start the child Python process.

Will use the referenced interpreter to run the 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 python_args is given, these are passed as arguments to the Python interpreter 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.

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

REPL = Read, Evaluate, Print, Loop.

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

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

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

insertFromMimeData(source)

Insert mime data by sending it to the REPL

keyPressEvent(data)

Called when the user types something in the REPL.

Correctly encodes it and sends it to the connected device.

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_devicecursor_to_qtcursor()

Call this whenever the cursor has been moved by the user, to send the cursor movement to the device.

mu.interface.themes

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

Theme and presentation related code for the Mu editor.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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

Contains the base classes for Mu editor modes.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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.

activate()

Executed when the mode is activated

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.

assets_dir(asset_type)

Determine (and create) the directory for a set of assets

This supports the [Images] and [Sounds] &c. buttons in pygamezero mode and possibly other modes, too.

If a tab is current and has an active file, the assets directory is looked for under that path; otherwise the workspace directory is used.

If the assets directory does not exist it is created

builtins = None

Symbols to assume as builtins when checking code style.

deactivate()

Executed when the mode is activated

device_changed(new_device)

Invoked when the user changes device.

ensure_state()

Executed when the mode is finished setting up. Used to ensure button / UI state according to current state of settings.

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.

write_plotter_data_to_csv(csv_filepath)

Write any plotter data out to a CSV file when the plotter is closed

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, target=None)

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.

activate()

Invoked whenever the mode is activated.

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.

compatible_board(port)

A compatible board must match on vendor ID, but only needs to match on product ID or manufacturer ID, if they are supplied in the list of valid boards (aren’t None).

deactivate()

Invoked whenever the mode is deactivated.

device_changed(new_device)

Invoked when the user changes device.

find_devices(with_logging=True)

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

on_data_flood()

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

remove_plotter()

Remove plotter pane. Disconnects serial connection to device.

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.

class mu.modes.base.REPLConnection(port, baudrate=115200)

close()

Close and clean up the currently open serial link.

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

open()

Open the serial link

send_commands(commands)

Send commands to the REPL via raw mode.

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

CircuitPython mode for Adafruit boards (and others).

A mode for working with Circuit Python boards.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class mu.modes.circuitpython.CircuitPythonMode(editor, view)

Represents the functionality required by the CircuitPython 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.

compatible_board(port)

Use adafruit_board_toolkit to find out whether a board is running CircuitPython. The toolkit sees if the CDC Interface name is appropriate.

connected = True

is the board connected.

force_interrupt = False

NO keyboard interrupt on serial connection.

save_timeout = 0

No auto-save on CP boards. Will restart.

workspace_dir()

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

mu.modes.debugger

The Python 3 debugger mode.

The mode Mu is is when it’s debugging a Python 3 script.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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.

disable_buttons()

Disable all debug control buttons except ‘stop’.

disable_buttons_later(*, milliseconds=100)

Set a timer to disable all debug control buttons except ‘stop’.

enable_buttons()

Enable all debug control buttons except ‘stop’: if the timer started in disable_buttons_later is active, stops it and does nothing else.

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.

The mode for working with the BBC micro:bit. Contains most of the origial functionality from Mu when it was only a micro:bit related editor.

Copyright (c) 2015-2021 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class mu.modes.microbit.DeviceFlasher(path_to_microbit, python_script=None, path_to_runtime=None)

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

run()

Flash the device. If we are sending a custom hex we need to manually read it and copy it into the micro:bit drive otherwise use uFlash.

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(script)

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

deactivate()

Invoked whenever the mode is deactivated.

device_changed(new_device)

Invoked when the user changes device.

find_microbit()

Finds a micro:bit path, serial port and board ID.

flash()

Performs multiple checks to see if it needs to flash MicroPython into the micro:bit and then sends via serial the Python script from the currently active tab. In some error cases it attaches the code directly into the MicroPython hex and flashes that (this method is much slower and deprecated).

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

flash_and_send(script, microbit_path, rt_path=None)

Start the MicroPython hex flashing process in a new thread with a custom hex file, or the one provided by uFlash. Then send the user script via serial.

flash_attached(script, microbit_path)

Start the MicroPython hex flashing process in a new thread with the hex file provided by uFlash and the script added to the filesystem in the hex.

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.

get_device_micropython_version()

Retrieves the MicroPython version from a micro:bit board. Errors bubble up, so caller must catch them.

minify_if_needed(python_script_bytes)

Minify the script if is too large to fit in flash via uFlash appended method. Raises exceptions if minification fails or cannot be performed.

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.

The Pygame Zero mode for the Mu editor.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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.

The Python3 mode for the Mu editor.

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class mu.modes.python3.KernelRunner(kernel_name, 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.MuKernelManager(*args, **kwargs)

start_kernel(**kw)

Starts a kernel on this host in a separate process.

Subclassed to allow checking that the kernel uses the same Python as Mu itself.

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

Copyright (c) 2015-2017 Nicholas H.Tollervey and others (see the AUTHORS file).

Based upon work done for Puppy IDE by Dan Pope, Nicholas Tollervey and Damien George.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

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_movie(name)

Load an animated GIF from the resources directory.

mu.resources.load_pixmap(name, size=None)

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/', ext='')

Return the filename for the referenced image.