Functions in the pytch module¶

Various functions, which do not need to refer to a particular Sprite, are available in the pytch module. For convenience, though, they are also available, where it makes sense, as methods on Sprite and Stage.

Pausing a script¶

pytch.wait_seconds(n_seconds)¶: The underlying function which pauses a script. See the documentation in the Sprites section for details.

Creating a clone¶

pytch.create_clone_of(thing): The underlying function which creates a new clone of thing. See the documentation in the Sprites section for recommended usage.

Sounds¶

Most sound functionality is accessed through Sprite methods. See the documentation in the Sprites section for details.

The underlying function to stop all sounds from playing is in the pytch module:

pytch.stop_all_sounds()¶: Stop all sounds from playing.

However, usually you will stop all sounds by using the matching Sprite method or Stage method.

Asking the user a question¶

This is usually done with a Sprite method, but the following function is also available if required.

pytch.ask_and_wait(prompt)¶

Ask the user a question, using a pop-up input box. The given prompt (if not None) is shown as part of the input box. The script calling pytch.ask_and_wait() pauses until the user answers the question.

The user’s answer is returned to the calling script.

If a question is already being asked, the new question is put in a queue, to be asked once all existing questions have been answered by the user.

Sensing whether a particular key is pressed¶

pytch.key_pressed(key_name)¶: The underlying function which detects whether a key is pressed. See details under the corresponding Sprite method.

Broadcasting messages¶

pytch.broadcast(message_string)¶
pytch.broadcast_and_wait(message_string)¶: The underlying functions which broadcast messages. See details under the corresponding Sprite methods: broadcast() and broadcast_and_wait().

Stopping all scripts¶

pytch.stop_all()¶: The underlying function which stops all scripts. See details under the corresponding Sprite method.

Variable watchers¶

Note

This is an experimental part of Pytch. In future versions of Pytch, we might change the way variable watchers work, depending on user feedback.

In Scratch, you can “show” a variable, either by ticking a box in the UI, or by using the show variable MY-VARIABLE block. Pytch does not have a box to tick, but does have the pytch.show_variable() function.

The simplest way to show a variable is to use self.show_variable() in a Sprite or Stage script. See the Sprite documentation or Stage documentation for details. If needed, though, the general pytch.show_variable() version is available, and can be used like this:

@pytch.when_I_receive("set-up-score")
def set_up_score(self):
    self.score = 0
    pytch.show_variable(self, "score")

As this example shows, you give Pytch two pieces of information: you tell it who owns the variable you want to show (here, the self sprite), and you tell it the name of the variable, as a string (here, "score"). In this simple form, the Stage will show a small ‘watcher’ box with a label and the variable’s value. By default, the label is the same as the variable name, and the watcher appears in the top-left corner of the stage.

You can tell Pytch where to show the watcher by giving it more information. You can choose whether to fix the left or right edge of the box, by giving the stage x-coordinate where you want that edge to be. You can separately choose whether to fix the top or bottom edge, by giving a stage y-coordinate. You can tell also Pytch what label to use, instead of the variable name.

To pass any of these arguments, use Python’s named argument syntax. In this example, we pass label, top, and right as named arguments:

pytch.show_variable(self, "score", label="SCORE:", top=176, right=236)

This will set up a watcher for self.score, showing the value with the label SCORE:, a little way in from the top-right corner of the stage.

As a special case, to show a global variable, use None as the owner, for example:

pytch.show_variable(None, "high_score")

To remove a variable watcher, use pytch.hide_variable(), which takes the same owner and attribute_name arguments. For example:

pytch.hide_variable(self, "score")

Sprite variables and clones¶

In Scratch, you can only show the original instance’s value of a “for this Sprite only” variable. In Pytch, you can show a clone’s value of the variable. When a clone is running a method, self refers to that clone.

When a clone is deleted, any variable watchers showing variables belonging to that clone are removed.

Project-level variables¶

Sometimes you will have a variable at the top level of your project, outside any Sprite or Stage. These are also called “global” variables. As a special case, to show these variables, you can use None as the first argument to show_variable(), for example:

score = 100

class Ship(pytch.Sprite):
    # [...]
    @pytch.when_this_sprite_clicked
    def show_score(self):
        pytch.show_variable(None, "score")

Advanced usage¶

Most Pytch programs will not need to use the techniques in this section.

In fact any attribute will do, so you can for example give the name of a property to compute the value dynamically. This property will be accessed 60 times a second so should not do any heavy computation.

So far we have given examples where the “variable owner”, i.e., the first argument to pytch.show_variable(), is a Sprite, or your Stage, or None to mean a global variable. It can also be any other object in your program, for instance a non-Actor class:

class GameState:
    score = 100

class Ship(pytch.Sprite):
    # [...]
    @pytch.when_this_sprite_clicked
    def show_score(self):
        pytch.show_variable(GameState, "score")

Suspiciously long-running loops outside event handlers¶

Most users will not need to use the functionality described in this section.

In Pytch, it is common to have an infinite loop (e.g., while True) inside an event handler. Such a loop runs at one iteration per display frame.

But an infinite loop at the top level of your program will prevent your project even starting. For example,

import pytch

while True:
    pass

Pytch detects this situation, and raises an error. It is impossible for Pytch to tell when a loop is truly infinite, though, and so it raises this error if more than 1000 iterations of loops happen when launching your program. Rarely, you might genuinely have a program which needs a longer-running loop at top-level. If so, you can raise the limit as follows.

pytch.set_max_import_loop_iterations(n_iters)¶: Set the maximum number of loop iterations permitted at top level before an error is raised.

For example:

import pytch

# Without the following line, the loop below would raise an error.
pytch.set_max_import_loop_iterations(2000)

for i in range(1200):
    pass