{
    "info": {
        "author": "Charles Ferguson",
        "author_email": "gerph@gerph.org",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3"
        ],
        "description": "## Overview\n\nThe 'longtraceback' module is intended to be used to give more information about the context of exceptions.\n\nCommonly it is necessary to add extra debugging into code which has gone wrong in order to discover what\nwas happening at the time of the failure. The 'longtraceback' module aims to avoid this situation by\nreporting the context of the exceptions in much greater detail than the standard traceback supplied with\nPython.\n\n## Features\n\n- Function names are qualified by their path:\n    - Functions defined within modules include the module path\n    - Methods defined within classes include the module and class path\n    - Named functions within methods or functions are given a path through to the function name\n    - Function names can indicate the type of symbol that was referenced.\n\n- Functions include information about parameters:\n    - The function name can include the parameter names as a prototype (optional)\n    - The function name can include all the parameters as a function call (optional)\n    - Following the function, we can show the values of the function parameters\n    - Parameters which are changed since the function started are inferred (optional)\n    - Additional '__traceback_*__' functions as used by _paste_ and _weberror_\n\n- Source lines:\n    - Lines have a context lines prior to the frame point (configurable)\n    - Source line indentation is not stripped.\n\n- Local variables:\n    - Local variables (which have not been listed in the function header) are listed after the source lines\n    - Variables are trimmed to avoid instance ids (optional)\n    - Properties on objects are included when showing variables (optional)\n\n- Exception information:\n    - Exception message are output in the normal way.\n    - They are followed by any non-standard properties on the exception object.\n    - Syntax error exceptions do not strip the left of the line when highlighting the failure position.\n\n- Filenames within each frame:\n    - Filenames are reduced to make it easier to see where the file comes from without having very long paths.\n    - <venv> indicates the virtualenv directories.\n    - <rootlib> indicates the top level directory (/Library/...) on OS X\n    - <syslib> indicates the system libraries (/System/Library/...) on OS X\n    - <userlib> indicates the user's python library\n    - <main> indicates the directory of the initially invoked script\n    - ~ indicates the home directory\n\n- Presentation:\n    - Blank lines can be included between each frame (optional)\n    - Repetitions of a given frame are detected (optional)\n    - Patterns of recursive parameters are reported (optional)\n\n- Error handling:\n    - When a problem occurs during frame extraction, backtraces are emitted for the failing case, and the extraction\n      falls back to the the old style extraction.\n    - When a problem occurs during printing the frames, python will report the exception within the handler, before\n      printing the original exception using the normal traceback handler.\n    - When a problem occurs during variable evaluation, we can optionally report the variable details (as the\n      evaluation invokes at least '__str__' or '__repr__' on the value).\n\n- Interactions with other environments:\n    - Aware of virtualenv for path reduction.\n    - Replaces the functions in the traceback module to allow other modules to gain from the new behaviour.\n    - New classes replace the Frame and Line information, so that users who do not understand them will get the\n      string behaviour they expect.\n    - When supplied with unaugmented extracted frame information (eg from prior to the import of this module),\n      the functions behave sensibly, reporting as much information as they can.\n    - When supplied with fake frame information (eg from Jinja2 tracebacks through the template code), the\n      presentation provides as much information as possible.\n\n- Colouring of exception output:\n    - In terminal, ANSI colouring is used to generate coloured output (optional).\n    - Rule-based configuration of colours allows customisation.\n\n- Configurable:\n    - User configuration file allows most features to be customised.\n    - Environment variable override allows configuration to be fixed in test environments.\n\n\n## Examples\n\nTaken from one of the tests, the original python traceback would produce the following output:\n\n``` none\nBoing\nTraceback (most recent call last):\n  File \"test_expect/function_naming/t09_inheritance_and_super.py\", line 29, in <module>\n    body.hit()\n  File \"test_expect/function_naming/t09_inheritance_and_super.py\", line 25, in hit\n    super(RubberWorld, self).hit()\n  File \"test_expect/function_naming/t09_inheritance_and_super.py\", line 14, in hit\n    raise Exception(\"Body '%s' got hit!\" % (self.__class__.__name__,))\nException: Body 'RubberWorld' got hit!\n```\n\nThe long traceback produces the following instead:\n\n``` none\nBoing\n\nTraceback (most recent call last):\n  File '<main>/t09_inheritance_and_super.py', line 29, in __main__\n       25 :         super(RubberWorld, self).hit()\n       26 :\n       27 :\n       28 : body = RubberWorld(1,2,-1,+1)\n       29-> body.hit()\n    Locals:\n      body = <__main__.RubberWorld object>\n       .vx = -1\n       .vy = 1\n       .x  = 1\n       .y  = 2\n\n  File '<main>/t09_inheritance_and_super.py', line 25, in __main__.RubberWorld.hit\n    self = <__main__.RubberWorld object>\n     .vx = -1\n     .vy = 1\n     .x  = 1\n     .y  = 2\n       23 :     def hit(self):\n       24 :         print(\"Boing\")\n       25->         super(RubberWorld, self).hit()\n\n  File '<main>/t09_inheritance_and_super.py', line 14, in __main__.Body.hit\n    self = <__main__.RubberWorld object>\n     .vx = -1\n     .vy = 1\n     .x  = 1\n     .y  = 2\n       13 :     def hit(self):\n       14->         raise Exception(\"Body '%s' got hit!\" % (self.__class__.__name__,))\n\nException: Body 'RubberWorld' got hit!\n```\n\nSame output, but using the colouring system:\n\n![Coloured traceback](images/coloured.png \"Simple coloured traceback\")\n\n\n## How to use\n\nHow you use the longtraceback module depends on what type of usage you intend for it.\n\n* At the command line it can be used very simply by referencing the module and using a Python REPL shell.\n* Embedded within an application, it is only necessary to import the longtraceback module to override the default traceback system.\n\n### Using the module from the command line\n\n1. Obtain a copy of the sources.\n2. Run the script to diagnose with: `PYTHONPATH=(path-to-module) python -mlongtraceback.shell (your-script)`\n\nFor simplicity, I have a small bash script in my path called `lpython` which does the equivalent for me:\n\n``` bash\n#!/bin/bash\n##\n# Activate python with the longtraceback extensions\n#\n\nexport PYTHONPATH=$HOME/projects/longtraceback/\n\npython -mlongtraceback.shell \"$@\"\n```\n\n\n## Configuration\n\nThe longtraceback module is configurable through a configuration file. This will be loaded on module\ninitialisation from the file referenced by the environment variable `PYTHONLONGTRACEBACKCONFIG`, or\nif it is unset, from the file `~/.python.longtraceback`.\n\nThe configuration file is a file parseable by ConfigParser (ie an .ini-like format), which contains\ntwo sections:\n\n1. `options` - contains the main options for the traceback system\n2. `colours` - contains rules for colouring the output\n\nAn example file can be found in [examples/python.traceback](examples/python.traceback).\n\nTo display the current configuration in a form suitable for putting into the configuration file,\nthe following commands can be used:\n\n  python -mlongtraceback.Options\n    - display the configuration with the defaults commented out\n  python -mlongtraceback.Options --defaults\n    - display the configuration with the defaults present\n\n\n### Options\n\nThe options take the form of settings which control whether settings are enabled or not, or the\nlimits to which they apply. The options are described in Options.py file, and the configuration\nfile example. See `examples/python.longtraceback` for an example configuration file containing\nthe descriptions of the options.\n\n\n### Colours\n\nWhen enabled, the colours used by the module are defined within the `colours` section of the\nconfiguration file. These take the form of keys which describe the rule to match areas of\nthe traceback output, and a value that is a comma-separated list of the properties to use.\n\nThe rules take the form of a .-separated list of the tokens used to describe the area of\nthe traceback output. For example, headers within the file are always described with the\n`header` token. To see what tokens are used for a given traceback, the styling format option\nin the main `options` section can be given the value `tokens`. When output as tokens,\neach token will be listed in the output within `<>` markers.\n\nIf a rule starts with a `.` character, the rule may match anywhere within a list of tokens.\nWithout the leading `.`, the rule matches from the start of the list.\n\nThe rule values take the form of property assignments. Properties describe how the rule should be\npresented. Some properties have values (like colours), and others do not (like bold). Values\nare given after an `=` sign in the list. The following properties are supported:\n\n- `fg` - foreground colour. Takes a named colour as a value.\n- `bg` - background colour. Takes a named colour as a value.\n- `bold` - bold enable. No value.\n- `underline` - underline enable. No value.\n\nColours supported are the 8 standard ANSI colours:\n\n- black\n- red\n- green\n- yellow\n- blue\n- magenta\n- cyan\n- white\n\nThe supplied colour scheme is suitable for a black-background terminal. It may not be ideal for\nwhite-background terminals.\n\nFor example, to change the colour of the filenames in the header, the rule used could be:\n\n```\n.header.file: fg=blue\n```\n\nA non-exhaustive list of the tokens used:\n\n- `context` - part of the source context lines around the failure\n- `context-caret` - the caret indicating the failure in a syntax error\n- `exception-name` - the exception name at the end of the output\n- `filename` - a filename\n- `function-name` - a function name\n- `function-type` - the inferred type of the function\n- `frame-repeated` - the message indicating the repetitions of the function frame\n- `header` - part of the header lines\n- `header.cause` - the messsage saying that this exception caused another one (Python 3 only)\n- `header.context` - the messsage saying that this exception was in a context (Python 3 only)\n- `header.exception` - the exception message\n- `header.file` - a header describing the function frame\n- `header.locals` - the local variables header\n- `header.traceback` - the initial message for traceback (not used in Python 2)\n- `internal-exception` - any internal errors which occurred whilst processing traceback\n- `line-divider` - the divider mark in the source context\n- `line-exception` - the marker for the line the exception was on\n- `lineno` - a line number within file description\n- `line-number` - the number of the source context line\n- `local` - a second of the local variables\n- `parameter` - the parameter to a function\n- `parameters` - a section of the function parameters\n- `property` - a property of an object\n- `sequence-values` - the values used within the repeated frames\n- `source` - source code\n- `varname` - a variable name\n- `varvalue` - a variable value",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://gitlab.gerph.org/gerph/longtraceback",
        "keywords": "traceback",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "longtraceback",
        "package_url": "https://pypi.org/project/longtraceback/",
        "platform": "",
        "project_url": "https://pypi.org/project/longtraceback/",
        "project_urls": {
            "Homepage": "https://gitlab.gerph.org/gerph/longtraceback"
        },
        "release_url": "https://pypi.org/project/longtraceback/1.0.356/",
        "requires_dist": null,
        "requires_python": ">=2.7",
        "summary": "More information about variables and context within traceback",
        "version": "1.0.356"
    },
    "last_serial": 5964655,
    "releases": {
        "1.0.356": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "18e963eaac9a78342693dd2c18cfa536",
                    "sha256": "6ea7f52f65dd5749384c19586fbc2a49fa19ed597724e1925e32ec464da79abb"
                },
                "downloads": -1,
                "filename": "longtraceback-1.0.356.tar.gz",
                "has_sig": false,
                "md5_digest": "18e963eaac9a78342693dd2c18cfa536",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=2.7",
                "size": 69469,
                "upload_time": "2019-10-12T15:28:25",
                "url": "https://files.pythonhosted.org/packages/d0/8e/23f8183755c59e4602bd23f0489319cf020d5995fce36121d888f7f36957/longtraceback-1.0.356.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "18e963eaac9a78342693dd2c18cfa536",
                "sha256": "6ea7f52f65dd5749384c19586fbc2a49fa19ed597724e1925e32ec464da79abb"
            },
            "downloads": -1,
            "filename": "longtraceback-1.0.356.tar.gz",
            "has_sig": false,
            "md5_digest": "18e963eaac9a78342693dd2c18cfa536",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=2.7",
            "size": 69469,
            "upload_time": "2019-10-12T15:28:25",
            "url": "https://files.pythonhosted.org/packages/d0/8e/23f8183755c59e4602bd23f0489319cf020d5995fce36121d888f7f36957/longtraceback-1.0.356.tar.gz"
        }
    ]
}