Warning

Most of the documentation was written prior to version 0.5 and needs to be updated. This work has now started for version 0.7 and we aim to have it completed before version 0.8 is available.

Editor plugins

As mentioned in Using with an editor or IDE, one can launch a program by writing an auxiliary file that uses friendly.run(). Perhaps your favourite editor support plugins that can replace such auxiliary scripts by a menu item or an additional button. If that is the case, we encourage you to do so, and let us know so that we can make other users aware.

friendly.run() makes use of another function called exec_code() found in editors_helpers.py. This file contains additional functions that might be useful to turn into plugins, for example enabling to check the syntax without actually running a program.

Again, if you do so, let us know, and we will add any function you use to the public API. In the meantime, here’s some information about these functions.

editors_helpers.py

The functions in this module have been created so that user editors/IDEs could use Friendly without having to change the content of their own programs.

None of these are part of the public API.

If you make use of any other function here, please file an issue so it can be determined if it should be added to the public API.

check_syntax(*, source=None, filename='Fake_filename', path=None, include=None, lang=None)

This uses Python’s compile() builtin which does some analysis of its code argument and will raise an exception if it identifies some syntax errors, but also some less common “overflow” and “value” errors.

Note that there are a few syntax errors that are not caught by this, as they are identified by Python very late in its execution process. See for example this blog post

This function can either be used on a file, using the path argument, or on some code passed as a string, using the source argument. For the latter case, one can also specify a corresponding filename: this could be useful if this function is invoked from a GUI-based editor.

Note that the path argument, if provided, takes precedence over the source argument.

Two additional named arguments, include and lang, can be provided to temporarily set the values to be used during this function call. The original values are restored at the end.

If friendly exception hook has not been set up prior to calling check_syntax, it will only be used for the duration of this function call.

Returns a tuple containing a code object and a filename if no exception has been raised, False otherwise.

Return type

Union[bool, Tuple[Any, str]]

exec_code(*, source=None, path=None, include=None, lang=None)

This uses check_syntax to see if the code is valid and, if so, executes it into a globals dict containing only {"__name__": "__main__"}. If no SyntaxError exception is raised, this dict is returned; otherwise, an empty dict is returned.

It can either be used on a file, using the path argument, or on some code passed as a string, using the source argument.

Note that the path argument, if provided, takes precedence over the source argument.

Two additional named arguments, include and lang, can be provided to temporarily set the values to be used during this function call. The original values are restored at the end.

If friendly exception hook has not been set up prior to calling check_syntax, it will only be used for the duration of this function call.

Return type

Dict