class_docstr: Extension of the completer class with IPython-specific features
class_docstr_tok: ["Extension","of","the","completer","class","with","IPython-specific","features"]
docstr: Find completions for the given text and line context.
  
  Note that both the text and the line_buffer are optional, but at least
  one of them must be given.
  
  Parameters
  ----------
    text : string, optional
      Text to perform the completion on.  If not given, the line buffer
      is split using the instance's CompletionSplitter object.
  
    line_buffer : string, optional
      If not given, the completer attempts to obtain the current line
      buffer via readline.  This keyword allows clients which are
      requesting for text completions in non-readline contexts to inform
      the completer of the entire text.
  
    cursor_pos : int, optional
      Index of the cursor in the full line buffer.  Should be provided by
      remote frontends where kernel has no access to frontend state.
  
  Returns
  -------
  text : str
    Text that was actually used in the completion.
  
  matches : list
    A list of completion matches.
docstr_tok: ["Find","completions","for","the","given","text","and","line","context",".","Note","that","both","the","text","and","the","line_buffer","are","optional",",","but","at","least","one","of","them","must","be","given",".","Parameters","--","--","--","--","--","text",":","string",",","optional","Text","to","perform","the","completion","on",".","If","not","given",",","the","line","buffer","is","split","using","the","instance","'s","CompletionSplitter","object",".","line_buffer",":","string",",","optional","If","not","given",",","the","completer","attempts","to","obtain","the","current","line","buffer","via","readline",".","This","keyword","allows","clients","which","are","requesting","for","text","completions","in","non-readline","contexts","to","inform","the","completer","of","the","entire","text",".","cursor_pos",":","int",",","optional","Index","of","the","cursor","in","the","full","line","buffer",".","Should","be","provided","by","remote","frontends","where","kernel","has","no","access","to","frontend","state",".","Returns","--","--","--","-","text",":","str","Text","that","was","actually","used","in","the","completion",".","matches",":","list","A","list","of","completion","matches","."]
code: def complete(self, text=None, line_buffer=None, cursor_pos=None):
      """Find completions for the given text and line context.
  
      Note that both the text and the line_buffer are optional, but at least
      one of them must be given.
  
      Parameters
      ----------
        text : string, optional
          Text to perform the completion on.  If not given, the line buffer
          is split using the instance's CompletionSplitter object.
  
        line_buffer : string, optional
          If not given, the completer attempts to obtain the current line
          buffer via readline.  This keyword allows clients which are
          requesting for text completions in non-readline contexts to inform
          the completer of the entire text.
  
        cursor_pos : int, optional
          Index of the cursor in the full line buffer.  Should be provided by
          remote frontends where kernel has no access to frontend state.
  
      Returns
      -------
      text : str
        Text that was actually used in the completion.
  
      matches : list
        A list of completion matches.
      """
      # if the cursor position isn't given, the only sane assumption we can
      # make is that it's at the end of the line (the common case)
      if cursor_pos is None:
          cursor_pos = len(line_buffer) if text is None else len(text)
  
      if self.use_main_ns:
          self.namespace = __main__.__dict__
  
      if PY3 and self.backslash_combining_completions:
          base_text = (
              text if not line_buffer else line_buffer[:cursor_pos]
          )
          latex_text, latex_matches = self.latex_matches(base_text)
          if latex_matches:
              return latex_text, latex_matches
          name_text = ""
          name_matches = []
          for meth in (
              self.unicode_name_matches,
              back_latex_name_matches,
              back_unicode_name_matches,
          ):
              name_text, name_matches = meth(base_text)
              if name_text:
                  return name_text, name_matches[:MATCHES_LIMIT]
  
      # if text is either None or an empty string, rely on the line buffer
      if not text:
          text = self.splitter.split_line(line_buffer, cursor_pos)
  
      # If no line buffer is given, assume the input text is all there was
      if line_buffer is None:
          line_buffer = text
  
      self.line_buffer = line_buffer
      self.text_until_cursor = self.line_buffer[:cursor_pos]
  
      # Start with a clean slate of completions
      self.matches[:] = []
      custom_res = self.dispatch_custom_completer(text)
      if custom_res is not None:
          # did custom completers produce something?
          self.matches = custom_res
      else:
          # Extend the list of completions with the results of each
          # matcher, so we return results to the user from all
          # namespaces.
          if self.merge_completions:
              self.matches = []
              for matcher in self.matchers:
                  try:
                      self.matches.extend(matcher(text))
                  except:
                      # Show the ugly traceback if the matcher causes an
                      # exception, but do NOT crash the kernel!
                      sys.excepthook(*sys.exc_info())
          else:
              for matcher in self.matchers:
                  self.matches = matcher(text)
                  if self.matches:
                      break
      # FIXME: we should extend our api to return a dict with completions for
      # different types of objects.  The rlcomplete() method could then
      # simply collapse the dict into a list for readline, but we'd have
      # richer completion semantics in other evironments.
      self.matches = sorted(
          set(self.matches), key=completions_sorting_key
      )[:MATCHES_LIMIT]
  
      return text, self.matches
  
imports: from __future__ import print_function
  import __main__
  import glob
  import inspect
  import itertools
  import keyword
  import os
  import re
  import sys
  import unicodedata
  import string
  import warnings
  from traitlets.config.configurable import Configurable
  from IPython.core.error import TryNext
  from IPython.core.inputsplitter import ESC_MAGIC
  from IPython.core.latex_symbols import latex_symbols, reverse_latex_symbol
  from IPython.utils import generics
  from IPython.utils.decorators import undoc
  from IPython.utils.dir2 import dir2, get_real_method
  from IPython.utils.process import arg_split
  from IPython.utils.py3compat import builtin_mod, string_types, PY3, cast_unicode_py2
  from traitlets import Bool, Enum, observe
label_desc: Use image node_id 17 for calling the IPCompleter obj's underlying member method code with example usage: obj.complete(text, line_buffer, cursor_pos) and returns: text,  self, latex_text,  latex_matches, name_text,  name_matches