# Bumps documentation

## util - Miscellaneous functions

`kbhit` | Check whether a key has been pressed on the console.
`profile` | Profile a function called with the given arguments.
`pushdir` | Change directories for the duration of a with statement.
`push_seed` | Set the seed value for the random number generator.
`redirect_console` | Console output redirection context

Miscellaneous utility functions.

bumps.util.kbhit()

  Check whether a key has been pressed on the console.

bumps.util.profile(fn, *args, **kw)

  Profile a function called with the given arguments.

class bumps.util.push_seed(seed=None)

  Bases: `object`

  Set the seed value for the random number generator.

  When used in a with statement, the random number generator state is restored after the with statement is complete.

  Parameters:

  seed int or array_like, optional

    Seed for RandomState

  Example:

  Seed can be used directly to set the seed:

      >>> from numpy.random import randint
      >>> push_seed(24)
      <...push_seed object at...>
      >>> print(randint(0,1000000,3))
      [242082    899 211136]

  Seed can also be used in a with statement, which sets the random number generator state for the enclosed computations and restores it to the previous state on completion:

      >>> with push_seed(24):
      ...    print(randint(0,1000000,3))
      [242082    899 211136]

  Using nested contexts, we can demonstrate that state is indeed restored after the block completes:

      >>> with push_seed(24):
      ...    print(randint(0,1000000))
      ...    with push_seed(24):
      ...        print(randint(0,1000000,3))
      ...    print(randint(0,1000000))
      242082
      [242082    899 211136]
      899

  The restore step is protected against exceptions in the block:

      >>> with push_seed(24):
      ...    print(randint(0,1000000))
      ...    try:
      ...        with push_seed(24):
      ...            print(randint(0,1000000,3))
      ...            raise Exception()
      ...    except Exception:
      ...        print("Exception raised")
      ...    print(randint(0,1000000))
      242082
      [242082    899 211136]
      Exception raised
      899

class bumps.util.pushdir(path)

  Bases: `object`

  Change directories for the duration of a with statement.

  Example:

  Show that the original directory is restored:

      >>> import sys, os
      >>> original_wd = os.getcwd()
      >>> with pushdir(sys.path[0]):
      ...     pushed_wd = os.getcwd()
      ...     first_site = os.path.abspath(sys.path[0])
      ...     assert pushed_wd == first_site
      >>> restored_wd = os.getcwd()
      >>> assert original_wd == restored_wd

class bumps.util.redirect_console(stdout=None, stderr=None)

  Bases: `object`

  Console output redirection context

  The output can be redirected to a string, to an already opened file (anything with a write attribute), or to a filename which will be opened for the duration of the with context. Unless stderr is specified, then both standard output and standard error are redirected to the same file. The open file handle is returned on enter, and (if it was not an already opened file) it is closed on exit.

  If no file is specified, then output is redirected to a StringIO object, which has a getvalue() method which can retrieve the string. The StringIO object is deleted when the context ends, so be sure to retrieve its value within the redirect_console context.

  Example:

  Show that output is captured in a file:

      >>> from bumps.util import redirect_console
      >>> print("hello")
      hello
      >>> with redirect_console("redirect_out.log"):
      ...     print("captured")
      >>> print("hello")
      hello
      >>> print(open("redirect_out.log").read()[:-1])
      captured
      >>> import os; os.unlink("redirect_out.log")

  Output can also be captured to a string:

      >>> with redirect_console() as fid:
      ...    print("captured to string")
      ...    captured_string = fid.getvalue()
      >>> print(captured_string.strip())
      captured to string