一個(gè) Python 和 JavaScript 交換數(shù)據(jù)的庫(kù)

作者：telepath 2021-05-19 22:23:56

telepath是一個(gè)Django庫(kù)，用于在Python和JavaScript之間交換數(shù)據(jù)，使您可以構(gòu)建具有豐富客戶端接口的應(yīng)用程序，同時(shí)將業(yè)務(wù)邏輯保留在服務(wù)器端代碼中。

[[400553]]

本文轉(zhuǎn)載自微信公眾號(hào)「Python中文社區(qū)」，作者telepath。轉(zhuǎn)載本文請(qǐng)聯(lián)系Python中文社區(qū)公眾號(hào)。

它有什么作用?

它提供了一種將包括Python對(duì)象在內(nèi)的結(jié)構(gòu)化數(shù)據(jù)打包為JSON可序列化格式的機(jī)制。通過(guò)向相應(yīng)的JavaScript實(shí)現(xiàn)注冊(cè)該機(jī)制，可以擴(kuò)展該機(jī)制以支持任何Python類。然后，打包的數(shù)據(jù)可以包含在HTTP響應(yīng)中，并在JavaScript中解壓縮以獲得與原始數(shù)據(jù)等效的數(shù)據(jù)結(jié)構(gòu)。

安裝方法

pip install telepath

并將'telepath'添加到項(xiàng)目的INSTALLED_APPS。

簡(jiǎn)介

假設(shè)我們正在構(gòu)建一個(gè)用于玩跳棋的Django應(yīng)用。我們已經(jīng)花費(fèi)了數(shù)天或數(shù)周的時(shí)間，構(gòu)建了游戲規(guī)則的Python實(shí)現(xiàn)，并提供了代表當(dāng)前游戲狀態(tài)和各個(gè)部分的類。但是，我們還希望為播放器提供一個(gè)適當(dāng)友好的用戶界面，這意味著該是我們編寫JavaScript前端的時(shí)候了。我們的UI代碼不可避免地將擁有自己的對(duì)象，這些對(duì)象代表不同的角色，鏡像我們正在服務(wù)器上跟蹤的數(shù)據(jù)結(jié)構(gòu)——但我們無(wú)法發(fā)送Python對(duì)象，因此將這些數(shù)據(jù)發(fā)送到客戶端通常將意味著設(shè)計(jì)游戲狀態(tài)的JSON表示形式，并在兩端分別設(shè)計(jì)大量樣式代碼，遍歷數(shù)據(jù)結(jié)構(gòu)以在本機(jī)對(duì)象之間來(lái)回轉(zhuǎn)換。讓我們看看telepath如何簡(jiǎn)化該過(guò)程。

一個(gè)完整的跳棋游戲?qū)τ诒窘坛虂?lái)說(shuō)有點(diǎn)太多了，所以我們只選擇渲染這一步...

在Python環(huán)境中，創(chuàng)建一個(gè)新的Django項(xiàng)目：

pip install "Django>=3.1,<3.2" 
django-admin startproject draughts 
cd draughts 
./manage.py startapp games

在draughts / settings.py的INSTALLED_APPS列表中添加'games'。

為簡(jiǎn)單起見，在本示例中，我們將不涉及數(shù)據(jù)庫(kù)，而是將游戲狀態(tài)表示為普通的Python類而不是Django模型。修改games/views.py，如下所示：

from django.shortcuts import render 
 
 
class Piece: 
    def __init__(self, color, position): 
        self.color = color 
        self.position = position 
 
 
class GameState: 
    def __init__(self, pieces): 
        self.pieces = pieces 
 
    @staticmethod 
    def new_game(): 
        black_pieces = [ 
            Piece('black', (x, y)) 
            for y in range(0, 3) 
            for x in range((y + 1) % 2, 8, 2) 
        ] 
        white_pieces = [ 
            Piece('white', (x, y)) 
            for y in range(5, 8) 
            for x in range((y + 1) % 2, 8, 2) 
        ] 
        return GameState(black_pieces + white_pieces) 
 
 
def game(request): 
    game_state = GameState.new_game() 
 
    return render(request, 'game.html', {})

如下所示創(chuàng)建games/templates/game.html：

<!doctype html> 
<html> 
    <head> 
        <title>Draughts</title> 
        <script> 
            document.addEventListener('DOMContentLoaded', event => { 
                const gameElement = document.getElementById('game'); 
                gameElement.innerHTML = 'TODO: render the board here' 
            }); 
        </script> 
    </head> 
    <body> 
        <h1>Draughts</h1> 
        <div id="game"> 
        </div> 
    </body> 
</html>

將新視圖添加到draughts/urls.py:

from django.contrib import admin 
from django.urls import path 
 
from games.views import game 
 
urlpatterns = [ 
    path('', game), 
    path('admin/', admin.site.urls), 
]

現(xiàn)在，使用./manage.py runserver啟動(dòng)服務(wù)器，并訪問(wèn)http：// localhost：8000 /。

到目前為止，我們已經(jīng)創(chuàng)建了一個(gè)代表新游戲的GameState對(duì)象——現(xiàn)在是時(shí)候引入telepath，以便我們可以將該對(duì)象傳輸?shù)娇蛻舳恕?zhí)行下面命令：

pip install telepath

并將'telepath'添加到draughts / settings.py中的INSTALLED_APPS列表中。現(xiàn)在編輯games/views.py文件：

import json 
from django.shortcuts import render 
from telepath import JSContext 
 
# ... 
 
def game(request): 
    game_state = GameState.new_game() 
 
    js_context = JSContext() 
    packed_game_state = js_context.pack(game_state) 
    game_state_json = json.dumps(packed_game_state) 
 
    return render(request, 'game.html', { 
        'game_state_json': game_state_json, 
    })

這里JSContext是一個(gè)幫助工具，用于管理游戲狀態(tài)對(duì)象到我們可以在Javascript中使用的表示形式的轉(zhuǎn)換。js_context.pack接受該對(duì)象并將其轉(zhuǎn)換為可以JSON序列化并傳遞到我們的模板的值。但是，現(xiàn)在重新加載頁(yè)面失敗，并出現(xiàn)以下形式的錯(cuò)誤：don't know how to pack object:

這是因?yàn)镚ameState是Telepath尚不知道如何處理的自定義Python類型。傳遞給pack的任何自定義類型必須鏈接到相應(yīng)的JavaScript實(shí)現(xiàn);這是通過(guò)定義Adapter對(duì)象并將其注冊(cè)到telepath來(lái)完成的。如下更新game / views.py：

import json 
from django.shortcuts import render 
from telepath import Adapter, JSContext, register 
 
# ... 
 
class GameState: 
    # keep definition as before 
 
 
class GameStateAdapter(Adapter): 
    js_constructor = 'draughts.GameState' 
 
    def js_args(self, game_state): 
        return [game_state.pieces] 
 
    class Media: 
        js = ['draughts.js'] 
 
 
register(GameStateAdapter(), GameState)

此處js_constructor是JavaScript構(gòu)造函數(shù)的標(biāo)識(shí)符，該標(biāo)識(shí)符將用于在客戶端上構(gòu)建GameState實(shí)例，并且js_args定義了將傳遞給此構(gòu)造函數(shù)的參數(shù)列表，以重新創(chuàng)建給定game_state對(duì)象的JavaScript對(duì)應(yīng)對(duì)象。Media類指示文件，該文件遵循Django對(duì)格式媒體的約定，可在其中找到GameState的JavaScript實(shí)現(xiàn)。稍后我們將看到此JavaScript實(shí)現(xiàn)的外觀，現(xiàn)在，我們需要為Piece類定義一個(gè)類似的適配器，因?yàn)槲覀儗?duì)GameStateAdapter的定義取決于是否能夠打包Piece實(shí)例。將以下定義添加到games/views.py：

class Piece: 
    # keep definition as before 
 
 
class PieceAdapter(Adapter): 
    js_constructor = 'draughts.Piece' 
 
    def js_args(self, piece): 
        return [piece.color, piece.position] 
 
    class Media: 
        js = ['draughts.js'] 
 
 
register(PieceAdapter(), Piece)

重新加載頁(yè)面，您將看到錯(cuò)誤提示消失了，這表明我們已成功將GameState對(duì)象序列化為JSON并將其傳遞給模板。現(xiàn)在，我們可以將其包含在模板中-編輯games/templates/game.html：

<body> 
       <h1>Draughts</h1> 
       <div id="game" data-game-state="{{ game_state_json }}"> 
       </div> 
   </body>

再次重新加載頁(yè)面，并在瀏覽器的開發(fā)人員工具中檢查游戲元素(在Chrome和Firefox中，右鍵單擊TODO注釋，然后選擇Inspect或Inspect Element)，您將看到GameState對(duì)象的JSON表示，準(zhǔn)備好解壓成完整的JavaScript對(duì)象。

除了將數(shù)據(jù)打包成JSON可序列化的格式外，JSContext對(duì)象還跟蹤將數(shù)據(jù)解壓縮所需的JavaScript媒體定義，作為其媒體屬性。讓我們更新游戲視圖，以將其也傳遞給模板-在games/views.py中：

def game(request): 
    game_state = GameState.new_game() 
 
    js_context = JSContext() 
    packed_game_state = js_context.pack(game_state) 
    game_state_json = json.dumps(packed_game_state) 
 
    return render(request, 'game.html', { 
        'game_state_json': game_state_json, 
        'media': js_context.media, 
    })

將下面代碼添加到games / templates / game.html中的HTML頭文件中：

<head> 
        <title>Draughts</title> 
        {{ media }} 
        <script> 
            document.addEventListener('DOMContentLoaded', event => { 
                const gameElement = document.getElementById('game'); 
                gameElement.innerHTML = 'TODO: render the board here' 
            }); 
        </script> 
    </head>

重新加載頁(yè)面并查看源代碼，您將看到這帶來(lái)了兩個(gè)JavaScript包括 —— telepath.js(客戶端telepath庫(kù)，提供解包機(jī)制)和我們?cè)谶m配器定義中指定的draughts.js文件。后者尚不存在，所以讓我們?cè)趃ames / static / draughts.js中創(chuàng)建它：

class Piece { 
    constructor(color, position) { 
        this.color = color; 
        this.position = position; 
    } 
} 
window.telepath.register('draughts.Piece', Piece); 
 
 
class GameState { 
    constructor(pieces) { 
        this.pieces = pieces; 
    } 
} 
window.telepath.register('draughts.GameState', GameState);

這兩個(gè)類定義實(shí)現(xiàn)了我們先前在適配器對(duì)象中聲明的構(gòu)造函數(shù)-構(gòu)造函數(shù)接收的參數(shù)是js_args定義的參數(shù)。window.telepath.register行將這些類定義附加到通過(guò)js_constructor指定的相應(yīng)標(biāo)識(shí)符。現(xiàn)在，這為我們提供了解壓縮JSON所需的一切-回到games / templates / game.html中，更新JS代碼，如下所示：

<script> 
           document.addEventListener('DOMContentLoaded', event => { 
               const gameElement = document.getElementById('game'); 
               const gameStateJson = gameElement.dataset.gameState; 
               const packedGameState = JSON.parse(gameStateJson); 
               const gameState = window.telepath.unpack(packedGameState); 
               console.log(gameState); 
           }) 
       </script>

您可能需要重新啟動(dòng)服務(wù)器以獲取新的games/static文件夾。重新加載頁(yè)面，然后在瀏覽器控制臺(tái)中，您現(xiàn)在應(yīng)該看到填充了Piece對(duì)象的GameState對(duì)象。現(xiàn)在，我們可以繼續(xù)在games/static/draughts.js中填寫渲染代碼：

class Piece { 
    constructor(color, position) { 
        this.color = color; 
        this.position = position; 
    } 
 
    render(container) { 
        const element = document.createElement('div'); 
        container.appendChild(element); 
        element.style.width = element.style.height = '24px'; 
        element.style.border = '2px solid grey'; 
        element.style.borderRadius = '14px'; 
        element.style.backgroundColor = this.color; 
    } 
} 
window.telepath.register('draughts.Piece', Piece) 
 
 
class GameState { 
    constructor(pieces) { 
        this.pieces = pieces; 
    } 
 
    render(container) { 
        const table = document.createElement('table'); 
        container.appendChild(table); 
        const cells = []; 
        for (let y = 0; y < 8; y++) { 
            let row = document.createElement('tr'); 
            table.appendChild(row); 
            cells[y] = []; 
            for (let x = 0; x < 8; x++) { 
                let cell = document.createElement('td'); 
                row.appendChild(cell); 
                cells[y][x] = cell; 
                cell.style.width = cell.style.height = '32px'; 
                cell.style.backgroundColor = (x + y) % 2 ? 'silver': 'white'; 
            } 
        } 
 
        this.pieces.forEach(piece => { 
            const [x, y] = piece.position; 
            const cell = cells[y][x]; 
            piece.render(cell); 
        }); 
    } 
} 
window.telepath.register('draughts.GameState', GameState)

在games/templates/game.html中添加對(duì)render方法的調(diào)用：

<script> 
            document.addEventListener('DOMContentLoaded', event => { 
                const gameElement = document.getElementById('game'); 
                const gameStateJson = gameElement.dataset.gameState; 
                const packedGameState = JSON.parse(gameStateJson); 
                const gameState = window.telepath.unpack(packedGameState); 
                gameState.render(gameElement); 
            }) 
        </script>

重新加載頁(yè)面，您將看到我們的跳棋程序已準(zhǔn)備就緒，可以開始游戲了。

讓我們快速回顧一下我們已經(jīng)取得的成果：
我們已經(jīng)打包和解包了自定義Python / JavaScript類型的數(shù)據(jù)結(jié)構(gòu)，而無(wú)需編寫代碼來(lái)遞歸該結(jié)構(gòu)。如果我們的GameState對(duì)象變得更復(fù)雜(例如，“棋子”列表可能變成棋子和國(guó)王對(duì)象的混合列表，或者狀態(tài)可能包括游戲歷史)，則無(wú)需重構(gòu)任何數(shù)據(jù)打包/拆包邏輯，除了為每個(gè)使用的類提供一個(gè)適配器對(duì)象。
僅提供了解壓縮頁(yè)面數(shù)據(jù)所需的JS文件-如果我們的游戲應(yīng)用程序擴(kuò)展到包括Chess，Go和Othello，并且所有生成的類都已通過(guò)Telepath注冊(cè)，則我們?nèi)匀恢恍枰峁┡c跳棋知識(shí)相關(guān)的代碼。

即使我們使用任意對(duì)象，也不需要?jiǎng)討B(tài)內(nèi)聯(lián)JavaScript —— 所有動(dòng)態(tài)數(shù)據(jù)都以JSON形式傳遞，并且所有JavaScript代碼在部署時(shí)都是固定的(如果我們的網(wǎng)站強(qiáng)制執(zhí)行CSP，這一點(diǎn)很重要)。

責(zé)任編輯：武曉燕來(lái)源： Python中文社區(qū)