Metadata-Version: 1.1
Name: api-shop
Version: 1.7.0
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框架。
        
        
        
        **核心功能：**
        ------------------
        
        
        #. 配置化api生成。
        #. 自动校验request提交的数据，并转换成指定格式，支持：int，float，list，dict，set，tuple，bool
        #. 自动生成api文档，并提供一个web页面可供查询和mock数据演示。
        #. 兼容 ``django`` 和 ``flask`` 。
        #. 自动生成接口\ ``骨架文件``\ 功能。
        #. 自定义格式转换器，data_format.datetime格式转换类；'2019-01-18 23:25:25' to datetime
        #. 多国语言支持。
        #. 文档支持热重载。
        #. 默认值支持方法函数。
        #. 支持url中包含参数，例如 ``/api/user/<id>``\ ，并且在配置methods参数的时候设置它的规则。
        
        **更新记录：**
        ------------------
        
        ..
        
           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）
        
           > 2019-02-11
           >
           > ver 1.6.4
           - 修复默认值为 int:0的时候，不触发的问题。
        
        
           > 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. 安装：
           ```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返回
              * - 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
                - 自动创建方法
        
        
           lang_pack 语言包
        
           value 就是目标语言
        
           .. code-block:: 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',
                      }
              }
        
        
        
        #. 自定义格式转换器
           .. 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)
        ```
        
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
