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