lsst.pex.config  13.0-3-g520d906+6
callStack.py
Go to the documentation of this file.
1 #
2 # LSST Data Management System
3 # Copyright 2017 AURA/LSST.
4 #
5 # This product includes software developed by the
6 # LSST Project (http://www.lsst.org/).
7 #
8 # This program is free software: you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation, either version 3 of the License, or
11 # (at your option) any later version.
12 #
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
17 #
18 # You should have received a copy of the LSST License Statement and
19 # the GNU General Public License along with this program. If not,
20 # see <https://www.lsstcorp.org/LegalNotices/>.
21 #
22 
23 from __future__ import print_function, division, absolute_import
24 
25 __all__ = ['getCallerFrame', 'getStackFrame', 'StackFrame', 'getCallStack']
26 
27 from builtins import object
28 
29 import re
30 import os
31 import inspect
32 import linecache
33 
34 
35 def getCallerFrame(relative=0):
36  """Retrieve the frame for the caller
37 
38  By "caller", we mean our user's caller.
39 
40  Parameters
41  ----------
42  relative : `int`, non-negative
43  Number of frames above the caller to retrieve.
44 
45  Returns
46  -------
47  frame : `__builtin__.Frame`
48  Frame for the caller.
49  """
50  frame = inspect.currentframe().f_back.f_back # Our caller's caller
51  for ii in range(relative):
52  frame = frame.f_back
53  return frame
54 
55 
56 def getStackFrame(relative=0):
57  """Retrieve the stack frame for the caller
58 
59  By "caller", we mean our user's caller.
60 
61  Parameters
62  ----------
63  relative : `int`, non-negative
64  Number of frames above the caller to retrieve.
65 
66  Returns
67  -------
68  frame : `StackFrame`
69  Stack frame for the caller.
70  """
71  frame = getCallerFrame(relative + 1)
72  return StackFrame.fromFrame(frame)
73 
74 
75 class StackFrame(object):
76  """A single element of the stack trace
77 
78  This differs slightly from the standard system mechanisms for
79  getting a stack trace by the fact that it does not look up the
80  source code until it is absolutely necessary, reducing the I/O.
81 
82  Parameters
83  ----------
84  filename : `str`
85  Name of file containing the code being executed.
86  lineno : `int`
87  Line number of file being executed.
88  function : `str`
89  Function name being executed.
90  content : `str` or `None`
91  The actual content being executed. If not provided, it will be
92  loaded from the file.
93  """
94  _STRIP = "/python/lsst/" # String to strip from the filename
95 
96  def __init__(self, filename, lineno, function, content=None):
97  loc = filename.rfind(self._STRIP)
98  if loc > 0:
99  filename = filename[loc + len(self._STRIP):]
100  self.filename = filename
101  self.lineno = lineno
102  self.function = function
103  self._content = content
104 
105  @property
106  def content(self):
107  """Getter for content being executed
108 
109  Load from file on demand.
110  """
111  if self._content is None:
112  self._content = linecache.getline(self.filename, self.lineno).strip()
113  return self._content
114 
115  @classmethod
116  def fromFrame(cls, frame):
117  """Construct from a Frame object
118 
119  inspect.currentframe() provides a Frame object. This is
120  a convenience constructor to interpret that Frame object.
121 
122  Parameters
123  ----------
124  frame : `Frame`
125  Frame object to interpret.
126 
127  Returns
128  -------
129  output : `StackFrame`
130  Constructed object.
131  """
132  filename = frame.f_code.co_filename
133  lineno = frame.f_lineno
134  function = frame.f_code.co_name
135  return cls(filename, lineno, function)
136 
137  def __repr__(self):
138  return "%s(%s, %s, %s)" % (self.__class__.__name__ , self.filename, self.lineno, self.function)
139 
140  def format(self, full=False):
141  """Format for printing
142 
143  Parameters
144  ----------
145  full : `bool`
146  Print full details, including content being executed?
147 
148  Returns
149  -------
150  result : `str`
151  Formatted string.
152  """
153  result = " File %s:%s (%s)" % (self.filename, self.lineno, self.function)
154  if full:
155  result += "\n %s" % (self.content,)
156  return result
157 
158 
159 def getCallStack(skip=0):
160  """Retrieve the call stack for the caller
161 
162  By "caller", we mean our user's caller - we don't include ourselves
163  or our caller.
164 
165  The result is ordered with the most recent frame last.
166 
167  Parameters
168  ----------
169  skip : `int`, non-negative
170  Number of stack frames above caller to skip.
171 
172  Returns
173  -------
174  output : `list` of `StackFrame`
175  The call stack.
176  """
177  frame = getCallerFrame(skip + 1)
178  stack = []
179  while frame:
180  stack.append(StackFrame.fromFrame(frame))
181  frame = frame.f_back
182  return list(reversed(stack))
def __init__(self, filename, lineno, function, content=None)
Definition: callStack.py:96
def getCallStack(skip=0)
Definition: callStack.py:159
def getStackFrame(relative=0)
Definition: callStack.py:56
def getCallerFrame(relative=0)
Definition: callStack.py:35
def format(self, full=False)
Definition: callStack.py:140