Metadata-Version: 1.1
Name: api-shop
Version: 1.7.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 <./README.EN.MD>`_
        =========================================
        
        ..
        
           api-shop：一个易用的、快速的restful-api接口工具包，兼容：\ ``django`` / ``flask`` / ``bottle``\ 。
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
           ``一切只为少加班。``
           ^^^^^^^^^^^^^^^^^^^^^^^^
        
        
        **demo 图片**
        -----------------
        
        
        .. image:: /static/demo.png
           :target: /static/demo.png
           :alt: demo
        
        
        **核心功能：**
        ------------------
        
        
        #. 配置化api生成。
        #. 自动校验request提交的数据，并转换成指定格式，支持：int，float，list，dict，set，tuple，bool
        #. 自动生成api文档，并提供一个web页面可供查询和mock数据演示。
        #. 兼容 ``django`` , ``flask`` , ``bottle`` (如果不指定框架，默认按这个顺序识别框架)
        #. 自动生成接口\ ``骨架文件``\ 功能。
        #. 自定义格式转换器，data_format.datetime格式转换类；'2019-01-18 23:25:25' to datetime
        #. 多国语言支持，也支持自定义语言包。
        #. 文档热重载。
        #. 默认值支持方法函数。
        #. 支持url中包含参数，例如 ``/api/user/<id>``\ ，并且在配置methods参数的时候设置它的规则。
        
        **更新记录：**
        ------------------
        
        ..
        
           2019-03-15 
        
           var 1.7.2
        
        
           * 进一步抽象优化代码，便于添加新框架支持。
           * 添加bottle框架支持。
           * 添加bad_request_error_status参数，当bad_request==False的时候，bad_request_error_status是返回给坏请求的自定义错误状态信息
        
           2019-03-14
        
           ver 1.7.1
        
        
           * 优化框架加载逻辑，默认加载框架顺序\ ``django`` -> ``flask``\ ；添加配置参数直接指定框架。
           * 优化部分正则处理逻辑。
        
           2019-03-12
        
           ver 1.7.0
        
        
           * 添加根据配置文件自动生成接口骨架文件：当你添加conf内容的时候，api-shop会根据其内容自动创建
             目录、文件、引入模块、创建类和方法，以及根据接口配置的参数创建备注信息，减少你的代码量。
           * 例如：
             .. code-block:: python
        
                af = ApiShop(conf,
                  {
                      'lang': 'zh',
                      'name_classification': ['微信', '账户'],
                      'url_classification': ['weixin', 'login'],
                      'auto_create_folder': True,  # 自动创建文件夹
                      'auto_create_file': True,  # 自动创建文件
                      'auto_create_class': True,  # 自动创建类
                      'auto_create_method': True,  # 自动创建方法
                  })
        
        
        生成后的文件
        
        .. code-block:: python
        
           # api-shop automatically inserts code
           from api_shop import Api
        
        
           class api_login(Api):
               """微信账户登录"""
               pass
               def post(self, request, data):
                   """ todo:
                   api-shop automatically inserts code
                   data.username # 用户名
                   data.ddd # 日期
                   """
                   pass
        
        ..
        
           2019-03-06
        
           ver 1.6.7
        
        
           * 添加url参数支持
           * 例如：
             ```python
             conf = [{
             .. code-block::
        
                  'url': 'weixin/<name>/<id>',
                  'class': 'business_code.views.test',
                  'name': 'test api',
                  'methods': {
        
        
        .. code-block::
        
                   'POST': [
                       {'name': 'id', 'type': int, 'required': True, 'description': '用户id'},
                       {'name': 'name', 'type': str, 'min':4,'required': True,'description': '用户name'}, 
                   ],
               }
           },]
        
        .. code-block::
        
        
        
        
           > 2019-02-25
           >
           > ver 1.6.5
           - 添加空Response支持，Api方法可以不返回任何值
           - 添加对bool参数类型的支持
           - 接口文档支持过滤（需配置options）
        
        
        
           ## **用法：**
           1. 安装：
           ```sh
           sudo pip install api-shop
        
        
        #. 引入：
           .. code-block:: python
        
              from api_shop from ApiShop,Api,data_format
        
        .. list-table::
           :header-rows: 1
        
           * - 模块名字
             - 功能说明
             - 模块介绍
           * - ApiShop
             - api初始化类
             - 用以加载conf和options
           * - Api
             - 业务继承类
             - 用来继承后写实际的业务代码
        
        
        
        #. 初始化
           ``` python
           conf = [
            {
           .. code-block::
        
               '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':[]
               }
            },
           ]
        
        .. code-block::
        
           > 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. 配置
           ```python
           options = {
                           'base_url':'/api/',
                           'bad_request': True,
                           'document': BASE_DIR + '/api_shop/static/document.html', 
                           'lang':'en',
                           'lang_pack':{}
                       }
        
        ..
        
           options 配置说明
        
           .. list-table::
              :header-rows: 1
        
              * - 键
                - 值类型
                - 默认值
                - 说明
              * - base_url
                - str
                - /api/
                - 接口url前缀
              * - bad_request
                - bool
                - True
                - 如果请求不合法，是否以坏请求方式返回；否则就是全部是200返回
              * - bad_request_error_status
                - str,int,bool
                - 'error'
                - 如果bad_request参数设置为False，那么这个参数就会启用，会在坏请求里附带一个status='error'的信息，你可以自定义这个信息。
              * - document
                - str(path)
                - 略
                - 文档页面的html模板所在的路径，默认会有一个简易模板
              * - lang
                - str
                - en
                - 多国语言支持，目前内置en, zh
              * - lang_pack
                - dict
                - 无
                - 扩展语言包，如果你想让api-shop支持更多语言
              * - name_classification
                - list
                - 无
                - 用于默认的文档模板对接口名称进行过滤，便于查找
              * - url_classification
                - list
                - 无
                - 用于默认的文档模板对接口url进行过滤，便于查找。例子：'url_classification':['weixin','login']
              * - auto_create_folder
                - bool
                - False
                - 自动创建文件夹
              * - auto_create_file
                - bool
                - False
                - 自动创建文件
              * - auto_create_class
                - bool
                - False
                - 自动创建类
              * - auto_create_method
                - bool
                - False
                - 自动创建方法
              * - framework
                - str
                - 无
                - 手动指定框架，目前支持django、flask、bottle，如果不指定，将按顺序识别框架，如果同时安装了多个框架，请手动指定。
        
        
           lang_pack 语言包
        
           value 就是目标语言
        
           .. code-block:: python
        
              'lang_pack':{
                  'zh': {
                          'no attributes found': '没有找到属性：',
                          'not found in conf': '在conf参数中没找到方法: ',
                          'no such interface': '没有这个接口',
                          'is required': '是必要的',
                          'parameter': '参数',
                          'can not be empty': '不能为空',
                          'must be type': '必须是类型',
                          'minimum length': '最小长度',
                          'minimum value': '最小值',
                          'maximum length': '最大长度',
                          'maximum value': '最大值',
                          'The wrong configuration, methons must be loaded inside the list container.': '错误的配置，methons必须装的list容器内。',
                          'no such interface method': '这个接口没有这个method',
                          'Framework version is not compatible.': 'api-shop不支持当前框架版本。',
                          'Not support': '不支持',
                          'supported framework as follows:': '支持的框架如下：',
                          'Did not find the framework':'没找指定的框架，请安装',
                      }
              }
        
        
        
        #. 自定义格式转换器
           .. code-block:: 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')
        
        例子
        ----
        
        
        #. [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': '密码'},
                    ]
        
        .. code-block::
        
                   ## 这里可以插入更多的methods，比如GET,DELETE,POST,PATCH
               }
           },
           ## 这里可以插入更多的api接口
        
        
        ]
        
        api-shop参数设置：
        ------------------
        
        options = {
                    'base_url':'/api/',# 基础url，用以组合给前端的api url 可默认
        
        .. code-block::
        
                   # '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'([\s\S]*)', ap.api_entry, name='index') # 接管api/下面其他的全部路由到api_entry入口方法
        ]
        
        .. code-block::
        
        
           ### 
           ```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 {'status': 'success', 'msg': '执行成功', 'token': token}
        
                   return {'status': 'error', 'msg': '用户登录失败'},400
        
        
        #. [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/regex("([\s\S]*)"):url',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)
        
        .. code-block::
        
           return af.api_entry(request,url)
        
        
        if **name** == '\ **main**\ ':
            app.run(host="0.0.0.0",debug=True)
        
        .. code-block::
        
        
        
        
           3. [bottle例子]
           ```python
           from bottle import route, run, template, request,HTTPResponse
           from src.api_shop import ApiShop
        
           conf = [
               {
                   'url': 'weixin/login',
                   'class': 'business_code.test.abc.api_login',
                   'name': '微信账户登录',
                   'methods': {
                       'POST': [
                           {'name': 'username', 'type': str, 'required': True,
                               'min': 3, 'max': 24, 'description': '用户名'},
                           {'name': 'ddd', 'type': str,   'description': '日期'},
                       ]
                   }
               },
               {
                   'url': 'weixin/<name>/<id>',
                   'class': 'business_code.views.test',
                   'name': '账户登录',
                   'methods': {
        
                       'POST': [{'name': 'id', 'type': bool, 'required': True,
                                    'description': '用户id'},
                                    {'name': 'name', 'type': str, 'min':4,'required': True,
                                    'description': '用户name'}, 
                               ],
                   }
               },
           ]
        
           af = ApiShop(conf,
               {
                   'lang': 'zh',
                   'name_classification': ['微信', '账户'],
                   'url_classification': ['weixin', 'login'],
                   'framework':'bottle'
               })
        
        
           @route('/api/<url:re:([\s\S]*)>',['GET','PUT','PATCH','DELETE','POST'])
           def api_index(url):
               print('*'*20,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)
        
           run(host='localhost', port=8080,reloader=True,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
