README.md

testcell

TL;DR: %%testcell prevents your testing cells from affecting the global namespace.

The Python cell magic %%testcell executes a cell without polluting the notebook’s global namespace. This is useful whenever you want to test your code without having any of the local variables escape that cell.

What’s happening under the hood is that your cell code, before being executed, is wrapped in a temporary function that will be deleted after execution. To give you the feeling of seamless integration the last statement is optionally returned like it happens in a normal cell.

WARNING: this don’t protect you from the side effects of your code like deleting a file or mutating the state of a global variable.

Install

pip install testcell

How to use

just import it with import testcell and then use the %%testcell cell magic.

%%testcell
a = "'a' is not polluting global scope"
a

"'a' is not polluting global scope"

assert 'a' not in locals()

What is happening under the hood is that %%testcell wraps your cell’s code with a function, execute it and then deletes it. Adding the verbose keywork will print which code will be executed.

NOTE: The actual cell code is enclosed within BEGIN and END comment blocks for improved readability.

%%testcell verbose
a = "'a' is not polluting global scope"
a

### BEGIN
def _test_cell_():
    #| echo: false
    a = "'a' is not polluting global scope"
    return a # %%testcell
try:
    _ = _test_cell_()
finally:
    del _test_cell_
_ # This will be added to global scope
### END

"'a' is not polluting global scope"

If you’re just interested in seeing what will be executed, but actually not executing it, you ca use dryrun option:

%%testcell dryrun
a = "'a' is not polluting global scope"
a

### BEGIN
def _test_cell_():
    #| echo: false
    a = "'a' is not polluting global scope"
    return a # %%testcell
try:
    _ = _test_cell_()
finally:
    del _test_cell_
if _ is not None: display(_)
### END

If you add a semicolon ; at the end of your last statement no return statement is added and nothing is displayed like a normal jupyter cell.

%%testcell verbose
a = "'a' is not polluting global scope"
a;

### BEGIN
def _test_cell_():
    #| echo: false
    a = "'a' is not polluting global scope"
    a;
try:
    _ = _test_cell_()
finally:
    del _test_cell_
_ # This will be added to global scope
### END

testcell works seamlessly with existing print or displaystatements on last line:

%%testcell verbose
a = "'a' is not polluting global scope"
print(a)

### BEGIN
def _test_cell_():
    #| echo: false
    a = "'a' is not polluting global scope"
    return print(a) # %%testcell
try:
    _ = _test_cell_()
finally:
    del _test_cell_
_ # This will be added to global scope
### END
'a' is not polluting global scope

Moreover, thanks to ast, it properly deals with complex situations like comments on the last line and multi lines statements

%%testcell verbose
a = "'a' is not polluting global scope"
(a,
 True)
# this is a comment on last line

### BEGIN
def _test_cell_():
    #| echo: false
    a = "'a' is not polluting global scope"
    return (a,
     True) # %%testcell
try:
    _ = _test_cell_()
finally:
    del _test_cell_
_ # This will be added to global scope
### END

("'a' is not polluting global scope", True)

Run in isolation

%%testcelln is a shortcut for %%testcell noglobals and executes the cell in complete isolation from the global scope. This is very useful when you want to ensure that global variables or namespaces are not accessible within the cell.

aaa = 'global variable'

%%testcell
'aaa' in globals()

True

%%testcell noglobals
'aaa' in globals()

False

%%testcelln
'aaa' in globals()

False

%%testcelln
globals().keys()

dict_keys(['__builtins__'])

With %%testcelln inside the cell, you’ll be able to access only to __builtins__ (aka: standard python’s functions). It behaves like a notebook-in-notebook.

%%testcell
def my_function(x):
    print(aaa) # global variable
    return x

try:
    my_function(123)
except Exception as e:
    print(e)

global variable

%%testcelln
def my_function(x):
    print(aaa) # global variable
    return x

try:
    my_function(123)
except Exception as e:
    print(e)

name 'aaa' is not defined

As you can see from this last example, %%testcelln helps you to identify that my_function refers global variable aaa.

IMPORTANT: this is just wrapping your cell and so it’s still running on your main kernel. If you modify variables that has been created outside of this cell (aka: if you have side effects) this will not protect you.

aaa

'global variable'

%%testcell 
# WARNING: this will alter the state of global variable:
globals().update({'aaa' : 'modified global variable'});

aaa

'modified global variable'

del aaa

Links:

• PROJECT PAGE: https://github.com/artste/testcell
• DOCUMENTATION: https://artste.github.io/testcell
• PYPI: https://pypi.org/project/testcell
• COLAB DEMO: testcell_demo.ipynb
• KAGGLE SAMPLE NOTEBOOK: https://www.kaggle.com/artste/introducing-testcell

Todo:

• Install as a plugin to enable it by default like other cell’s magic.