Metadata-Version: 2.1
Name: testcell
Version: 0.0.5
Summary: testcell prevents your testing cells from affecting the global namespace
Home-page: https://github.com/artste/testcell
Author: Stefano Giomo
Author-email: artste@users.noreply.github.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: Pillow ; extra == 'dev'
Requires-Dist: matplotlib ; extra == 'dev'

# testcell

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

**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 variables. 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
line is optionally wrapped with a `display` statement if needed.

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

``` sh
pip install testcell
```

## How to use

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

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

    "'a' is not polluting global scope"

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

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


    ### BEGIN
    def _test_cell_():
        #| echo: false
        a = "'a' is not polluting global scope"
        display( # %%testcell
        a
        ) # %%testcell
    try:
        _test_cell_()
    finally:
        del _test_cell_
    ### 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:

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


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

On top of *wrapping* your cell’s code, it will optinally add a
`display(...)` call on your last cell’s row, trying to emulate what a
real cell usually does. If you explicitly add a semicolon `;` in the
end, this output will be suppressed.

``` python
%%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_
    ### END

There are more cases where `display(...)` is avoided: \* `display`: if
this is already present on the last line. \* `print`: even in this case
no print is preserved and no other display call is added. \*
`# comment...#`: these are preserved

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


    ### BEGIN
    def _test_cell_():
        #| echo: false
        a = "'a' is not polluting global scope"
        print(a)
    try:
        _test_cell_()
    finally:
        del _test_cell_
    ### END
    'a' is not polluting global scope

### Run in isolation

`%%testcelln` is a shourtcut for `%%testcell noglobals` and executes the
cell in complete isolation from global scope. This is very useful when
you want to be sure that global variables or namespace should be part of
the cell.

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

``` python
aaa = 'global variable'
```

``` python
%%testcell
'aaa' in globals()
```

    True

``` python
%%testcell noglobals
'aaa' in globals()
```

    False

``` python
%%testcelln
'aaa' in globals()
```

    False

``` python
%%testcelln
globals().keys()
```

    dict_keys(['__builtins__', '_test_cell_'])

Inside the cell, from the *global scope*, only these two items are
available: + `__builtins__` : built in python’s functions. +
`_test_cell_` : `%%testcell` wrapped function executed (we can’t avoid
this).

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

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

    global variable

``` python
%%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.

``` python
aaa
```

    'global variable'

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

``` python
aaa
```

    'modified global variable'

``` python
del aaa
```

## TODO:

- Install as a plugin to enable it by default like other cell’s magic.
- Eval possibility to run code on a new kernel to reduce even more
  possible side effects.
