メインコンテンツにスキップ
GitHubでこのページを編集

開発方法

ドキュメントへのコントリビューション​

最新のドキュメントとチュートリアルは https://superset.dokyumento.jp/ で入手できます。

ドキュメントサイトは、最新の静的ウェブサイトジェネレーターである Docusaurus 2 を使用して構築されており、そのソースは ./docs にあります。

ローカル開発​

ドキュメントサイトのホットリロードによるローカル開発環境をセットアップするには

cd docs
yarn install  # Installs NPM dependencies
yarn start  # Starts development server at http://localhost:3000

ビルド​

ドキュメントサイトの本番ビルドを作成して提供するには

yarn build
yarn serve

デプロイメント​

master へのコミットは、ドキュメントサイトの再構築と再デプロイをトリガーします。ドキュメントを修正するプルリクエストは、docs: というプレフィックスを付けて送信してください。

可視化プラグインの作成​

Superset の可視化は、JavaScript または TypeScript で実装されています。Superset には、superset-frontend/plugins ディレクトリにあるいくつかの可視化タイプ（以下「viz プラグイン」）がプリインストールされています。Viz プラグインは、superset-frontend/src/visualizations/presets/MainPreset.js でアプリケーションに追加されます。Superset プロジェクトは、常に高品質の新しい viz プラグインの提案を歓迎します。ただし、高度にカスタマイズされた viz タイプの場合は、Superset のフォークを維持し、手動でカスタムビルドされた viz プラグインを追加することをお勧めします。

注意: カスタムの可視化プラグインの作成とデプロイに関するコミュニティ生成のリソースは、Superset Wiki で確認できます。

前提条件​

新しい viz プラグインを作成するには、以下が必要です

  • macOS または Linux で実行する（Windows は公式にはサポートされていませんが、動作する可能性があります）
  • Node.js 16
  • npm 7 または 8

React および npm/Node システムに関する一般的な知識も推奨されます。

シンプルな Hello World viz プラグインの作成​

開始するには、Superset Yeoman Generator が必要です。使用している Superset のバージョンに付属しているテンプレートのバージョンを使用することをお勧めします。これは、次の手順でインストールできます

npm i -g yo
cd superset-frontend/packages/generator-superset
npm i
npm link

この後、viz プラグインの作成に進むことができます。viz プラグイン用の新しいディレクトリを superset-plugin-chart というプレフィックスを付けて作成し、Yeoman ジェネレーターを実行します

mkdir /tmp/superset-plugin-chart-hello-world
cd /tmp/superset-plugin-chart-hello-world

viz プラグインを初期化します

yo @superset-ui/superset

その後、ジェネレーターがいくつかの質問をします（デフォルトで問題ありません）

$ yo @superset-ui/superset
     _-----_     ╭──────────────────────────╮
    |       |    │      Welcome to the      │
    |--(o)--|    │    generator-superset    │
   `---------´   │        generator!        │
    ( _´U`_ )    ╰──────────────────────────╯
    /___A___\   /
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `
? Package name: superset-plugin-chart-hello-world
? Description: Hello World
? What type of chart would you like? Time-series chart
   create package.json
   create .gitignore
   create babel.config.js
   create jest.config.js
   create README.md
   create tsconfig.json
   create src/index.ts
   create src/plugin/buildQuery.ts
   create src/plugin/controlPanel.ts
   create src/plugin/index.ts
   create src/plugin/transformProps.ts
   create src/types.ts
   create src/SupersetPluginChartHelloWorld.tsx
   create test/index.test.ts
   create test/__mocks__/mockExportString.js
   create test/plugin/buildQuery.test.ts
   create test/plugin/transformProps.test.ts
   create types/external.d.ts
   create src/images/thumbnail.png

viz プラグインをビルドするには、次のコマンドを実行します

npm i --force
npm run build

または、viz プラグインを開発モードで実行する（変更が行われるたびに再構築する）には、次のコマンドで開発サーバーを起動します

npm run dev

パッケージを Superset に追加するには、Superset ソースフォルダーの superset-frontend サブディレクトリに移動して実行します

npm i -S /tmp/superset-plugin-chart-hello-world

パッケージを npm に公開する場合は、そこから直接インストールすることもできます。この後、superset-frontend/src/visualizations/presets/MainPreset.js を編集し、次の変更を行います

import { SupersetPluginChartHelloWorld } from 'superset-plugin-chart-hello-world';

viz プラグインをインポートし、後で plugins プロパティに渡される配列に次を追加します

new SupersetPluginChartHelloWorld().configure({ key: 'ext-hello-world' }),

その後、Superset（例：開発サーバー）を実行すると、viz プラグインが表示されるはずです

npm run dev-server

テスト​

Python テスト​

すべての python テストは、標準化されたテストフレームワークである tox で実行されます。すべての python テストは、次のコマンドを使用して、tox の 環境 のいずれかで実行できます。

tox -e <environment>

例:

tox -e py38

または、次のコマンドで単一のファイルですべてのテストを実行できます。

tox -e <environment> -- tests/test_file.py

または、次のコマンドで特定のテストを実行できます。

tox -e <environment> -- tests/test_file.py::TestClassName::test_method_name

テスト環境では、SQLite データベースを定義するための一時ディレクトリを使用しており、テストコマンドのグループが呼び出されるたびにクリアされることに注意してください。

また、Superset コードベースには、python 統合テストを実行するためのユーティリティスクリプトも含まれています。 readme はこちら にあります。

たとえば、すべての統合テストを実行するには、ルートディレクトリからこのスクリプトを実行します

scripts/tests/run.sh

pytest を使用して、たとえば './tests/unit_tests' にある単体テストを実行できます。これは、データベース設定を必要としない分離されたテストを実行する簡単な方法です

pytest ./link_to_test.py

ローカル Presto 接続でのテスト​

Presto/Trino の DB エンジンスペックを変更する場合は、Docker でローカル Presto クラスターを実行できます

docker run -p 15433:15433 starburstdata/presto:350-e.6

次に、SUPERSET__SQLALCHEMY_EXAMPLES_URI を更新して、ローカル Presto クラスターを指すようにします

export SUPERSET__SQLALCHEMY_EXAMPLES_URI=presto://localhost:15433/memory/default

フロントエンドテスト​

TypeScript/JavaScript をテストするために、Jest と Enzyme を使用しています。テストは次のコマンドで実行できます

cd superset-frontend
npm run test

単一のテストファイルを実行するには

npm run test -- path/to/file.js

e2e 統合テスト​

エンドツーエンドの統合テストには、Cypress を使用しています。手早く開始するための簡単なオプションの1つは、tox を利用して、分離された環境ですべてのスイートを実行することです。

tox -e cypress

または、次の手順に従って、開発環境で下位レベルでセットアップすることもできます

まず、python/flask バックエンドをセットアップします

export SUPERSET_CONFIG=tests.integration_tests.superset_test_config
export SUPERSET_TESTENV=true
export CYPRESS_BASE_URL="http://localhost:8081"
superset db upgrade
superset load_test_users
superset init
superset load-examples --load-test-data
superset run --port 8081

別のターミナルで、フロントエンドを準備し、Cypress テストを実行します

cd superset-frontend
npm run build-instrumented

cd cypress-base
npm install

# run tests via headless Chrome browser (requires Chrome 64+)
npm run cypress-run-chrome

# run tests from a specific file
npm run cypress-run-chrome -- --spec cypress/e2e/explore/link.test.ts

# run specific file with video capture
npm run cypress-run-chrome -- --spec cypress/e2e/dashboard/index.test.js --config video=true

# to open the cypress ui
npm run cypress-debug

# to point cypress to a url other than the default (http://localhost:8088) set the environment variable before running the script
# e.g., CYPRESS_BASE_URL="http://localhost:9000"
CYPRESS_BASE_URL=<your url> npm run cypress open

superset-frontend/cypress_build.sh を参照してください。

または、テストに docker compose 環境を使用することもできます

/etc/hosts ファイルに次の行を追加したことを確認してください: 127.0.0.1 db

すでに Docker 環境を起動している場合は、次のコマンドを使用して、新しいデータベースインスタンスを確保してください: docker compose down -v

環境を起動します

CYPRESS_CONFIG=true docker compose up

これにより、バックエンドとフロントエンドがポート 8088 で提供されます。

Cypress テストを実行します

cd cypress-base
npm install
npm run cypress open

サーバーアプリのデバッグ​

Docker コンテナ内で実行されている Flask アプリをデバッグするには、次の手順に従います。

まず、次の内容を ./docker-compose.yaml ファイルに追加します

superset:
    env_file: docker/.env
    image: *superset-image
    container_name: superset_app
    command: ["/app/docker/docker-bootstrap.sh", "app"]
    restart: unless-stopped
+   cap_add:
+     - SYS_PTRACE
    ports:
      - 8088:8088
+     - 5678:5678
    user: "root"
    depends_on: *superset-depends-on
    volumes: *superset-volumes
    environment:
      CYPRESS_CONFIG: "${CYPRESS_CONFIG}"

通常どおり Superset を起動します

docker compose up

必要なライブラリとパッケージを docker コンテナにインストールします

superset_app コンテナに入ります

docker exec -it superset_app /bin/bash
root@39ce8cf9d6ab:/app#

コンテナ内で次のコマンドを実行します

apt update
apt install -y gdb
apt install -y net-tools
pip install debugpy

Flask プロセスの PID を見つけます。必ず最初の PID を使用してください。Flask アプリは、python コードを変更するたびにサブプロセスを再生成します。そのため、最初の PID を使用することが重要です。

ps -ef

UID        PID  PPID  C STIME TTY          TIME CMD
root         1     0  0 14:09 ?        00:00:00 bash /app/docker/docker-bootstrap.sh app
root         6     1  4 14:09 ?        00:00:04 /usr/local/bin/python /usr/bin/flask run -p 8088 --with-threads --reload --debugger --host=0.0.0.0
root        10     6  7 14:09 ?        00:00:07 /usr/local/bin/python /usr/bin/flask run -p 8088 --with-threads --reload --debugger --host=0.0.0.0

実行中の Flask プロセスに debugpy を注入します。この場合、PID は 6 です。

python3 -m debugpy --listen 0.0.0.0:5678 --pid 6

debugpy がポート 5678 でリッスンしていることを確認します

netstat -tunap

Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 0.0.0.0:5678            0.0.0.0:*               LISTEN      462/python
tcp        0      0 0.0.0.0:8088            0.0.0.0:*               LISTEN      6/python

これで、デバッガーをプロセスにアタッチする準備ができました。VSCode を使用すると、次のように .vscode/launch.json などの起動構成ファイルを構成できます。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Superset App in Docker Container",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "127.0.0.1",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "/app"
                }
            ]
        },
    ]
}

VSCode はブレークポイントですぐには停止しません。PID 6 にアタッチしましたが、まだサブプロセスを認識していません。デバッガーを「起動」するには、python ファイルを変更する必要があります。これにより、Flask がコードをリロードし、新しいサブプロセスを作成します。この新しいサブプロセスは VSCode によって検出され、ブレークポイントがアクティブ化されます。

Kubernetes 環境でのサーバーアプリのデバッグ​

Kubernetes クラスター内の POD で実行されている Flask をデバッグするには、POD が root として実行され、SYS_TRACE 機能が付与されていることを確認する必要があります。これらの設定は、本番環境で使用しないでください。

  securityContext:
    capabilities:
      add: ["SYS_PTRACE"]

詳細については、コンテナの機能を設定するを参照してください。

POD が root として実行され、SYS_PTRACE 機能を持っていると、Flask アプリをデバッグできるようになります。

docker compose と同じ手順に従うことができます。POD に入り、必要なライブラリとパッケージ（gdb、netstat、debugpy）をインストールします。

多くの場合、Kubernetes 環境では、ノードはクラスター外部からアドレス指定できません。したがって、VSCode は Kubernetes ノード上のポート 5678 にリモートで接続できません。これを行うには、ポート 5678 をローカルマシンに転送するトンネルを作成する必要があります。

kubectl port-forward  pod/superset-<some random id> 5678:5678

これで、上記と同じ構成で VSCode デバッガーを起動できます。VSCode は 127.0.0.1:5678 に接続します。これは kubectl によってリモート Kubernetes POD に転送されます。

Storybook​

Supersetには、さまざまなSupersetコンポーネントとそのバリエーションのレイアウト/スタイルをプレビューするためのStorybookが含まれています。 Storybookを開いて表示するには、

cd superset-frontend
npm run storybook

新しいReactコンポーネントをSupersetに貢献する場合は、コンポーネントのjsx/tsxファイルと一緒にStoryを追加するようにしてください。

翻訳への貢献​

Supersetの翻訳にはFlask-Babelを使用しています。Pythonファイルでは、Flask-Babelから以下の翻訳関数を使用します。

  • gettext および lazy_gettext（通常は_にエイリアスされます）：単数形の文字列を翻訳する場合に使用します。
  • ngettext：複数形になる可能性のある文字列を翻訳する場合に使用します。
from flask_babel import lazy_gettext as _

次に、翻訳可能な文字列を_('Translate me')のようにラップします。抽出時に、_に渡された文字列リテラルは、後で翻訳するために、各言語の生成された.poファイルに追加されます。

実行時には、_関数は現在の言語で指定された文字列の翻訳を返します。翻訳がない場合は、指定された文字列自体が返されます。

TypeScript/JavaScriptでは、手法は似ています。t（単純な翻訳）、tn（数値を含む翻訳）をインポートします。

import { t, tn } from "@superset-ui/translation";

言語選択の有効化​

superset_config.pyにLANGUAGES変数を追加します。複数のオプションを追加すると、ナビゲーションバーの右側に言語選択ドロップダウンがUIに追加されます。

LANGUAGES = {
    'en': {'flag': 'us', 'name': 'English'},
    'fr': {'flag': 'fr', 'name': 'French'},
    'zh': {'flag': 'cn', 'name': 'Chinese'},
}

新しい言語辞書の作成​

まず、ターゲット言語の言語コードがすでに存在するかどうかを確認します。ターゲット言語の2文字のISO 639-1コードがsuperset/translationsディレクトリにすでに存在するかどうかを確認してください。

ls superset/translations | grep -E "^[a-z]{2}\/"

言語の翻訳がすでに存在する場合は、次のセクションにスキップしてください。

以下の言語はFlask AppBuilderですでにサポートされており、アプリケーションをターゲット言語に翻訳するのに役立ちます。Flask AppBuilder i18n ドキュメント

新しい言語の辞書を作成するには、まず必要な依存関係がインストールされていることを確認してください。

pip install -r superset/translations/requirements.txt

次に、以下を実行します。ここで、LANGUAGE_CODEはターゲット言語の言語コードに置き換えられます。

pybabel init -i superset/translations/messages.pot -d superset/translations -l LANGUAGE_CODE

たとえば、フィンランド語（言語コードfi）の翻訳を追加するには、以下を実行します。

pybabel init -i superset/translations/messages.pot -d superset/translations -l fi

翻訳用の新しい文字列の抽出​

翻訳作業を行う際、バックエンドとフロントエンドの両方から文字列を抽出して、翻訳対象のすべての文字列のリストをコンパイルする必要が定期的に発生します。これは自動的には行われず、文字列を収集して、翻訳可能な.poファイルに入れ、コンパイルできるようにするための必須ステップです。

このスクリプトはそれを実行します。

./scripts/translations/babel_update.sh

言語ファイルの更新​

次のコマンドを実行して、新しく抽出された文字列で言語ファイルを更新します。

 pybabel update -i superset/translations/messages.pot -d superset/translations --ignore-obsolete

次に、superset/translationにあるファイルに収集された文字列を翻訳できます。ここでは言語ごとに1つのフォルダーがあります。Poeditを使用すると、poファイルをより便利に翻訳できます。こちらがチュートリアルです。

MacOSで翻訳を実行するには、Homebrewを使用してpoeditをインストールできます。

brew install poedit

この後、poeditアプリケーションを起動し、messages.poファイルを開きます。フィンランド語翻訳の場合、これはsuperset/translations/fi/LC_MESSAGES/messages.poになります。

翻訳の適用​

フロントエンドで翻訳を利用できるようにするには、POファイルをJSONファイルのコレクションに変換する必要があります。すべてのPOファイルをフォーマットされたJSONファイルに変換するには、build-translationスクリプトを使用できます。

# Install dependencies if you haven't already
cd superset-frontend/ && npm ci
# Compile translations for the frontend
npm run build-translation

最後に、翻訳を有効にするには、pybabelを使用してバックエンド用の翻訳カタログをバイナリMOファイルにコンパイルする必要があります。

# inside the project root
pybabel compile -d superset/translations

リンティング​

Python​

リンティングにはPylintを使用しており、これは以下を介して呼び出すことができます。

# for python
tox -e pylint

ベストプラクティスとして、グローバルに（.pylintrc経由で）またはファイルヘッダー内でトップレベルでPylintメッセージをまとめて無効にすることは避けてください。ただし、いくつかの例外があります。無効化はインラインで発生する必要があります。これにより、問題が隠蔽されるのを防ぎ、メッセージが無効になっている理由のコンテキストを提供します。

さらに、PythonコードはBlackを使用して自動的にフォーマットされます。これはpre-commitフックとして構成されています。また、多数のエディター統合もあります。

TypeScript​

cd superset-frontend
npm ci
# run eslint checks
npm run eslint -- .
# run tsc (typescript) checks
npm run type

vscodeでeslint拡張機能を使用する場合は、ワークスペースのsettings.jsonファイルに以下を記述します。

"eslint.workingDirectories": [
  "superset-frontend"
]