Metadata-Version: 2.0
Name: ezcf
Version: 0.2.1
Summary: Import JSON/YAML/INI/XML like .py files
Home-page: http://github.com/laike9m/ezcf/
Author: laike9m
Author-email: laike9m@gmail.com
License: MIT
Keywords: config,import,JSON,YAML,INI,XML
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: configobj (==5.0.6)
Requires-Dist: pyyaml (==3.11)
Requires-Dist: xmltodict (==0.9.2)
Provides-Extra: coveralls
Requires-Dist: coveralls; extra == 'coveralls'

ezcf
====

|Build Status| |Supported Python versions| |PyPI version| |Coverage
Status|

ezcf stands for **easy configuration**, it allows you to import
JSON/YAML/INI/XML like .py files. It is useful whenever you need to read
from these formats, especially for reading configuration files.

OK, stop talking, show us some code!

| On the left is what you'll normally do, on the right is the ezcf way.
| **All you need is ``import ezcf`` first, then ``import filename``
  without extension.** Nothing else!

.. figure:: https://github.com/laike9m/ezcf/raw/master/code_compare.png
   :alt: 

For instance, here we want to load file ``config.json``. With a single
line of code ``from config import *``, everything is done and you're
happy.

Install
-------

::

    pip install ezcf

If you run into ``error: yaml.h: No such file or directory``, don't
worry, you can still use ezcf without any problem.

Supported File Types
--------------------

ezcf supports ``JSON``, ``YAML``, ``INI`` and ``XML`` with extension
``json``, ``yaml``, ``yml``, ``ini``, ``xml``.

Sample Usage
------------

Let's start with an easy case:

::

    ├── sample1.py
    └── sample1.json  

``sample1.py`` and ``sample1.json`` are in the same directory. We want
to read ``sample1.json`` in ``sample1.py``, here's how:

.. code:: python

    """
    # sample1.json
    {
        "hello": "world"
    }
    """

    # sample1.py
    import ezcf
    from sample1 import hello

    print(hello)  # 'world'

It's that easy.

 That's cool, but we usually put config files in a separate folder. Can
ezcf deal with that?

::

    ├── conf
    │   ├── __init__.py
    │   └── sample2.yaml
    └── sample2.py

Why not?

.. code:: python

    """sample2.yaml
    ---
    Time: 2001-11-23 15:02:31 -5
    User: ed
    warning:
      This is a warning.
    ---
    Stack:
      - file: TopClass.py
        line: 23
        code: |
          x = MoreObject("345\n")
      - file: MoreClass.py
        line: 58
        code: |-
          foo = bar
    """

    # sample2.py
    import ezcf
    from conf.sample2 import Time, User, warning, Stack

    Time  # datetime.datetime(2001, 11, 23, 20, 2, 31)
    User  # ed
    warning  # This is a warning.
    Stack  # [{'line': 23, 'code': 'x = MoreObject("345\\n")\n', 'file': 'TopClass.py'}, {'line': 58, 'code': 'foo = bar', 'file': 'MoreClass.py'}]

ezcf supports all kinds of valid import statements. These statements are
equivalent:

.. code:: python

    from conf.sample2 import Time, User, warning, Stack
    from conf.sample2 import *
    import conf.sample2  # then use conf.sample2.Time/User/warning/Stack
    import conf.sample2 as cs  # then use cs.Time/User/warning/Stack

In a word, you can assume they're just regular python files.(Currently
ezcf only supports files with utf-8 encoding)

What about relative import? Yes, ezcf supports relative import, as long
as you use it *correctly*.

Note
----

1. Be careful importing YAML which contains multiple documents: if there
   exists keys with the same name, only one of them will be loaded. So
   it's better not to use multiple documents;
2. All values in ``.ini`` files are kept as it is and loaded as a
   string;
3. Since XML only allows single root, the whole xml will be loaded as
   one dict with root's name as variable name;
4. Use `**valid variable
   names** <https://docs.python.org/3.4/reference/lexical_analysis.html#identifiers>`__,
   this means key strings in JSON/YAML/INI/XML should be valid Python
   variable name. Invalid variable name won't do any harm to your
   program nor will it crash, but you can't use them as expected.

Run Tests
---------

::

    python setup.py test

Roadmap
-------

-  [x] Use dot to seperate folder/subfolder/file
-  [x] Unicode support
-  [x] JSON support
-  [x] YAML support
-  [x] INI support
-  [x] XML support
-  [ ] Auto encoding detect?
-  [x] CI
-  [x] coverage
-  [x] pypi

License
-------

MIT

.. |Build Status| image:: https://travis-ci.org/laike9m/ezcf.svg
   :target: https://travis-ci.org/laike9m/ezcf
.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/ezcf.svg
   :target: https://pypi.python.org/pypi/ezcf/
.. |PyPI version| image:: https://badge.fury.io/py/ezcf.svg
   :target: http://badge.fury.io/py/ezcf
.. |Coverage Status| image:: https://coveralls.io/repos/laike9m/ezcf/badge.svg
   :target: https://coveralls.io/r/laike9m/ezcf


