LSSTApplications  18.1.0
LSSTDataManagementBasePackage
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  """Get the frame for the user's caller.
31 
32  Parameters
33  ----------
34  relative : `int`, optional
35  Number of frames (0 or more) above the caller to retrieve. Default is 0.
36 
37  Returns
38  -------
39  frame : `__builtin__.Frame`
40  Frame for the caller.
41 
42  Notes
43  -----
44  This function is excluded from the frame.
45  """
46  frame = inspect.currentframe().f_back.f_back # Our caller's caller
47  for ii in range(relative):
48  frame = frame.f_back
49  return frame
50 
51 
52 def getStackFrame(relative=0):
53  """Get the `StackFrame` for the user's caller.
54 
55  Parameters
56  ----------
57  relative : `int`, optional
58  Number of frames (0 or more) 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 getting a
73  stack trace by the fact that it does not look up the source code until it
74  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`, optional
85  The actual content being executed. If not provided, it will be loaded
86  from the file.
87 
88  Notes
89  -----
90  This differs slightly from the standard system mechanisms for getting a
91  stack trace by the fact that it does not look up the source code until it
92  is absolutely necessary, reducing the I/O.
93 
94  See also
95  --------
96  getStackFrame
97  """
98 
99  _STRIP = "/python/lsst/"
100  """String to strip from the ``filename`` in the constructor."""
101 
102  def __init__(self, filename, lineno, function, content=None):
103  loc = filename.rfind(self._STRIP)
104  if loc > 0:
105  filename = filename[loc + len(self._STRIP):]
106  self.filename = filename
107  self.lineno = lineno
108  self.function = function
109  self._content = content
110 
111  @property
112  def content(self):
113  """Content being executed (loaded on demand) (`str`).
114  """
115  if self._content is None:
116  self._content = linecache.getline(self.filename, self.lineno).strip()
117  return self._content
118 
119  @classmethod
120  def fromFrame(cls, frame):
121  """Construct from a Frame object.
122 
123  Parameters
124  ----------
125  frame : `Frame`
126  Frame object to interpret, such as from `inspect.currentframe`.
127 
128  Returns
129  -------
130  stackFrame : `StackFrame`
131  A `StackFrame` instance.
132 
133  Examples
134  --------
135  `inspect.currentframe` provides a Frame object. This is a convenience
136  constructor to interpret that Frame object:
137 
138  >>> import inspect
139  >>> stackFrame = StackFrame.fromFrame(inspect.currentframe())
140  """
141  filename = frame.f_code.co_filename
142  lineno = frame.f_lineno
143  function = frame.f_code.co_name
144  return cls(filename, lineno, function)
145 
146  def __repr__(self):
147  return "%s(%s, %s, %s)" % (self.__class__.__name__, self.filename, self.lineno, self.function)
148 
149  def format(self, full=False):
150  """Format for printing.
151 
152  Parameters
153  ----------
154  full : `bool`, optional
155  If `True`, output includes the conentent (`StackFrame.content`) being executed. Default
156  is `False`.
157 
158  Returns
159  -------
160  result : `str`
161  Formatted string.
162  """
163  result = " File %s:%s (%s)" % (self.filename, self.lineno, self.function)
164  if full:
165  result += "\n %s" % (self.content,)
166  return result
167 
168 
169 def getCallStack(skip=0):
170  """Retrieve the call stack for the caller.
171 
172  Parameters
173  ----------
174  skip : `int`, non-negative
175  Number of stack frames above caller to skip.
176 
177  Returns
178  -------
179  output : `list` of `StackFrame`
180  The call stack. The `list` is ordered with the most recent frame to
181  last.
182 
183  Notes
184  -----
185  This function is excluded from the call stack.
186  """
187  frame = getCallerFrame(skip + 1)
188  stack = []
189  while frame:
190  stack.append(StackFrame.fromFrame(frame))
191  frame = frame.f_back
192  return list(reversed(stack))
def __init__(self, filename, lineno, function, content=None)
Definition: callStack.py:102
def getCallStack(skip=0)
Definition: callStack.py:169
def getStackFrame(relative=0)
Definition: callStack.py:52
def getCallerFrame(relative=0)
Definition: callStack.py:29
def format(self, full=False)
Definition: callStack.py:149
daf::base::PropertyList * list
Definition: fits.cc:885
bool strip
Definition: fits.cc:883