diff --git a/boltons/tbutils.py b/boltons/tbutils.py index c2aca40..0caf035 100644 --- a/boltons/tbutils.py +++ b/boltons/tbutils.py @@ -1,6 +1,27 @@ # -*- coding: utf-8 -*- +"""\ +One of the oft-cited tenets of Python is that it is better to ask +forgiveness than permission. That is, there are many cases where it is +more inclusive and correct to handle exceptions than spend extra lines +and execution time checking for conditions. This philosophy makes good +exception handling features all the more important. Unfortunately +Python's :mod:`traceback` module is woefully behind the times. + +The ``tbutils`` module provides two disparate but complementary featuresets: + + 1. With :class:`TracebackInfo` and :class:`ExceptionInfo`, the + ability to extract, construct, manipulate, format, and serialize + exceptions, tracebacks, and callstacks. + 2. With :class:`ParsedTB`, the ability to find and parse tracebacks + from captured output such as logs and stdout. + +There is also the :class:`ContextualTracebackInfo` variant of +:class:`TracebackInfo`, which includes much more information from each +frame of the callstack, including values of locals and neighboring +lines of code. + +""" -"""Extract, format and print information about Python stack traces.""" from __future__ import print_function import re @@ -21,8 +42,24 @@ import linecache class Callpoint(object): + """\ + + The Callpoint is a lightweight object used to represent a single + entry in the code of a call stack. It stores the code-related + metadata of a given frame. Available attributes are the same as + the parameters below. + + Args: + func_name (str): the function name + lineno (int): the line number + module_name (str): the module name + module_path (str): the filesystem path of the module + lasti (int): the index of bytecode execution + line (str): the single-line code content (if available) + + """ __slots__ = ('func_name', 'lineno', 'module_name', 'module_path', 'lasti', - 'line') # line is for the actual single-line code content + 'line') def __init__(self, module_name, module_path, func_name, lineno, lasti, line=None): @@ -34,6 +71,7 @@ class Callpoint(object): self.line = line def to_dict(self): + "Get a :class:`dict` copy of the Callpoint. Useful for serialization." ret = {} for slot in self.__slots__: try: @@ -44,11 +82,13 @@ class Callpoint(object): @classmethod def from_current(cls, level=1): + "Creates a Callpoint from the location of the calling function." frame = sys._getframe(level) return cls.from_frame(frame) @classmethod def from_frame(cls, frame): + "Create a Callpoint object from data extracted from the given frame." func_name = frame.f_code.co_name lineno = frame.f_lineno module_name = frame.f_globals.get('__name__', '') diff --git a/docs/tbutils.rst b/docs/tbutils.rst index fe0d433..628d9ed 100644 --- a/docs/tbutils.rst +++ b/docs/tbutils.rst @@ -3,4 +3,3 @@ .. automodule:: boltons.tbutils :members: - :undoc-members: