lsst.pex.config  16.0-5-gd0f1235
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 __all__ = ['getCallerFrame', 'getStackFrame', 'StackFrame', 'getCallStack']
24 
25 import inspect
26 import linecache
27 
28 
29 def getCallerFrame(relative=0):
30  """Retrieve the frame for the caller
31 
32  By "caller", we mean our user's caller.
33 
34  Parameters
35  ----------
36  relative : `int`, non-negative
37  Number of frames above the caller to retrieve.
38 
39  Returns
40  -------
41  frame : `__builtin__.Frame`
42  Frame for the caller.
43  """
44  frame = inspect.currentframe().f_back.f_back # Our caller's caller
45  for ii in range(relative):
46  frame = frame.f_back
47  return frame
48 
49 
50 def getStackFrame(relative=0):
51  """Retrieve the stack frame for the caller
52 
53  By "caller", we mean our user's caller.
54 
55  Parameters
56  ----------
57  relative : `int`, non-negative
58  Number of frames above the caller to retrieve.
59 
60  Returns
61  -------
62  frame : `StackFrame`
63  Stack frame for the caller.
64  """
65  frame = getCallerFrame(relative + 1)
66  return StackFrame.fromFrame(frame)
67 
68 
69 class StackFrame:
70  """A single element of the stack trace
71 
72  This differs slightly from the standard system mechanisms for
73  getting a stack trace by the fact that it does not look up the
74  source code until it is absolutely necessary, reducing the I/O.
75 
76  Parameters
77  ----------
78  filename : `str`
79  Name of file containing the code being executed.
80  lineno : `int`
81  Line number of file being executed.
82  function : `str`
83  Function name being executed.
84  content : `str` or `None`
85  The actual content being executed. If not provided, it will be
86  loaded from the file.
87  """
88  _STRIP = "/python/lsst/" # String to strip from the filename
89 
90  def __init__(self, filename, lineno, function, content=None):
91  loc = filename.rfind(self._STRIP)
92  if loc > 0:
93  filename = filename[loc + len(self._STRIP):]
94  self.filename = filename
95  self.lineno = lineno
96  self.function = function
97  self._content = content
98 
99  @property
100  def content(self):
101  """Getter for content being executed
102 
103  Load from file on demand.
104  """
105  if self._content is None:
106  self._content = linecache.getline(self.filename, self.lineno).strip()
107  return self._content
108 
109  @classmethod
110  def fromFrame(cls, frame):
111  """Construct from a Frame object
112 
113  inspect.currentframe() provides a Frame object. This is
114  a convenience constructor to interpret that Frame object.
115 
116  Parameters
117  ----------
118  frame : `Frame`
119  Frame object to interpret.
120 
121  Returns
122  -------
123  output : `StackFrame`
124  Constructed object.
125  """
126  filename = frame.f_code.co_filename
127  lineno = frame.f_lineno
128  function = frame.f_code.co_name
129  return cls(filename, lineno, function)
130 
131  def __repr__(self):
132  return "%s(%s, %s, %s)" % (self.__class__.__name__, self.filename, self.lineno, self.function)
133 
134  def format(self, full=False):
135  """Format for printing
136 
137  Parameters
138  ----------
139  full : `bool`
140  Print full details, including content being executed?
141 
142  Returns
143  -------
144  result : `str`
145  Formatted string.
146  """
147  result = " File %s:%s (%s)" % (self.filename, self.lineno, self.function)
148  if full:
149  result += "\n %s" % (self.content,)
150  return result
151 
152 
153 def getCallStack(skip=0):
154  """Retrieve the call stack for the caller
155 
156  By "caller", we mean our user's caller - we don't include ourselves
157  or our caller.
158 
159  The result is ordered with the most recent frame last.
160 
161  Parameters
162  ----------
163  skip : `int`, non-negative
164  Number of stack frames above caller to skip.
165 
166  Returns
167  -------
168  output : `list` of `StackFrame`
169  The call stack.
170  """
171  frame = getCallerFrame(skip + 1)
172  stack = []
173  while frame:
174  stack.append(StackFrame.fromFrame(frame))
175  frame = frame.f_back
176  return list(reversed(stack))
def __init__(self, filename, lineno, function, content=None)
Definition: callStack.py:90
def getCallStack(skip=0)
Definition: callStack.py:153
def getStackFrame(relative=0)
Definition: callStack.py:50
def getCallerFrame(relative=0)
Definition: callStack.py:29
def format(self, full=False)
Definition: callStack.py:134