1  # encoding: utf-8
   2  """Decorators that don't go anywhere else.
   3  
   4  This module contains misc. decorators that don't really go with another module
   5  in :mod:`IPython.utils`. Before putting something here please see if it should
   6  go into another topical module in :mod:`IPython.utils`.
   7  """
   8  
   9  #-----------------------------------------------------------------------------
  10  #  Copyright (C) 2008-2011  The IPython Development Team
  11  #
  12  #  Distributed under the terms of the BSD License.  The full license is in
  13  #  the file COPYING, distributed as part of this software.
  14  #-----------------------------------------------------------------------------
  15  
  16  #-----------------------------------------------------------------------------
  17  # Imports
  18  #-----------------------------------------------------------------------------
  19  from typing import Sequence
  20  
  21  from IPython.utils.docs import GENERATING_DOCUMENTATION
  22  
  23  
  24  #-----------------------------------------------------------------------------
  25  # Code
  26  #-----------------------------------------------------------------------------
  27  
  28  def flag_calls(func):
  29      """Wrap a function to detect and flag when it gets called.
  30  
  31      This is a decorator which takes a function and wraps it in a function with
  32      a 'called' attribute. wrapper.called is initialized to False.
  33  
  34      The wrapper.called attribute is set to False right before each call to the
  35      wrapped function, so if the call fails it remains False.  After the call
  36      completes, wrapper.called is set to True and the output is returned.
  37  
  38      Testing for truth in wrapper.called allows you to determine if a call to
  39      func() was attempted and succeeded."""
  40      
  41      # don't wrap twice
  42      if hasattr(func, 'called'):
  43          return func
  44  
  45      def wrapper(*args,**kw):
  46          wrapper.called = False
  47          out = func(*args,**kw)
  48          wrapper.called = True
  49          return out
  50  
  51      wrapper.called = False
  52      wrapper.__doc__ = func.__doc__
  53      return wrapper
  54  
  55  
  56  def undoc(func):
  57      """Mark a function or class as undocumented.
  58  
  59      This is found by inspecting the AST, so for now it must be used directly
  60      as @undoc, not as e.g. @decorators.undoc
  61      """
  62      return func
  63  
  64  
  65  def sphinx_options(
  66      show_inheritance: bool = True,
  67      show_inherited_members: bool = False,
  68      exclude_inherited_from: Sequence[str] = tuple(),
  69  ):
  70      """Set sphinx options"""
  71  
  72      def wrapper(func):
  73          if not GENERATING_DOCUMENTATION:
  74              return func
  75  
  76          func._sphinx_options = dict(
  77              show_inheritance=show_inheritance,
  78              show_inherited_members=show_inherited_members,
  79              exclude_inherited_from=exclude_inherited_from,
  80          )
  81          return func
  82  
  83      return wrapper
  84