Metadata-Version: 2.1
Name: configlines
Version: 0.3
Summary: Add line number information to ConfigParser options
Home-page: https://github.com/benfogle/configlines
Author: Benjamin Fogle
Author-email: benfogle@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.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
Requires-Dist: six

.. image:: https://travis-ci.org/benfogle/configlines.svg?branch=master
    :target: https://travis-ci.org/benfogle/configlines

.. image:: https://codecov.io/gh/benfogle/configlines/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/benfogle/configlines


Description
-----------
This module is an extension to Python's standard `configparser`_ module
that adds file and line number information to each stored option. This
is primarily useful in reporting error messages: you can point your user
to exactly where a bad value occurred:

.. code:: python

    try:
        timeout = config.getint('connection', 'retry')
    except ValueError:
        filename, line = config.get_location('connection', 'retry')
        logging.error("retry must be an integer (%s:%d)", filename, line)
        ...

This package is compatible with both Python 2 and 3.

Installation
------------

Install with pip::

    $ pip install configlines

Usage
-----

Given the following two configuration files:

.. code:: ini

    # Line one of data1.cfg
    [some_section]
    foo = 1

    [DEFAULT]
    bar = 2

.. code:: ini

    # Line one of data2.cfg
    [some_section]
    baz = 3

You can read and manipulate them exactly the same as the standard module:

.. code:: python

    >>> from configlines import ConfigParser
    >>> cfg = ConfigParser()
    >>> cfg.read(['data1.cfg', 'data2.cfg'])
    >>> cfg.get('some_section', 'foo')
    '1'

You can also access file and line information:

.. code:: python

    >>> cfg.get_location('some_section', 'foo')
    ('data1.cfg', 3)
    >>> cfg.get_location('some_section', 'bar')
    ('data1.cfg', 6)
    >>> cfg.get_location('some_section', 'baz')
    ('data2.cfg', 3)

In addition to ``get_location``, this module also provides ``get_line`` and
``get_filename`` functions for convenience.

If an option didn't come from a file, (i.e., you set it programmatically,) then
line number information will not be present:

.. code:: python

    >>> cfg.set('some_section', 'qwerty', '1234')
    >>> cfg.get_location('some_section', 'qwerty')
    None

Overwriting options programmatically will erase line number information:

.. code:: python

    >>> cfg.get_location('some_section', 'foo')
    ('data1.cfg', 3)
    >>> cfg.set('some_section', 'foo', '1234')
    >>> cfg.get_location('some_section', 'foo')
    None

Line number information can be set explicitly:

.. code:: python

    >>> cfg.set('some_section', 'foo', '1234', location=('somefile.cfg',10))
    >>> cfg.get_location('some_section', 'foo')
    ('somefile.cfg', 10)
    >>> cfg.set('some_section', 'foo', '1234', location='preserve')
    >>> cfg.get_location('some_section', 'foo')
    ('somefile.cfg', 10)
    >>> cfg.set_location('some_section', 'foo', ('otherfile.cfg', 50))
    >>> cfg.get_location('some_section', 'foo')
    ('otherfile.cfg', 50)

.. _configparser: https://docs.python.org/3/library/configparser.html



