Metadata-Version: 1.0
Name: pyconfigreader
Version: 0.3.3
Summary: A simple module for handling configurations and config files
Home-page: http://github.com/giantas/pyconfigreader
Author: Aswa Paul
Author-email: UNKNOWN
License: MIT
Description: ConfigReader
        ============
        
        |Travis-CI| |Codacy Badge| |Issues|
        
        A configuration file handler for the most basic stuff in ini files that
        will get you up and running in no time.
        
        ``ConfigReader`` uses Python's ConfigParser to parse config files.
        
        ***PS***: This is just to get you working on other stuff and not focus
        on config files. If you need advanced features head to `Python's
        ConfigParser <https://docs.python.org/3/library/configparser.html>`__.
        
        Usage
        =====
        
        Installation
        ------------
        
        ::
        
            $ pip install pyconfigreader
        
        Setting Values
        --------------
        
        ``ConfigReader`` creates a default ``main`` section in which key-value
        pairs are inserted if no section is specified.
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.set('version', '2')  # Saved to section `main`
            config.set('Key', 'Value', section='Section')   # Creates a section `Section` on-the-fly
            config.set('name', 'main')
            config.close(save=True)  # Save on close
            # Or explicitly call
            # config.save()
            # config.close()
        
        By default, changes are not immediately written to the file on disk but
        are kept in memory. ``commit=True`` writes the changes to the file on
        disk.
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.set('okay', 'True', commit=True)
        
        Getting values
        --------------
        
        Getting values only requires specifying the key. If the key does not
        exist then None is returned. No exception is raised.
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            name = config.get('name')
            okay = config.get('okay')
            section = config.get('Key', section='Section')  # Get from the section `Section`
        
            agency = config.get('agency')  # agency is None, it doesn't exist
        
            print(config.sections)  # Get a list of sections
        
            key, value, section = config.search('config')   # Search for the parameters of a value. Returns a tuple
        
            help(config)
            config.close()  # Don't forget to close the file object
        
        Sometimes, if a key is not available a return value may be added
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            name = config.get('country', default='Kenya')   # Returns Kenya since key was not available in config file
            config.close()
        
        The return value, by default, is not saved to file but this can be
        enabled by setting default\_commit=True
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            name = config.get('name', default='Kenya', default_commit=True)
            config.close()
        
        Any call to ``commit`` saves all the in-memory changes to the file on
        disk.
        
        Options
        -------
        
        Options can be remove permanently
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.remove_option('reader')  # the reader option is always set by default
            # or config.remove_key('reader')
            config.set('name', 'first', section='Details')
            config.remove_option('name', section='Details')
            config.close(save=True)
        
        Sections
        --------
        
        Sections are created when keys and values are added to them.
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.set('name', 'first', section='Details')  # Save key `name` with value `first` in section `Details`
            config.close()
        
        Sections can be removed explicitly.
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.set('name', 'first', section='Details') # Creates section `Details`
            config.remove_section('Details')    # Removes section `Details` plus all the keys and values
            config.close(save=True)
        
        Section items can be acquired as dictionary values
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.set('name', 'first', section='Details')
        
            config.get_items('Details')
            # OrderedDict([('name', 'first')])
            config.close()  # Or config.close(save=True)
        
        Environment Variables
        ---------------------
        
        Configuration values can be save to the environment (``os.environ``)
        
        .. code:: python
        
            import os
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.set('name', 'first', section='Details')
            config.to_env()
            os.environ['DETAILS_NAME']
            # first
            os.environ['MAIN_READER']
            # configreader
            config.close()
        
        The environment keys are formed from the section name and the key name.
        
        Saving
        ------
        
        Changes are not written to disk unless ``commit`` is set to True.
        
        Another alternative is calling ``to_file``
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            config = ConfigReader(filename='config.ini')
            config.set('name', 'first', section='Details')
            config.save()
            config.close()
        
        As a context, the changes are saved when the object is closed.
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            with ConfigReader(filename='config.ini') as config:
                config.set('name', 'first', section='Details')
        
        The contents of the config file can also be dumped to a JSON file.
        
        .. code:: python
        
            from pyconfigreader import ConfigReader
            reader = ConfigReader()
            reader.set('name', 'first', section='Details')
            with open('config.json', 'w') as f:
                reader.to_json(f)
                
            reader.close()
        
        A lot more on ``help(config)``
        
        More
        ====
        
        Docs to come :)
        
        License
        =======
        
        Distributed under `MIT <LICENSE>`__
        
        .. |Travis-CI| image:: https://img.shields.io/travis/giantas/pyconfigreader.svg?maxAge=25920
           :target: https://travis-ci.org/giantas/pyconfigreader
        .. |Codacy Badge| image:: https://api.codacy.com/project/badge/Coverage/5f3132cafe78478dbdeb081b53d3661d
           :target: https://www.codacy.com/app/giantas/pyconfigreader?utm_source=github.com&utm_medium=referral&utm_content=giantas/pyconfigreader&utm_campaign=Badge_Coverage
        .. |Issues| image:: https://img.shields.io/github/issues-raw/giantas/pyconfigreader/website.svg
           :target: https://github.com/giantas/pyconfigreader/issues
        
Platform: UNKNOWN
