ezcf 0.2.1

ezcf
====

|构建状态| |支持的 Python 版本| |PyPI 版本| |覆盖
状态|

ezcf 代表 **easy configuration**，它允许您导入
JSON/YAML/INI/XML 之类的 .py 文件。
当您需要读取这些格式 时，它很有用 ，尤其是在读取配置文件时。

好吧，别说了，给我们看一些代码！

左边是你通常会做的，右边是ezcf方式。
**您只需要先“import ezcf”，然后是
不带扩展名的“import filename”。** 没有别的！

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

例如，这里我们要加载文件``config.json``。用单
一行代码``from config import *``，一切都完成了，你很
高兴。

安装
--------

::

pip install ezcf

如果你遇到``error: yaml.h: No such file or directory``，别
担心，你仍然可以毫无问题地使用ezcf。

支持的文件类型
--------------------

ezcf 支持带扩展名的 ``JSON``、``YAML``、``INI`` 和 ``XML``
``json``，``yaml``，``yml``，``ini``，``xml``。

示例用法
------------

让我们从一个简单的案例开始：

::

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

``sample1.py`` 和 ``sample1.json``在同一个目录中。我们想要
要在 ``sample1.py`` 中阅读 ``sample1.json``，方法如下：

.. code:: python

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

# sample1.py
import ezcf
from sample1 import hello

print(hello) # 'world'

就这么简单。

这很酷，但我们通常将配置文件放在单独的文件夹中。ezcf 可以
处理吗？

::

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

为什么不呢？

.. 代码:: python

"""sample2.


用户：ed
警告：
这是一个警告。
---
堆栈：
- 文件：TopClass.py
行：23
代码：|
x = MoreObject("345\n")
- 文件：MoreClass.py
行：58
代码：|-
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 # 这是一个警告。
堆栈 # [{'line': 23, 'code': 'x = MoreObject("345\\n")\n', 'file': 'TopClass.py'}, {'line': 58, 'code ': 'foo = bar', 'file': 'MoreClass.py'}]

ezcf 支持各种有效的导入语句。这些语句是
等价的：

.. 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

总之，你可以假设它们只是普通的python文件。（目前
ezcf只支持utf-8编码的文件）

相对导入呢？是的，


注意
----

1. 注意导入包含多个文档的YAML：如果
存在同名的key，则只会加载其中一个。所以
最好不要使用多个文档；
2. ``.ini`` 文件中的所有值都保持原样并作为
字符串加载；
3. 由于xml只允许单个root，整个xml将被加载为
一个dict，root的名称为变量名；
4.使用`**valid variable
names** <https://docs.python.org/3.4/reference/lexical_analysis.html#identifiers>`__，
这意味着JSON/YAML/INI/XML中的key strings应该是有效的Python
变量名。无效的变量名不会对您造成任何伤害
程序也不会崩溃，但你不能按预期使用它们。

运行测试
---------

::

python setup.py test

Roadmap
--------

- [x] 使用点分隔文件夹/子文件夹/文件
- [x] Unicode 支持
- [x] JSON支持
- [x] YAML 支持
- [x] INI 支持
- [x] XML 支持
- [] 自动编码检测？
- [x] CI
- [x] 覆盖率
- [x] pypi

许可证
-------

MIT

.. |构建状态| 图片：：https
://travis-ci.org/laike9m/ezcf.svg：目标：https://travis-ci.org/laike9m/ezcf
.. |支持的 Python 版本| 图片:: https://img.shields.io/pypi/pyversions/ezcf.svg
:目标: https://pypi.python.org/pypi/ezcf/
.. |PyPI 版本| 图片:: https://badge.fury.io/py/ezcf.svg
:target: http://badge.fury.io/py/ezcf
.. |覆盖状态| 图片：：https
://coveralls.io/repos/laike9m/ezcf/badge.svg：目标：https://coveralls.io/r/laike9m/ezcf