Metadata-Version: 1.2
Name: tempvars
Version: 1.0.1
Summary: Context manager for handling temporary variables in Jupyter Notebook, IPython, etc.
Home-page: https://www.github.com/bskinn/tempvars
Author: Brian Skinn
Author-email: bskinn@alum.mit.edu
License: MIT License
Description: tempvars: A context manager for handling temporary variables
        ============================================================
        
        **Current Development Version:**
        
        .. image:: https://travis-ci.org/bskinn/tempvars.svg?branch=dev
            :target: https://travis-ci.org/bskinn/tempvars
        
        .. image:: https://codecov.io/gh/bskinn/tempvars/branch/dev/graph/badge.svg
            :target: https://codecov.io/gh/bskinn/tempvars
        
        **Most Recent Stable Release:**
        
        .. image:: https://img.shields.io/pypi/v/tempvars.svg
            :target: https://pypi.org/project/tempvars
        
        .. image:: https://img.shields.io/pypi/pyversions/tempvars.svg
        
        **Info:**
        
        .. image:: https://img.shields.io/readthedocs/tempvars/v1.0.1.svg
            :target: http://tempvars.readthedocs.io/en/v1.0.1/
        
        .. image:: https://img.shields.io/github/license/mashape/apistatus.svg
            :target: https://github.com/bskinn/tempvars/blob/master/LICENSE.txt
        
        .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
            :target: https://github.com/ambv/black
        
        ----
        
        **Use Jupyter Notebook?**
        
        **Constantly run into problems from obsolete variables hanging around
        in the namespace?**
        
        ``tempvars`` *can help.*
        
        Developing in Jupyter notebooks can sometimes be frustrating.
        For example, it's aggravating to debug a worksheet for half an hour,
        only to discover that a carried-over variable name was hanging around
        in the notebook namespace and causing problems.
        Or, to open a notebook that "worked fine" the last
        time it was used, but only because of random, obsolete variables that happened
        to be lingering in the namespace.
        Wrapping notebook code in functions/classes is an effective way of avoiding
        these sorts of problems, but it's rarely effective or efficient to
        do this in the initial exploratory phase of in-notebook development.
        
        ``TempVars`` is a context manager that helps to avoid these pitfalls by
        clearing selected identifiers from the namespace for the duration of
        its scope, then restoring them afterwards (or not, if desired).
        Further, any variables created within the managed context
        that match the ``TempVars`` filtering criteria are removed from
        the namespace upon exiting, ensuring these values do not spuriously
        contribute to following code. For convenience, all variables
        removed from the namespace at entry and exit
        are stored for later reference (see example code below).
        
        Due to the way Python handles non-global scopes, ``TempVars``
        can only be used at the global scope. *Any attempt
        to use* ``TempVars`` *in non-global contexts will
        result in a* ``RuntimeError``. Viable use-cases include Jupyter notebooks,
        the IPython and basic Python REPLs, and the outermost scope of executed and
        imported modules. Preliminary testing indicates it also works with
        `cauldron-notebook <https://github.com/sernst/cauldron>`__, though
        it may be less helpful there due to its step-local scoping paradigm
        (shared values must be passed around via ``cauldron.shared``).
        
        ----
        
        After installing with ``pip install tempvars``, import as:
        
        .. code:: python
        
            >>> from tempvars import TempVars
        
        For typical use in a Jupyter notebook cell, the recommended approach
        is to pick a marker to use on all variables that are to be temporary,
        and enclose the entire cell in a ``TempVars`` context. For example,
        one could prefix all temporary variables with `t_` and make use
        of the `starts` argument:
        
        .. code:: python
        
            >>> foo = 5
            >>> with TempVars(starts=['t_']):
            ...     print(foo)
            ...     t_bar = 8
            ...     print(foo + t_bar)
            5
            13
            >>> print('t_bar' in dir())
            False
        
        A similar effect can be achieved with a suffix such as `_t` and
        the `ends` argument.
        
        Temporary variable masking can also be introduced to existing
        code in a more selective fashion via the `names` argument:
        
        .. code:: python
        
            >>> foo = 5
            >>> bar = 7
            >>> with TempVars(names=['bar']):
            ...     print(foo)
            ...     print('bar' in dir())
            5
            False
            >>> print(foo * bar)
            35
        
        Setting the `restore` argument to ``False`` instructs ``TempVars``
        not to restore any masked variables to the namespace after its
        context exits. This is potentially useful to avoid carryover of
        common helper variables (`arr`, `df`, `i`, etc.) to downstream cells
        that may have been created earlier in a notebook:
        
        .. code:: python
        
            >>> for k in ['foo', 'bar']:
            ...     pass
            >>> print(k)
            bar
            >>> with TempVars(names=['k'], restore=False):
            ...     print('k' in dir())
            False
            >>> print('k' in dir())
            False
        
        ``TempVars`` stores the values of variables it removes from the namespace,
        should they need to be accessed. A bound `with`/`as` statement must be
        used in order to enable this:
        
        .. code:: python
        
            >>> foo = 5
            >>> with TempVars(names=['foo']) as tv:
            ...     print('foo' in dir())
            ...     print(tv.stored_nsvars['foo'])
            ...     foo = 8
            ...     print(foo)
            False
            5
            8
            >>> print(foo)
            5
            >>> print(tv.retained_tempvars['foo'])
            8
        
        ----
        
        
        Available on `PyPI <https://pypi.org/project/tempvars>`__: ``pip install tempvars``.
        
        Full documentation at
        `Read the Docs <http://tempvars.readthedocs.io/en/v1.0.1/>`__.
        
        Source on `GitHub <https://github.com/bskinn/tempvars>`__.
        Bug reports and feature requests are welcomed at the
        `Issues <https://github.com/bskinn/tempvars/issues>`__ page there.
        If you like the idea of an enhancement already in the Issues list,
        please comment to say so; it'll help with prioritization.
        
        Copyright (c) Brian Skinn 2017-2018
        
        License: The MIT License. See `LICENSE.txt <https://github.com/bskinn/tempvars/blob/master/LICENSE.txt>`__
        for full license terms.
        
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development
Classifier: Development Status :: 5 - Production/Stable
Requires: attrs (>=17.1)
Provides: tempvars
Requires-Python: >=3.4
