ENH: add space and remove_space magics

Author: davidesarra

.gitignore

@@ -0,0 +1,11 @@
+# distribution
+dist
+build
+
+# python
+__pycache__
+*.egg-info
+
+# testing
+.pytest_cache
+.tox

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Davide Sarra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE.txt
+include README.md

README.md

@@ -1,5 +1,90 @@
-# `jupyter_spaces`
+# Jupyter Spaces
 
-`jupyter_spaces` is an IPython extension for creating parallel namespaces
-within the user namespace. It is designed to be used via IPython magics in
-Jupyter notebooks.
+Jupyter Spaces is an IPython extension for creating parallel namespaces
+availabe within the user namespace. It is designed to be used via IPython
+magics in Jupyter notebooks.
+
+## Installation
+
+```bash
+pip install jupyter_spaces
+```
+
+`jupyter_spaces` supports Python versions `3.4`, `3.5` and `3.6`.
+
+## Usage
+
+### Load `jupyter_spaces` extension
+
+```python
+%load_ext jupyter_spaces
+```
+
+### Reload `jupyter_spaces` extension
+
+```python
+%reload_ext jupyter_spaces
+```
+
+Reloading the extension will remove all spaces.
+
+### Run a cell within a space
+
+```python
+%%space <space-name>
+alpha = 0.50
+print(alpha)
+```
+
+When you execute a cell within a space, all references are firstly searched in
+the space namespace and secondly in the user namespace. All assignments are
+made in the space namespace. However, as expected, `global` assigments are made
+in the user namespace.
+
+#### Console output
+
+Conversely to the standard usage of the python console, you need to use print
+to get a output in the console or Jupyter cell output.
+
+- No output to console
+    ```python
+    %%space <space-name>
+    100
+    ```
+- Output to console
+    ```python
+    %%space <space-name>
+    print(100)
+    ```
+
+### Remove a space
+
+```python
+%remove_space <space-name>
+```
+
+### Access all spaces at once
+
+Without using any magic you can access the spaces' namespaces.
+This might be useful to jointly post-process or compare the spaces' contents.
+
+```python
+from jupyter_spaces import get_spaces
+
+spaces = get_spaces()
+space = spaces[<space-name>]
+reference = space.namespace[<reference-name>]
+```
+
+`Space` objects have two properties:
+
+- `name` the name of the space
+- `namespace` a dictionary with the namespace of the space
+
+Modifying the spaces via `get_spaces` will actually modify the underlying
+spaces.
+
+## Acknowledgements
+
+Many thanks to [Yeray Diaz Diaz](https://github.com/yeraydiazdiaz) and
+[Karol Duleba](https://github.com/mrfuxi)!

dev-requirements.txt

@@ -0,0 +1,6 @@
+ipython>=6.2.1
+nbconvert==5.3.1
+nbformat==4.4.0
+nbval==0.9.0
+pytest==3.5.0
+tox==3.0.0

jupyter_spaces/__init__.py

@@ -0,0 +1,31 @@
+"""Jupyter Spaces is an IPython extension for creating parallel namespaces
+availabe within the user namespace. It is designed to be used via IPython
+magics in Jupyter notebooks.
+
+Copyright (c) 2018 Davide Sarra.
+MIT License, see LICENSE.txt for more details.
+"""
+from types import MappingProxyType
+
+from jupyter_spaces.magics import SpaceMagic as _SpaceMagic
+from jupyter_spaces.magics import space_register as _space_register
+
+
+def get_spaces():
+    """Get a proxy mapping of the spaces.
+
+    Returns:
+        dict: Mapping of spaces with keys being space names and values being
+            space namespaces.
+    """
+    return MappingProxyType(_space_register.register)
+
+
+def load_ipython_extension(ipython):
+    """Load IPython extension."""
+    ipython.register_magics(_SpaceMagic)
+
+
+def unload_ipython_extension(ipython):
+    """Unload IPython extension. All existing spaces will be removed."""
+    _space_register.remove_all_spaces()

jupyter_spaces/errors.py

@@ -0,0 +1,6 @@
+class BaseJupyterSpaceError(Exception):
+    pass
+
+
+class RegistryError(BaseJupyterSpaceError):
+    pass

jupyter_spaces/magics.py

@@ -0,0 +1,43 @@
+from IPython.core.magic import cell_magic, line_magic, Magics, magics_class
+
+from jupyter_spaces.space import SpaceRegister
+
+
+space_register = SpaceRegister()
+
+
+@magics_class
+class SpaceMagic(Magics):
+
+    @cell_magic
+    def space(self, line, cell):
+        """Execute cell contents using the space namespace as locals and the
+        user namespace as globals.
+
+        Args:
+            line (str): Content following `%%space` magic call, expected to
+                match the space name. If the provided space name has already
+                been used and not been removed, the same space object is used.
+            cell (str): Content following the first line.
+
+        Examples:
+            >>> %%space space_name
+            ... alpha = 0.50
+            ... print(alpha)
+        """
+        space = space_register.get_space(
+            name=line, outer_space=self.shell.user_ns)
+        space.execute(source=cell)
+
+    @line_magic
+    def remove_space(self, line):
+        """Remove a space.
+
+        Args:
+            line (str): Content following `%%remove_space` magic call, expected
+                to match the space name to remove.
+
+        Examples:
+            >>> %remove_space space_name
+        """
+        space_register.remove_space(name=line)

jupyter_spaces/space.py

@@ -0,0 +1,102 @@
+from jupyter_spaces.errors import RegistryError
+
+
+class SpaceRegister:
+    __slots__ = ['_register']
+
+    def __init__(self):
+        """Initialise SpaceRegister instance."""
+        self._register = {}
+
+    @property
+    def register(self):
+        """Register.
+
+        Returns:
+            dict: Register of Space instances.
+        """
+        return self._register
+
+    def get_space(self, name, outer_space):
+        """Get existing Space if a Space has the same name, otherwise create
+        and get new Space.
+
+        Args:
+            name (str): Name of the Space.
+            outer_space (dict): User namespace.
+
+        Returns:
+            Space: Space.
+        """
+        if name not in self._register:
+            self._register[name] = Space(name=name, outer_space=outer_space)
+        return self._register[name]
+
+    def remove_space(self, name):
+        """Remove Space from register.
+
+        Args:
+            name (str): Name of the Space.
+
+        Raises:
+            RegistryError: If no registered Space has the name passed.
+        """
+        try:
+            del self._register[name]
+        except KeyError:
+            raise RegistryError('Failed to forget space {name} because '
+                                'it does not exist'.format(name=name))
+
+    def remove_all_spaces(self):
+        """Remove all Spaces from register."""
+        self._register.clear()
+
+
+class Space:
+    __slots__ = ['_name', '_inner_space', '_outer_space']
+
+    def __init__(self, name, outer_space):
+        """Initialise Space instance.
+
+        Args:
+            name (str): Name of the space.
+            outer_space (dict): Outer namespace.
+        """
+        self._name = name
+        self._inner_space = {}
+        self._outer_space = outer_space
+
+    def __repr__(self):
+        return "Space(name='{name}' namespace={namespace})".format(
+            name=self.name, namespace=self.namespace)
+
+    @property
+    def name(self):
+        """Name of the Space instance.
+
+        Returns:
+            str: Name.
+        """
+        return self._name
+
+    @property
+    def namespace(self):
+        """Namespace of the Space instance.
+
+        Note that modifying the namespace will modify the actual namespace
+        of the Space instance.
+
+        Returns:
+            dict: Namespace.
+        """
+        return self._inner_space
+
+    def execute(self, source):
+        """Execute source code inside the space namespace and outer namespace.
+
+        Args:
+            source (str): Source code.
+        """
+        compiled_source = compile(
+            source=source, filename='<string>', mode='exec')
+        exec(compiled_source, self._outer_space, self._inner_space)

setup.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+from setuptools import find_packages, setup
+
+NAME = 'jupyter_spaces'
+VERSION = '0.0.1'
+AUTHOR = 'Davide Sarra'
+URL = 'https://github.com/davidesarra/jupyter_spaces'
+DESCRIPTION = 'Create parallel namespaces in Jupyter Notebooks'
+LICENSE = 'MIT'
+CLASSIFIERS = [
+    'Environment :: Console',
+    'Framework :: IPython',
+    'Framework :: Jupyter',
+    'Intended Audience :: Developers',
+    'Intended Audience :: Science/Research',
+    'License :: OSI Approved :: MIT License',
+    'Operating System :: OS Independent',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3.4',
+    'Programming Language :: Python :: 3.5',
+    'Programming Language :: Python :: 3.6',
+]
+KEYWORDS = 'jupyter ipython magic extension namespace'
+
+with open('README.md', 'r') as f:
+    LONG_DESCRIPTION = f.read()
+
+REQUIREMENTS = [
+    'ipython>=6.2.1',
+]
+
+if __name__ == "__main__":
+    setup(
+        name=NAME,
+        version=VERSION,
+        author=AUTHOR,
+        url=URL,
+        license=LICENSE,
+        classifiers=CLASSIFIERS,
+        keywords=KEYWORDS,
+        description=DESCRIPTION,
+        long_description=LONG_DESCRIPTION,
+        long_description_content_type='text/markdown',
+        packages=find_packages(exclude=['tests']),
+        install_requires=REQUIREMENTS,
+        python_requires='~=3.4',
+    )