Metadata-Version: 2.1
Name: KaKa
Version: 0.1.1
Summary: A simple and easy-to-use web framework
Home-page: https://github.com/zlw10100/kaka/
Author: zouliwei
Author-email: 330494152@qq.com
License: BSD
Keywords: pip,web,framework,wsgi,restful
Platform: any
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Dist: Werkzeug (>=0.14.1)
Requires-Dist: jinja2 (>=2.10)


# KaKa

一个基于`werkzeug`和`jinja2`的`web`框架，简单易用、架构清晰、模块化。

## 快速开始
### 安装并引入
使用如下命令安装KaKa:

    pip install KaKa

使用如下命令将框架引入你的项目：

    from kaka import KaKa

### 实例化应用
使用如下语句实例化一个`KaKa`应用对象：

    app = KaKa()

### 定义视图函数
使用如下语句定义一个简单的视图函数，此函数将会接受`http`请求并返回一个简单的`hello world`字符串:

    from kaka.response import TextResponse

    def hello(request):
        return TextResponse('hello world')

### 定义路由表
使用如下语句定义一个路由表以指导`http`请求的正确路由：

    app.router.register([
        ('index/', hello),
    ])

### 启动服务器
执行如下语句启动服务器，`KaKa`会帮助我们启动底层的`WSGI`服务器，默认地址是`127.0.0.1`，端口号是`8888`：

    app.run_server()

`KaKa`为`run_server`接口提供了一个`debug`参数，默认值是`False`，若置为`True`则会启动`debug`模式。
在`debug`模式中，任何对源代码的修改都将自动重启服务器，且一旦发生了错误将会在浏览器上以页面的形式显示出错误栈信息。
可以这样开启`debug`模式：

    app.run_server(debug=True)

### 页面展示
打开浏览器并访问`http://127.0.0.1:8888/index/`，你将会看到视图函数返回的`hello world`字符串。

---

## 功能介绍和使用

然而，一个简单的`hello world`页面是不足以解决我们的问题的，下面是`KaKa`框架目前支持的功能介绍和使用说明。

### 路由系统

#### 定义路由表

路由系统是`web`框架最核心的功能之一，`KaKa`使用术语`路由器`和`路由表`来描述路由系统。
`KaKa`的路由系统底层引用了`Werkzeug`的`Map`和`Rule`模块。

一张路由表由一个元组列表表示，其中的元组代表着路由条目信息。
`KaKa`设定路由条目由`3`个参数组成：`url, view, name`，其中`name`可以不提供。
但若为`name`提供了一个值，你就可以通过`reverse`函数来反向解析`url`，像这样：

    from kaka.utils import reverse

    # 路由表
    table = [
        ('index/', index_view),   # 路由条目1
        ('articles/', article_view),  # 路由条目2

        ('home/', home_view, 'home'),  # 路由条目3
    ]

    url = reverse('home')  # url的值是: '/home/'

#### 处理动态元素

如果`url`中有动态的元素，`KaKa`也可以处理，动态元素将会作为视图函数的参数传入，就像这样：

    table = [
        ('articles/<int:id>/', show_articles, 'article'),
    ]

#### 多级路由

`KaKa`的路由系统还支持多级路由，这一部分的介绍和使用我将会放到产品文档中。


### 视图系统
#### 视图传参
视图系统是处理`http`请求并返回`http`响应的地方。
`KaKa`为所有的视图函数提供了一个`request`第一参数，代表当前的请求对象，用户可以通过此对象访问有底层请求环境的相关数据。

#### 响应对象
`KaKa`使用`TextResponse`类来封装字符串形式的返回值，这种返回值的`mimetype=text/plain`，所以它不会被浏览器当做`html`页面渲染，而是直接打印字符串。
像这样使用视图系统：

    from kaka.response import TextResponse

    def show_articles(request, nid):
        print(request.path)
        print(request.cookies)
        print(request.method)
        print(nid)

        return TextResponse('show articles view')

### 模板渲染
#### 模板目录设定
模板渲染功能可以让我们方便的制造含有动态元素的`html`页面。
在渲染功能上，`KaKa`目前没有做太多事情，仅是在底层引用了`jinja2`模块并为模板渲染过程提供了一层方便调用的接口。
在使用渲染功能前首先定义模板文件目录：

    # 设定模板文件所在目录
    template_path = 'your template directory'
    app.render.register(template_path)

#### 渲染调用
`KaKa`为用户提供了一个`RenderResponse`响应对象，其底层调用了`jinja2`的渲染接口。
渲染的结果类型将会是`mimetype=text/html`，所以浏览器会将结果当做`html`页面渲染并展示。

    from kaka.response import RenderResponse

    # 在视图函数中使用模板渲染功能
    def show_articles(request, id):
        title = 'hello kaka'
        content = 'a web framework'

        return RenderResponse('article.html', title=title, content=content)


### `Restful`支持

#### `Restful`视图定义
当然，`KaKa`也支持`Restful`形式的请求处理，`KaKa`使用了一个`RestView`来帮助分发请求，像这样定义`restful`的视图函数：

    from kaka.restful import RestView

    # 定义restful形式的处理视图，必须以类的形式定义
    class ArticlesView(RestView):
        def get(self, request, id):
            pass

        def post(self, request)
            pass

        ...  # 其他与http method同名的函数

#### `Restful`视图路由
`restful`的视图函数可以像这样添加到路由表中：

    table = [
        ('index/', index),
        ('articles/', ArticlesView.restful, 'article),  # 使用类名.restful即可
    ]

#### `Restful`视图响应
`KaKa`除了支持`restful`的请求之外还支持`restful`的响应，使用了`RestResponse`响应类，它的`mimetype=application/json`, 所以一个`restful`响应的使用和样式是这样的：

    from kaka.restful import RestView
    from kaka.response import RestResponse  # restful风格的响应类

    class ArticlesView(RestView):
        def get(self, request, id):
            data = {'title': 'hello kaka', 'content': 'a web framework'}
            extra_dict = {
                'data': data,
            }
            return RestResponse(code=1200, status='success', extra_dict=extra_dict)

    # 这样的响应在浏览器中看起来是这样的：
    {
        "code": 1200,
        "status": "success",
        "data": {
            "title": "hello kaka",
            "content": "a web framework"
        }
    }

#### 高层`Restful`调用接口
在`restful`的支持上，`KaKa`还提供了更高一层的`SUCCESS`和`FAIL`接口，为用户提供了更加方便的操作`restful`响应的形式，不过这两个接口的介绍和使用说明我将会放到产品文档中。

### 中间件系统

#### 处理机制解释
`KaKa`提供了中间件系统，让用户可以在视图处理前和处理后对请求(或响应)对象完成必要的中间操作。
我认为中间件系统的主要目的是**修改**流经的请求或响应对象，而**不是伪造**一个新的对象，这意味着`KaKa`提供的中间件系统的处理机制是这样的：

* 视图前

    `KaKa`的中间件系统在视图前的处理只允许返回`None`或一个响应对象(这意味着后续中间件不再有机会处理请求，视图函数也是)。换句话说，返回`None`意味着中间件仅仅对请求对象执行修改操作而不是替换它，返回一个响应对象意味着中间件拦截了这个请求并直接返回。

* 视图后

    `KaKa`的中间件系统在视图后的处理只允许返回`None`，这意味着中间件只能修改响应对象而不能替换它。

*关于中间件系统的详细设计思路和结构请参考产品文档。*

#### 定义中间件
我们可以通过这种方式自定义一个中间件：

    from kaka.middlewares import AbstractMiddleWare  # 抽象中间件类，用于约束处理接口
    from kaka.response import TextResponse

    class MyMiddleWare(AbstractMiddleWare):
        def pre_process(self, request):
            print('对请求对象做各种修改操作')
            return None

            # 如果要拦截当前请求，则这样写：
            # return TextResponse('中间件拦截请求，直接返回响应对象')

        def after_process(self, request, response):
            print('对响应对象做各种修改操作', response)
            return None

#### 注册中间件
然后通过中间件管理器注册这个中间件以使其生效：

    import MyMiddleWare

    app.mw_manager.register([
        (5, MyMiddleWare),  # priority, cls
    ])
其中，`5`是表示优先级的数字，最小为0，最大无限制，**数字越小优先级越高**。


#### 多个中间件的执行顺序
如果定义了多个中间件(很常见的情况)，则它们的处理顺序是这样的：

    app.mw_manager.register([
        (5, MW1),
        (7, MW2),
        (9, MW3),
    ])

    # 视图前：MW1处理请求 -> MW2处理请求 -> MW3处理请求 
    # 视图后：MW3处理响应 -> MW2处理响应 -> MW1处理响应

#### 多个中间件的数据共享
`KaKa`对请求对象和响应对象均设置了一个`storage`属性用以共享数据，它使用起来像这样：

    # 请求中间件中的使用
    def pre_process(self, request):
        request.storage['is_handled'] = True

        return None

    # 视图中的使用
    def show_articles(request):
        print(request.storage.get('is_handled'))
        response = TextResponse('hello world')
        response.storage['name'] = 'kaka'

        return response

    # 响应中间件中的使用
    def after_process(self, request, response):
        print(request.get('is_handled'))
        print(response.get('name'))

        return None