Metadata-Version: 1.1
Name: api-shop
Version: 1.6.2
Summary: RESTful api shop for django or flask
Home-page: https://github.com/pcloth/api-shop
Author: pcloth
Author-email: pcloth@gmail.com
License: BSD License
Description-Content-Type: UNKNOWN
Description: api-shop
        ========
        
        `English Documents <https://github.com/pcloth/api-shop/blob/master/README.EN.MD>`__
        ======================================
        
            什么是api-shop：提供易用的、轻量化的restful-api接口工具包，基于django或者flask框架。
        
        **demo 图片**
        -------------
        
        .. figure:: /static/demo.png
           :alt: demo
        
           demo
        **核心功能：**
        --------------
        
        1. 配置化api生成。
        2. 自动校验request提交的数据，并转换成制定格式。
        3. 自动生成api文档，并提供一个web页面可供查询和mock数据演示。
        4. 兼容django 和 flask
        5. 容器格式转换：list，dict，set，tuple
        6. 自定义格式转换器，data\_format.datetime格式转换类；'2019-01-18
           23:25:25' to datetime
        7. 多国语言支持。
        8. 文档支持热重载。
        9. 默认值支持方法函数。
        
        **更新记录：**
        --------------
        
            2019-01-30
        
            ver 1.6.2 - 优化项目目录 - 缩短格式转换器类型名称 -
            默认值支持方法函数，比如datetime.now，如果是方法函数，那么将不再自动比较类型和转换了，你需要自己把握好格式。
        
            2019-01-29
        
            ver 1.6.1 - 文档支持热重载 - 文档添加版本支持 - 优化错误提示
        
            2019-01-23
        
            ver 1.6.0
        
        -  添加多国语言支持，可以在options里指定语言或者扩展语言包。
        -  文档改进
        
        **用法：**
        ----------
        
        1. 安装：
        
           .. code:: sh
        
               sudo pip install api-shop
        
        2. 引入：
        
           .. code:: python
        
               from api_shop from ApiShop,Api,data_format
        
        +------------+---------------+------------------------------+
        | 模块名字   | 功能说明      | 模块介绍                     |
        +============+===============+==============================+
        | ApiShop    | api初始化类   | 用以加载conf和options        |
        +------------+---------------+------------------------------+
        | Api        | 业务继承类    | 用来继承后写实际的业务代码   |
        +------------+---------------+------------------------------+
        
        3. 初始化 \`\`\` python conf = [ { 'url': 'login', 'class':
           'account.views.api\_login', 'name': '账户登录', 'methods': { 'POST':
           [ {'name':'username', 'type': str, 'required': True, 'min': 3, 'max':
           24, 'description': '用户名'}, {'name':'password', 'type': str,
           'required': True, 'min': 3, 'max': 24, 'description': '密码'}, ],
           'GET':` <#section>`__ } }, ]
        
        \`\`\` > conf 配置说明 > 键 \| 值类型 \| 说明 :----------- \|
        :----------- \| -----------: url \| str \|
        接口的url地址，只需要填写相对地址 class \| str,class \|
        接口实际调用的业务类（继承至Api），可以是对象，也可以是引用地址 name \|
        str \| 接口的名字 methods \| dict \| 接口所能接收的methods：有GET POST
        DELETE PUT PATCH
        
            methods 配置说明
        
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
            | 键            | 值类型         | 说明                                                                                                                                                                 |
            +===============+================+======================================================================================================================================================================+
            | name          | str            | 参数名，接收后在data.name                                                                                                                                            |
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
            | type          | class          | str,int,float,bool,list,dict,tuple等等，也支持data\_format.datetime时间格式，你也可以自定义一个类型转换器                                                            |
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
            | required      | bool           | 是否是必要值                                                                                                                                                         |
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
            | default       | str,function   | 当没有接收到时的默认值，注意，它也会被type所指定的类型转换器转换。当它是一个function时，如果没有收到请求参数，将会自动运行这个方法获取值，同时将不再进行类型转换。   |
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
            | min           | int,str        | 最小值/最小长度，为字符串时，会被type指定的类型转换器转换。                                                                                                          |
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
            | max           | int,str        | 最大值/最大长度，为字符串时，会被type指定的类型转换器转换。                                                                                                          |
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
            | description   | str            | 功能描述，给前端人员看文档的内容                                                                                                                                     |
            +---------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
        
        4. 配置
        
           .. code:: python
        
               options = {
                               'base_url':'/api/',
                               'bad_request': True,
                               'document': BASE_DIR + '/api_shop/static/document.html', 
                               'lang':'en',
                               'lang_pack':{}
                           }
        
               options 配置说明
        
               +----------------+-------------+----------+---------------------------------------------------------------+
               | 键             | 值类型      | 默认值   | 说明                                                          |
               +================+=============+==========+===============================================================+
               | base\_url      | str         | /api/    | 接口url前缀                                                   |
               +----------------+-------------+----------+---------------------------------------------------------------+
               | bad\_request   | bool        | True     | 如果请求不合法，是否以坏请求方式返回；否则就是全部是200返回   |
               +----------------+-------------+----------+---------------------------------------------------------------+
               | document       | str(path)   | 略       | 文档页面的html模板所在的路径，默认会有一个简易模板            |
               +----------------+-------------+----------+---------------------------------------------------------------+
               | lang           | str         | en       | 多国语言支持，目前内置en, zh                                  |
               +----------------+-------------+----------+---------------------------------------------------------------+
               | lang\_pack     | dict        | 无       | 扩展语言包，如果你想让api-shop支持更多语言                    |
               +----------------+-------------+----------+---------------------------------------------------------------+
        
            lang\_pack 语言包
        
            value 就是目标语言
        
        .. code:: python
        
            'lang_pack':{
                'en': {
                        'django version error': 'Django version is not compatible',
                        'not flask or django': 'Currently only compatible with django and flask',
                        'no attributes found': 'No attributes found: ',
                        'not found in conf': 'Not found in conf: ',
                        'document template not found': 'Document template not found',
                        'no such interface': 'No such interface',
                        'is required': 'is required',
                        'parameter': 'Parameter',
                        'can not be empty': 'can not be empty',
                        'must be type': 'must be type',
                        'minimum length': 'minimum length',
                        'minimum value': 'minimum value',
                        'maximum length': 'maximum length',
                        'maximum value': 'maximum value',
                        'The wrong configuration, methons must be loaded inside the list container.': 'The wrong configuration, methons must be loaded inside the list container.',
                        'no such interface method': 'No such interface method',
                    }
            }
        
        1. 自定义格式转换器
        
           .. code:: python
        
               # 使用自定义格式转换器的时候，min和max也会自动加载这个转换器转换了进行比较
               from datetime import datetime as dt
               class datetime():
                   '''将str转换成datetime格式'''
                   def __new__(self, string):
                       if ':' in string:
                           return dt.strptime(string, '%Y-%m-%d %H:%M:%S')
                       else:
                           return dt.strptime(string, '%Y-%m-%d')
        
        例子
        ----
        
        1. [Django例子] \`\`\`python ## urls.py from api\_shop import ApiShop
        
        接口配置数据
        ------------
        
        conf = [ { 'url': 'login', 'class': 'account.views.api\_login',
        #需要引入的api类，继承于上面说的Api接口类 'name': '账户登录', 'methods':
        { 'POST': [ {'name':'username', 'type': str, 'required': True, 'min': 3,
        'max': 24, 'description': '用户名'}, {'name':'password', 'type': str,
        'required': True, 'min': 3, 'max': 24, 'description': '密码'}, ] ##
        这里可以插入更多的methods，比如GET,DELETE,POST,PATCH } }, ##
        这里可以插入更多的api接口
        
        ]
        
        api-shop参数设置：
        ------------------
        
        options = { 'base\_url':'/api/',# 基础url，用以组合给前端的api url
        可默认 # 'document':BASE\_DIR+'/api\_shop/static/document.html', #
        文档路由渲染的模板 可默认 'bad\_request':True, #
        参数bad\_request如果是真，发生错误返回一个坏请求给前端，否则都返回200的response，里面附带status=error和msg附带错误信息
        可默认 }
        
        ap = ApiShop(conf,options)
        
        app\_name='api'
        
        urlpatterns = [ path('api\_data', ap.get\_api\_data, name='api\_data'),
        # api文档需要的接口 path('document/', ap.render\_documents,
        name='document'), #api文档渲染的路由 re\_path(r'([]\*)', ap.api\_entry,
        name='index') # 接管api/下面其他的全部路由到api\_entry入口方法 ]
        
        \`\`\`
        
        .. code:: python
        
            ## account/views.py
            from api_shop from Api
        
            class api_login(Api):
                def post(self,request,data=None):
                    '''api登陆接口，方便微信用户绑定账户'''
                    username = data.username
                    password = data.password
                    user = authenticate(username=username, password=password)
                    if user:
                        login(request, user)
                        token = TokenBackend.make_token(user).decode('utf-8')
                        return JsonResponse({'status': 'success', 'msg': '执行成功', 'token': token})
                    
                    return JsonResponse({'status': 'error', 'msg': '用户登录失败'})
        
        2. [flask例子] \`\`\`python from flask import
           Flask,request,render\_template\_string
        
        from werkzeug.routing import BaseConverter
        
        from api\_shop import ApiShop,Api
        
        class RegexConverter(BaseConverter): def **init**\ (self, map, \*args):
        self.map = map self.regex = args[0]
        
        app = Flask(\ **name**) #
        如果使用蓝图，添加正则处理器必须是在注册蓝图之前使用。
        app.url\_map.converters['regex'] = RegexConverter
        
        conf = [ { 'url': 'login', 'class': 'api.views.api\_login', 'name':
        '账户登录', 'methods': { 'POST': [ {'name':'username', 'type': str,
        'required': True, 'min': 3, 'max': 24, 'description': '用户名'},
        {'name':'password', 'type': str, 'required': True, 'min': 3, 'max': 24,
        'description': '密码'}, ] } }, { 'url': 'test', 'class':
        'api.views.test', 'name': '测试数据', 'methods': { 'GET':[{'name':'bb',
        'type': int, 'required': True, 'min': 0, 'max': 100, 'description':
        '百分比','default':95},], 'POST': [ {'name':'add', 'type': str,
        'required': True, 'min': 3, 'max': 24, 'description': '地址'},
        {'name':'bb', 'type': int, 'required': True, 'min': 0, 'max': 100,
        'description': '百分比','default':95}, {'name':'list', 'type': list,
        'description': '列表'}, ], 'DELETE':[ {'name':'id', 'type': int,
        'required': True, 'min': 1,'description': '编号'}, ] } },
        
        ]
        
        af = ApiShop(conf)
        
        @app.route('/api/',methods=['GET', 'POST','PUT','DELETE','PATCH']) def
        hello\_world(url): print(url) if url=='document/': return
        af.render\_documents(request,url) if url=='api\_data': return
        af.get\_api\_data(request,url)
        
        ::
        
            return af.api_entry(request,url)
        
        if **name** == '**main**\ ': app.run(host="0.0.0.0",debug=True) \`\`\`
        
Keywords: api-shop,Flask-RESTful,Django REST framework,RESTful
Platform: all
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation
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: Topic :: Software Development :: Libraries
