GitHubじゃ!Pythonじゃ!

GitHubからPython関係の優良リポジトリを探したかったのじゃー、でも英語は出来ないから日本語で読むのじゃー、英語社会世知辛いのじゃー

christabor

flask_jsondash – 🐍 📊 📈 フロントエンドコードなしで複雑なダッシュボードを構築する。 独自のエンドポイントを使用します。 J..

投稿日:

🐍 📊 📈 フロントエンドコードなしで複雑なダッシュボードを構築する。 独自のエンドポイントを使用します。 JSON設定のみ。 行く準備ができています。

フラスコJSONダッシュ

任意のAPIエンドポイントからチャートダッシュボードを簡単に設定できます。 JSON設定のみ。 行く準備ができています。

このプロジェクトはフロントエンド(またはバックエンド)コードを書かずに洗練されたダッシュボードを作成できるフロンプラントブループリントです。 すべては、任意のチャートを宣言するための単純なJSON設定によって強化されています。

特徴

  • C3.jsやD3.jsなどの人気のあるライブラリーを活用しています。
  • テンプレートとiframeもサポート
  • 基本的な直観的な構成だけが必要です。
  • ダッシュボードのレイアウトと青写真のスタイルはあらかじめパッケージ化されており、途中で欠かせないものがあります。
  • レイアウトを簡単かつ直感的にドラッグアンドドロップする
  • 複数のレイアウトモード – ブートストラップグリッドベースまたは完全にフリーフォーム
  • さまざまなチャートに適したデータの操作と操作のためのデータユーティリティ

サポートされているすべてのライブラリを見る

ペイロード形式が正しい限り、指定されたjsonエンドポイントを使用してデータを取得します

JSON設定の紹介

設定JSONはコア機能を提供し、プロジェクトの中心にあります。 examples / configディレクトリにはいくつかの包括的なサンプルがあり、どのように動作するのか、またコアの設定ドキュメントを知ることができます 簡単な例:

{
    "modules": [
        {
            "type": "timeseries",
            "name": "name3",
            "width": 510,
            "height": 400,
            "dataSource": "http://localhost:5001/test1",
            "order": 0
        }
    ]
}

(4.0以降)カスタム入力を提供して、各チャートでインタラクティブ機能を使用することもできます。

例えば

{
    "modules": [
        {
            "name": "line",
            "height": "400",
            "width": "500",
            "dataSource": "http://127.0.0.1:5004/custom-inputs",
            "override": false,
            "guid": "a6eb10e7-26fa-7814-818a-3699b24415c5",
            "type": "line",
            "inputs": {
                "btn_classes": ["btn", "btn-info", "btn-sm"],
                "submit_text": "Submit",
                "options": [
                    {
                        "type": "number",
                        "name": "entries",
                        "input_classes": ["form-control", "input-sm"],
                        "label": "Number of points",
                        "help_text": "Change the number of points per entry shown"
                    }
                ]
            }
        }
    ]
}

エンドポイントが返すものをフィルタリングまたは変更するために使用できるクエリパラメータ(この例ではentries=10 )にマッピングされます。

また、jsonでの入力の順序によってhtmlでの順序が決まることにも注意してください。

以下は、カスタム入力構成を使用した出力の例です。

サポートされているすべてのオプションについては、 examples / configディレクトリを参照してください。

デモ

すべての/ほとんどのチャートを表示するには、青写真を使用するメインアプリと一緒にendpoints.py .pyフラスコアプリ(付属)を起動し、新しいダッシュボードを作成してからraw json編集オプションを選択し、 examples / configにあるjsonファイルの1つを指定します。 (これはmongodbを使ってテストされています)。

さまざまなチャートスキーマJSON形式

各グラフは非常に簡単です。 大部分のパワーは、フラスコ – ジンサッシュが守る様々なチャートライブラリによって活用されています。 特定のチャートタイプに対してエンドポイントjsonデータをフォーマットする方法と、サポートされている各ライブラリのドキュメントを見つける方法の詳細については、 スキーマを参照してください。

使用法

クイックスタート

データベース環境変数の設定。

次の環境変数が設定されていることを確認します。

  • CHARTS_DB_HOST – DBサーバーのホスト名(デフォルトは ‘localhost’)
  • CHARTS_DB_PORT – DBサーバーポート(デフォルトは27017)
  • CHARTS_DB_NAME – DBデータベース名(デフォルトは ‘charts’)
  • CHARTS_DB_TABLE DBコレクション名(デフォルトは ‘views’)
  • CHARTS_ACTIVE_DB使用するDBバックエンド – オプション: ‘mongo’(デフォルト)
DBの起動

jsonの設定を保存できるように開始してください。

データベースの起動: MongoDB

しかし、あなたは好きですが、通常はmongodが動作します。 注意:コレクションがmongoインスタンス内で作成され、CHARTS_DB_TABLEのenv varで指定されていることを確認し、データベース名をCHARTS_DB_NAMEのenv varの下に指定する必要があります

パッケージをダウンロードしてアプリを起動する

方法1 – 提供されたフラスコアプリを使用する

git clone https://github.com/christabor/flask_jsondash.git
cd flask_jsondash
virtualenv env
source env/bin/activate
python setup.py install
cd example_app
python app.py

これは、仮想環境でアプリケーションをセットアップし、すぐにポート8080付属のテストアプリ( app.py )を実行します。

青写真を既存のフラスコインスタンスにインポートする場合は、次のようにします。

方法2 – 既存のアプリを使用する

pip install flask-jsondash

あなたのアプリは青写真をインポートして登録し、適切なテンプレートタグを持っている必要があります。 これの例はここで見つけることができます

方法3 – ドッカー

ドッカードッカーの作成があると仮定します:

git clone https://github.com/christabor/flask_jsondash.git
make dockerize

これにより、ベースイメージとサービスイメージが構築され、ドッカーのサービスがセットアップされ、それらをリンクします。 エンドポイントはデフォルトで0.0.0.0:5004実行され、アプリケーションは0.0.0.0:8080で利用可能です。

ドッカーファイルは3つあり、ベースと継承しています。 これは、Pythonを再インストールしてapt reposを更新することなく、後続のアプリケーション固有のビルドを高速化する方法です

重要な使用法については、外部のボリュームをmongodbに設定して、データがドッカーの外側に永続化されるようにすることに注意してください。

Python 3.x用法

上記はうまくいくはずですが、すべての操作にpython 3.xを使用する必要があります。 例えば:

...
virtualenv -p python3 env
python3 setup.py install
python3 app.py

要件

コア

  • フラスコ
  • ジンジャ2

Javascript / CSS

これらは含まれていません。自分で持っている可能性が高いからです。 そうでない場合は、それらを追加する必要があります:

  • Jquery(JS)
  • ブートストラップ(CSS / JS)

これらは、すでに使用されていない可能性に基づいて、必要かつ含まれています。

  • JRespond(JS)
  • 石積み(JS)
  • Jquery UI(CSS / JS)

フラスコアプリの起動

あなた自身のフラスコアプリで青写真をインポートして使用するか、 app.py直接実行してそのままアプリを起動してください。

テストサーバーの起動

既存のエンドポイントをテストして、チャートのJSONをリンクする場合は、 endpoints.py実行しendpoints.py

リモートAJAXエンドポイントの使用

これを達成する方法の例については、 endpoints.pyを参照してください。 サーバー側でCORSを許可しないと、すべてのAjax要求は失敗します。

カスタマイズ

上記のjsondashの核となる設定を超えて、アプリケーションの動作を制御する方法が増えています。

フラスコの構成

認証

既定では、特定の操作に対して認証は実行されません。 しかし、各タイプの独自のカスタム認証をサポートするのは簡単な設定です。 JSONDASH名前空間(この場合はJSONDASH指定する必要があります)に設定を注入するフラスコパターンを使用すると、必要な機能を指定でき、指定された機能だけをチェックできます。 実際の例を次に示します。

def can_edit_others(view_id=None):
    if view_id == '...' and session.get('user')['name'] in SECRET_ADMINS:
        return True
    return False

def can_delete_charts():
    return session.get('user')['name'] in SECRET_ADMINS

charts_config = dict(
    auth=dict(
        edit_others=can_edit_others,
        delete=can_delete_charts,
    ),
)
app.config['JSONDASH'] = charts_config

サポートされているタイプとその詳細については、以下を参照してください。

認証タイプ

edit_global

これは、ユーザーが適切なアプリケーションフラグが設定されている場合 、すべてのユーザーにダッシュボードを表示する “global”フラグが設定されたグラフを作成または更新できるかどうかを決定します( グローバル設定フラグを参照 )。グローバルダッシュボードこのオプションは使用できません。

削除

チャートの削除を許可します。

クローン

チャートの複製を許可します。

更新

グラフの更新を許可します。

作成する

新しいチャートの作成を許可します。

見る

チャートの表示を許可します。 提供された関数はview_id kwargとしてビューのidを渡されます。

edit_others

他のクリエイターのチャートの編集を許可する。 提供された関数はview_id kwargとしてビューのidを渡されます。 created_byがログインしているユーザーと一致する場合は、authのオーバーライドに関係なく自動的に許可されます。

メタデータ設定

さらなるカスタマイズのために、json構成にメタデータを追加することができます。 すべての任意の値は、上に挙げたauth関数とまったく同じ方法で、付随する関数に取り込まれることを期待しています。 これらはすべて、 app.config['JSONDASH']ディクショナリ内のmetadataキーの下に名前が付けられます(指定されている場合)。

以下は、あなた自身の任意の関数でこれらのフィールドをオーバーライドする方法の例です。 注:デフォルトでは、引数をとりません。 これは特定のタイプに対して変更される可能性があります。

charts_config = dict(
    metadata=dict(
        created_by=get_username,
    ),
)
app.config['JSONDASH'] = charts_config

以下のメタデータのオーバーライドが使用されますが、ダッシュボードの設定に保存される任意のキーと値を追加することもできます。ここで必ずしも使用する必要はありません。

によって作成された

これは、構成上にそのようなキーが存在する場合、ユーザーがフロントページのビューを整理するために使用されます。 このキーは更新され、存在する場合は保存され、そうでない場合はnullになります。

ユーザー

これは現在ログインしているユーザーです。 これは、ユーザーによるダッシュボードのフィルタリングに必要です。 また、 JSONDASH_FILTERUSERSフラグをTrueに設定する必要があります。

グローバル設定フラグ

以下はグローバルアプリの設定フラグです。 それらのデフォルト値はPythonコードの動作例で表されています。

app.config['JSONDASH_FILTERUSERS'] = False :ログインしたユーザーによるダッシュボードのフィルタリング。 ユーザーデータの設定については、上記を参照してください。

app.config['JSONDASH_GLOBALDASH'] = True :「グローバル」ダッシュボードの表示を許可します。 これらのダッシュボードには、「global」のcreated_userがあるか、または上書きされている必要があります(下記参照)。

app.config['JSONDASH_GLOBAL_USER'] = "global" :グローバルダッシュボードを表示するときに使用するオーナーネーム。 これは、特定のJSON設定のcreated_byプロパティで設定されます。 より多くの例については上記を参照してください。

app.config['JSONDASH_MAX_PERPAGE'] = 50 :ページごとに表示する結果の数。 残りの結果は改ページされます。

静的アセット設定オプション

デフォルトでは、すべてのアセット(css / js)は、指定されたチャートライブラリに推奨されている一般的なCDNによってリモートにロードされます。

ただし、ネットワーク/プロキシの問題により、アセットが常に利用可能であるか、アセットにアクセスできないようにすることができます。 settings.pyファイル内で指定された独自のローカルアセットを使用したい場合は、それらをダウンロードしてアプリケーションのどこかに置いて、そこからロードする場所をjsondashに伝えurl_for('static', filename=XXX)標準フラスコurl_for('static', filename=XXX)パターン)。

これらの値をJSONDASH設定にstaticキーとして追加するだけです:

app.config['JSONDASH'] = dict(
    static=dict(
        js_path='js/vendor',
        css_path='css/vendor',
    )
)

デフォルトのフラスコの静的設定では、URLを/static/js/vendor/filename.js解決します。

あなたはどちらか一方を使うことができますが、両方を使用するか、使用しないことをお勧めします。

Jinjaテンプレート設定

マスターテンプレートでは、次のブロックが使用されます。

  1. jsondash_body :レイアウト全体に必要 ❗️
  2. jsondash_css :CSSの読み込みに必要 ❗️
  3. jsondash_js :jsのロードに必要 ❗️
  4. jsondash_api_scripts :コールバックを登録する場合はオプションです(下記参照)
  5. jsondash_init :ダッシュボードを初期化するために必要 ❗️
  6. jsondash_title :ページのタイトルを上書きまたは拡張する場合はオプションです。

サンプルアプリケーションをチェックして、どのように動作するかを確認することができます。

JavaScript設定

カスタムコールバック

jsondashのポイントは、フロントエンドのコーディングを完全に不要にし、ダッシュボードを作成するために直列化可能な宣言的な設定を使用することですが、スクリプトを必要とするものを一からやる必要があることがあります。 コールバックモジュールは、既存の構成を邪魔することなく、これを非常に簡単に行うために存在します。

この青写真を使用する既存のアプリと一緒に独自のjavascriptファイルを追加して個別のチャートをカスタマイズし、 チャートごとのIDベースでコールバックを登録することができます すべてのコールバックは、チャートがロードされて完全にレンダリングされた後、登録した順に実行されます。

開始するには、テンプレート内のテンプレートブロックをオーバーライドして、javascriptを実行できるようにし、独自の引数でコールバックを登録します。

{% block jsondash_api_scripts %}
<script>
    jsondash.api.registerCallback('my-chart-guid', function(container, config, myargs){
            console.log('Running FIRST callbacK!');
            console.log(myargs[0]);
            console.log(myargs[1]);
            container.style('background-color', 'green');
            console.log(config.guid);
    }, ['all', 'my', 'optional', 'arguments']);
    // Register a second one, which runs after.
    jsondash.api.registerCallback('my-chart-guid', function(container, config){
            console.log('Running SECOND callbacK!');
    });
</script>
{% endblock %}

すべてのコールバックには、次の引数の順序が渡されます。

  1. container :グラフコンテナのd3セレクタ。
  2. config :このチャートのjsonオブジェクト設定。
  3. args :コールバックの登録時に指定した引数の配列。

チャートjsondash.api.listCallbacks()にすべてのコールバックのリストを表示するには、 jsondash.api.listCallbacks()呼び出します。

カスタムイベント

いくつかのイベントがプロセス全体でトリガされ、自分のコールバックやアプリケーションに埋め込まれた他のコードだけで聴くことができます。

  • jsondash.init
  • jsondash.editform.loaded
  • jsondash.widget.added
  • jsondash.widget.updated
  • jsondash.widget.deleted
  • jsondash.widget.refresh
  • jsondash.row.add
  • jsondash.row.delete
  • jsondash.preview

イベントの下のapp.js内のすべてのイベントを表示します。

バージョン管理

このプロジェクトでは、リリースのセマンティックバージョン管理が使用されています。 しかし、 マスターブランチは 、最終的にリリースでタグ付けされるアップデート、修正プログラムなどで、 “出血”を表すため、不安定であるとみなされます 安定版を使用する場合は、対象とする特定のリリース確実に固定してください。

よくある質問

Q :なぜ、ライブラリX、Y、またはZを公開するのを選択したのですか?

A :かなり広く知られていて人気のある図書館に行きました。 公開されているものに不満がある場合は、js / cssとhtmlをテンプレートに埋め込み、 iframeオプションで読み込んで独自のタグを追加することができます。

Q :「X、Y、Zはどのようにカスタマイズしますか?」

A :ここで使用されている抽象化のレベルのため、多くのチャートは当然、手動でスクリプト化されている場合よりも構成の自由度が低くなります。 これは、簡単に多くのチャートを簡単にセットアップできることとのトレードオフです。

ここでの目標は、インテリジェントなデフォルトを可能な限り使用し、共通のインターフェースを通じて最も普遍的な側面をカスタマイズできるようにすることです。

ただし、チャートにoverrideフラグが設定されている場合、jsonに優しい未処理の設定を注入できoverride これはすべてのチャートでは機能しません。 詳細については設定オプションを参照してください。

たいていのチャートはhtmlやSVGなので、多くのスタイルカスタマイズはCSSでオーバーライドできます。 また、上で述べたように、常にoverrideオプションやiframe / customオプションを使用して、 dataSourceエンドポイントが完全なhtml / js / cssの事前レンダリングされたテンプレートを含め、必要なものを返すようにすることができます。

Q :「メタデータを公開するときに、 g変数を使用してそれを読むのはなぜですか?」

A :これは@app.before_request decoratorを使用し、 g変数にメタデータを設定することです。 問題は、非常に不必要なオーバーヘッドを作成することです。

ヒントとテクニック

付属のデータユーティリティを使用する

詳細については、 データユーティリティをチェックしてください。

サンプルダッシュボードの自動設定の読み込み

make fixtures実行します。

エンドポイントを動的に使用する

チャート作成者は単純なエンドポイントを使用するため、RESTの機能を使用してより複雑なビューを作成できます。 例えば:

curl -XGET http://localhost:8080/api/foo/

{"data": [1, 2, 3, 4]}返すことができますが、クエリ引数をサポートするためにダッシュボードに保存されたURLを更新することによってURLをカスタマイズできます:

curl -XGET http://localhost:8080/api/foo?gt=9

代わりに{"data": [10, 20, 30, 40]}返すことができます!

パフォーマンスとシンプルさのために共有データを使用する。

ペイロード内の名前空間の「キー」を使用して、単一のソースからのデータをN個のチャート間で共有することができます。 共有データセクション参照して、 ここ設定例を 参照してください

テストデータの生成

偽のチャートを生成するためのCLIユーティリティなどがあります。py2 / p3との互換性のために必要な相対的なインポートスタイルのため、pythonパッケージのように実行する必要があります。 たとえば、モデルファクトリジェネレータを実行するには、 python -m flask_jsondash.model_factories --records 10実行します。 python3.xの場合は、 python3 -m ...と置き換えてpython3 -m ...

デモモードを使用する

クエリ引数jsondash_demo_mode=1をURLに追加すると(例えば...?jsondash_demo_mode=1など)、UIはダッシュボードの編集ボタンと戻るボタンを自動的に隠します。これは、例えば、マウントされた画面を非表示にするために使用できます余分な詳細。

他の場所に図表を埋め込む

jsondash_demo_modeと同様に、 jsondash_demo_modeにquery param jsondash_demo_mode (例えば?embeddable=1 )を追加すると、すべてのインタラクティブな要素やダッシュボードのタイトルやその他の付属要素を隠すことができます。

注:これにより、jsondashのjinjaブロックの範囲外のUIの他の部分は削除されません。 それらは別々に隠される必要があります。

gist.github.comの使用

データは動的に生成されませんが、Githubの要点(またはgithub.comのrawファイル)を使ってグラフを読み込むことは簡単です! gistからロードされた実際の作業チャートを見るには、 kitchensinkダッシュボードをチェックしてください!

他のリソースからのグラフの埋め込み

たとえば、ビルドツールJenkinsはビルド統計のためプラグインを提供します iframeチャートオプションを使用して未加工の生成されたpng(URLは通常、https:// {JENKINS_SERVER} / view / {VIEW_NAME} / job / {JOB_NAME} / buildTimeGraph / pngの形式です)を直接埋め込むことができます。

その他のクールなもの

もっと便利なコマンドについてはMakefileを見てください。

パフォーマンス

パフォーマンス・メトリックは使用できませんが、サンプル・エンドポイントの「ストレス・テスト」の例を見ることができます。 これらの設定はexamples / config / stresstest.jsonにあります。 また、上の包括的な例(plotly、kitchensink)は非常に複雑なダッシュボード(20-30図、webglなど)であり、ブラウザでテストされています。

ストレステスト(MacBook Pro / 16gb / 2.7ghz i7で実行)に関するいくつかの観察

  • ネイティブD3.jsは大きなデータセットを非常にうまく処理します。 それは問題なしで1〜2MBのjsonファイルを処理しました。
  • Datatablesは問題のない非常に大きなデータセットを処理します。 劣化前の最大テスト数は約100,000行でした。
  • チャートごとに2-300データポイントのアップデータが使用されていると、C3.jsの時間が大幅に遅れて10秒を過ごし、場合によってはGoogle Chrome(ページに複数のチャートが表示されます)がクラッシュします。

あなたのパフォーマンスは良くても悪くても良いので、テストしてみてください。 いつものように、あなたのマイルは多少なるかもしれません。

デバッグ/トラブルシューティング

URLが正しいのに私のグラフはロードされません!

httpの問題

あなたのサイトがhttpsを使用している場合、これはおそらく、それを使用していないサードパーティの問題ではなく、安全でないhttp Webサーバーを実行していることが原因です。 残念ながら、これを修正するのは簡単ではありません。

  • SSL証明書をもはや持っていないことであなたのサイトが安全でない(望ましくない)
  • エンドポイントの所有者にSSLを強制し、httpsを提供するように伝えます。

JavaScriptの問題

JavaScriptの解析エラーのトラブルシューティングを行うには、ブラウザのコンソールを開きます(例:Chromeでは、Macの場合はcmd + option + i 、Windowsの場合はCtrl + Alt + i )。 解析エラーがある場合、指定されたコンテンツタイプに対してjsonレスポンスのフォーマットが無効になることがあります。 フォーマット要件についてはスキーマページを確認してください

私のチャートは醜いですか、コンテナの外に流れています

これは通常、特に表示する項目の数を選択するときに、データテーブルの問題です。 テーブルのサイズは大きくなり、レイアウトはそのことを考慮していません。 ここでの最良のケースは、実際にどのサイズが理にかなっているかを判断し、それに応じてグラフのサイズを調整することです。

また、このグラフでサポートされているオーバーライドオプションを使用して、1ページあたりの結果数と表示可能なエントリ数を指定することもできます。 詳細については、 datatablesスキーマのドキュメントを参照してください。

貢献/開発

プロジェクトで作業したい場合は、サンプルアプリケーションを使用して開発することをおすすめします。 これを簡単に行うには、 setuptools developモードを使用して、仮想環境をセットアップしてパッケージをローカルに設定する必要があります。 以下はあなたを始めるはずです:

git clone github.com/christabor/flask_jsondash.git
cd flask_jsondash
virtualenv env
source env/bin/activate
git checkout -b YOUR_NEW_BRANCH
python setup.py develop
cd example_app
python app.py

そしてボイル! これで、フォルダを直接編集したり、何かを変更するたびに再インストールすることなく、通常のピップパッケージとしてそのまま使用することができます。

テスト

カバレッジを持つPython 2.7と3.xのすべてのテストを実行するには、 tox実行しtox (toxがインストールされていると仮定します)。

Python

pytest( pip install -U pytest )を使用してこれらのテストを実行し、既存のvirtualenvでpytest tests実行pytest tests

この方法に問題がある場合は、プロジェクトのvirtualenv内にpytestをインストールして(それを作成したと仮定して) python -m pytest testsように実行しpython -m pytest tests

テストカバレッジ

カバレッジ情報を見つけるには( pytest-covがインストールされていると仮定します)、 pytest tests -s --cov=flask_jsondashます。

Javascript

JSテストは、ノード・ライブラリーJasmineを使用して実行されます。 それをインストールして実行するには、nodejsをインストールしてからnpm install -g jasmineパッケージをインストールする必要があります。 次に、 tests_jsフォルダにcdして、提供されているpythonスクリプトを実行しますpython runner.py







-christabor
-, , , , , , , ,

執筆者: