Metadata-Version: 2.1
Name: extra-context
Version: 1.0.0
Summary: Add additional context to warnings and exceptions
Home-page: https://github.com/WanzenBug/extra-context-py
Author: Moritz "WanzenBug" Wanzenböck
Author-email: moritz.wanzenboeck@gmail.com
License: UNKNOWN
Project-URL: Bug Reports, https://github.com/WanzenBug/extra-context-py/issues
Project-URL: Source, https://github.com/WanzenBug/extra-context-py
Description: # extra-context
        
        Sometimes, when you get warnings and exeptions, backtraces are just not enough.
        For example, you have a loop with 10.000 iterations. In the 1000th iteration there is an 
        exception in a function you called. So you would like to have more context for the error message.
        
        There are 2 options
        * give more context at the site the exception occured
          * Only possible if you control the exception/warning generation
          * Sometimes, there is not enough context to begin with (i.e. you are calling some common utility function)
          
        * Provide additional context as the exception/warning is passed up the call stack
          * Can be "opt-in" in user-code, no changes in libraries required.
          * Also works for warnings (which normally don't provide backtrace information)
        
        ## Examples
        
        The main example that inspired writing this library:
        ```python
        to_process = { "file1": {...}, "file2": {...}, ...}
        
        for k, v in to_process.items():
            cleaned = clean_data(v)
            write_output(k, cleaned)
        ```
        
        If there is an exception or warning somewhere in `clean_data(v)`, the "context" i.e. from which
        file the data came is lost. The backtrace could look something like:
        ```
          File "clean.py", line 35, in clean_data
        ZeroDivisionError: division by zero
        ```
        
        Now, with this library you can give extra context to your error messages
        
        ```python
        from extra_context import provide_extra_context
        
        to_process = { "file1": {...}, "file2": {...}, ...}
        
        for k, v in to_process.items():
            with provide_extra_context(filename=k):
                cleaned = clean_data(v)
                write_output(k, cleaned)
        ```
        
        This would report the same error as:
        ```
          File "clean.py", line 35, in clean_data
        ZeroDivisionError: division by zero
          |- In context: filename='file4'
        ```
        
        ### Decorator
        There is also a decorator that reports the function arguments in case of an error
        
        ```python
        import warnings
        from extra_context import provide_call_context
        
        @provide_call_context
        def w(x):
            warnings.warn("Oops")
        
        w(42)
        ```
        
        This reports:
        ```
        UserWarning: Oops
          |- In context: w(42)
          warnings.warn("Oops")
        ``` 
        
        
        ## License
        
        Copyright 2018 Moritz Wanzenböck
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
        documentation files (the "Software"), to deal in the Software without restriction, including without limitation
        the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
        Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
        WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
        COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
        OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
        
Keywords: warnings exception context logging
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Logging
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
Provides-Extra: test
