Python modules make it easy to group related code into .py files that you can reference in your program, main.py. You do this by using an import statement that makes the module or or specific parts of it available to your program.


If you are writing a module yourself, you can create a new module in the editor using the Create file button on the Project tab. Often you might use a module written by someone else, for example a module provided with a micro:bit accessory, or by a teacher or other educator to help with an activity.


This article shows how to add a third-party module to the editor. The example module we use is called flipper. It provides a function called flip that can flip images (like Image.HEART), turning them upside down. Save this file as flipper.py on your computer.


If you are developing a Python module for the micro:bit (e.g. for an accessory), please add magic header information that this is a microbit-module and give it a name and version number in the format major.minor.patch e.g. flipper@0.1.0. This way the editor will add the module alongside the users code automatically if it is dragged and dropped into the editor. You can open a main Python file and a module in one step if you use this technique. Otherwise, by default, users will be prompted to replace their main.py file with your module.



Add the module to your project

Drag and drop flipper.py from your Downloads folder onto the editor window or use the Open button and choose the file from the dialog. You will see a confirmation dialog:



Some modules may need an extra step. If the dialog suggests replacing your main.py code then you can use the cog to add the file alongside main.py instead:



Click Confirm, then you will see a message saying "Added file flipper.py". You can switch to the Project tab then you can see the new module in the file list (you can remove it there if you need to). You can now call the module from your main.py program.



Calling the module from main.py

In the code editor import everything from the microbit module and from your newly added flipper module:


from microbit import *
from flipper import *


Now create a program that uses the flip function from your module.


from microbit import *
from flipper import *

image = Image.HAPPY
while True:
    if accelerometer.was_gesture("shake"):
        image = flip(image)
        display.show(image)
        sleep(100)

This program uses flip to flip the image when you shake the micro:bit. You can download this program from the attachment below (main.py).



Troubleshooting

Check the module file name. For the import statement to work it needs to be correct when you add the file to the editor. If you have more than one copy of the file in your downloads folder ensure you use the one with the matching name.



Looking inside the module

We've included the example code for the flipper module below as an example for module authors.


# microbit-module: flipper@0.1.0
from microbit import Image


def flip(source):
    """Create an upside down copy of an image.
    
    :param source: The image to flip, for example ``Image.HEART``.
    :return: A copy of the image flipped on the y-axis.
    """
    width = source.width()
    height = source.height()
    target = Image(width, height)
    for x in range(0, width):
        for y in range(0, height):
            target.set_pixel(x, height - y - 1, source.get_pixel(x, y))
    return target


By default, module code with the magic header comments is not shown to uses. If they open the file they will see a placeholder:


Placeholder instead of code editor showing text "This file is a third-party module and is not intended to be edited" and module metadata