diff --git a/superset-core/README.md b/superset-core/README.md index 0ca50a252f7..61fefbac142 100644 --- a/superset-core/README.md +++ b/superset-core/README.md @@ -31,70 +31,70 @@ The official core package for building Apache Superset backend extensions and in pip install apache-superset-core ``` -## 🏗️ Architecture +## 🏗️ Package Structure -The package is organized into logical modules, each providing specific functionality: - -- **`api`** - REST API base classes, models access, query utilities, and registration -- **`api.models`** - Access to Superset's database models (datasets, databases, etc.) -- **`api.query`** - Database query utilities and SQL dialect handling -- **`api.rest_api`** - Extension API registration and management -- **`api.types.rest_api`** - REST API base classes and type definitions +``` +src/superset_core/ +├── common/ +├── extensions/ +├── mcp/ +├── queries/ +├── rest_api/ +├── tasks/ +└── __init__.py +``` ## 🚀 Quick Start -### Basic Extension Structure +### Basic Extension API ```python -from flask import request, Response from flask_appbuilder.api import expose, permission_name, protect, safe -from superset_core import common, queries, rest_api from superset_core.rest_api.api import RestApi +from superset_core.rest_api.decorators import api + +@api(id="dataset_references", name="Dataset References API") class DatasetReferencesAPI(RestApi): - """Example extension API demonstrating core functionality.""" - - resource_name = "dataset_references" - openapi_spec_tag = "Dataset references" - class_permission_name = "dataset_references" @expose("/metadata", methods=("POST",)) @protect() @safe @permission_name("read") def metadata(self) -> Response: - """Get dataset metadata for tables referenced in SQL.""" - sql: str = request.json.get("sql") - database_id: int = request.json.get("databaseId") - - # Access Superset's models using core APIs - databases = models.get_databases(id=database_id) - if not databases: - return self.response_404() - - database = databases[0] - dialect = query.get_sqlglot_dialect(database) - - # Access datasets to get owner information - datasets = models.get_datasets() - owners_map = { - dataset.table_name: [ - f"{owner.first_name} {owner.last_name}" - for owner in dataset.owners - ] - for dataset in datasets - } - - # Process SQL and return dataset metadata - return self.response(200, result=owners_map) - -# Register the extension API -rest_api.add_extension_api(DatasetReferencesAPI) + # ... endpoint implementation ``` -## 🤝 Contributing +### Background Tasks -We welcome contributions! Please see the [Developer Portal](https://superset.apache.org/developer_portal/) for details. +```python +from superset_core.tasks.decorators import task +from superset_core.tasks.types import TaskScope + +@task(name="generate_report", scope=TaskScope.SHARED) +def generate_report(chart_id: int) -> None: + # ... task implementation +``` + +### MCP Tools + +```python +from superset_core.mcp.decorators import tool + +@tool(name="my_tool", description="Custom business logic", tags=["extension"]) +def my_extension_tool(param: str) -> dict: + # ... tool implementation +``` + +### MCP Prompts + +```python +from superset_core.mcp.decorators import prompt + +@prompt(name="my_prompt", title="My Prompt", description="Interactive prompt", tags={"extension"}) +async def my_prompt_handler(ctx: Context) -> str: + # ... prompt implementation +``` ## 📄 License @@ -102,12 +102,6 @@ Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com ## 🔗 Links -- [Apache Superset](https://superset.apache.org/) -- [Documentation](https://superset.apache.org/docs/) - [Community](https://superset.apache.org/community/) - [GitHub Repository](https://github.com/apache/superset) -- [Extension Development Guide](https://superset.apache.org/docs/extensions/) - ---- - -**Note**: This package is currently in release candidate status. APIs may change before the 1.0.0 release. Please check the [changelog](CHANGELOG.md) for breaking changes between versions. +- [Extensions Documentation](https://superset.apache.org/developer-docs/extensions/overview) diff --git a/superset-core/pyproject.toml b/superset-core/pyproject.toml index 44b2b3df06e..57dfb231ade 100644 --- a/superset-core/pyproject.toml +++ b/superset-core/pyproject.toml @@ -18,7 +18,7 @@ [project] name = "apache-superset-core" -version = "0.0.1rc4" +version = "0.1.0rc1" description = "Core Python package for building Apache Superset backend extensions and integrations" readme = "README.md" authors = [ diff --git a/superset-extensions-cli/README.md b/superset-extensions-cli/README.md index 00b75f9ef33..a5143a80ba3 100644 --- a/superset-extensions-cli/README.md +++ b/superset-extensions-cli/README.md @@ -28,6 +28,7 @@ Official command-line interface for building, bundling, and managing Apache Supe ## 🚀 Features - **Extension Scaffolding** - Generate initial folder structure and scaffold new extension projects +- **Validation** - Validate extension structure and configuration before building - **Development Server** - Automatically rebuild extensions as files change during development - **Build System** - Build extension assets for production deployment - **Bundle Packaging** - Package extensions into distributable .supx files @@ -43,68 +44,52 @@ pip install apache-superset-extensions-cli ### Available Commands ```bash -# Generate initial folder structure and scaffold a new extension project -superset-extensions init +# Scaffold a new extension project (interactive prompts, or pass options directly) +superset-extensions init [--publisher ] [--name ] [--display-name ] + [--version ] [--license ] + [--frontend/--no-frontend] [--backend/--no-backend] + +# Validate extension structure and configuration +superset-extensions validate + +# Build extension assets for production (runs validate first) +superset-extensions build + +# Package extension into a distributable .supx file (runs build first) +superset-extensions bundle [--output/-o ] # Automatically rebuild extension as files change during development superset-extensions dev - -# Build extension assets for production -superset-extensions build - -# Package extension into a distributable .supx file -superset-extensions bundle ``` ## 📋 Extension Structure -The CLI generates extensions with the following structure: +The CLI scaffolds extensions with the following structure: ``` -extension_name/ +{publisher}.{name}/ # e.g., my-org.dashboard-widgets/ ├── extension.json # Extension configuration and metadata -├── frontend/ # Frontend code -│ ├── src/ # TypeScript/React source files -│ ├── webpack.config.js # Frontend build configuration -│ ├── tsconfig.json # TypeScript configuration -│ └── package.json # Frontend dependencies -├── backend/ # Backend code +├── .gitignore +├── frontend/ # Optional frontend code │ ├── src/ -│ │ └── dataset_references/ # Python package source -│ ├── tests/ # Backend tests -│ ├── pyproject.toml # Python package configuration -│ └── requirements.txt # Python dependencies -├── dist/ # Built extension files (generated) -│ ├── manifest.json # Generated extension manifest -│ ├── frontend/ -│ │ └── dist/ # Built frontend assets -│ │ ├── remoteEntry.*.js # Module federation entry -│ │ └── *.js # Additional frontend bundles -│ └── backend/ -│ └── dataset_references/ # Built backend package -│ ├── __init__.py -│ ├── api.py -│ └── entrypoint.py -├── dataset_references-1.0.0.supx # Packaged extension file (generated) -└── README.md # Extension documentation +│ │ └── index.tsx # Frontend entry point +│ ├── package.json +│ ├── webpack.config.js +│ └── tsconfig.json +└── backend/ # Optional backend code + ├── src/ + │ └── {publisher}/ # e.g., my_org/ + │ └── {name}/ # e.g., dashboard_widgets/ + │ └── entrypoint.py + └── pyproject.toml ``` -## 🤝 Contributing - -We welcome contributions! Please see the [Developer Portal](https://superset.apache.org/developer_portal/) for details. - ## 📄 License Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/apache/superset/blob/master/LICENSE.txt) for details. ## 🔗 Links -- [Apache Superset](https://superset.apache.org/) -- [Extension Development Guide](https://superset.apache.org/docs/extensions/) -- [API Documentation](https://superset.apache.org/docs/api/) -- [GitHub Repository](https://github.com/apache/superset) - [Community](https://superset.apache.org/community/) - ---- - -**Note**: This package is currently in early development. APIs and commands may change before the 1.0.0 release. Please check the [changelog](CHANGELOG.md) for breaking changes between versions. +- [GitHub Repository](https://github.com/apache/superset) +- [Extensions Documentation](https://superset.apache.org/developer-docs/extensions/overview) diff --git a/superset-extensions-cli/pyproject.toml b/superset-extensions-cli/pyproject.toml index 4487152c171..7a09fbe274e 100644 --- a/superset-extensions-cli/pyproject.toml +++ b/superset-extensions-cli/pyproject.toml @@ -17,7 +17,7 @@ [project] name = "apache-superset-extensions-cli" -version = "0.0.1rc2" +version = "0.1.0rc1" description = "Official command-line interface for building, bundling, and managing Apache Superset extensions" readme = "README.md" authors = [ diff --git a/superset-frontend/package-lock.json b/superset-frontend/package-lock.json index 436da649f45..b0dd8471377 100644 --- a/superset-frontend/package-lock.json +++ b/superset-frontend/package-lock.json @@ -51390,7 +51390,7 @@ }, "packages/superset-core": { "name": "@apache-superset/core", - "version": "0.0.1-rc11", + "version": "0.1.0-rc1", "license": "ISC", "devDependencies": { "@babel/cli": "^7.28.6", diff --git a/superset-frontend/packages/superset-core/README.md b/superset-frontend/packages/superset-core/README.md index 948f8ac39d2..d9f835dab98 100644 --- a/superset-frontend/packages/superset-core/README.md +++ b/superset-frontend/packages/superset-core/README.md @@ -30,74 +30,98 @@ The official core package for building Apache Superset extensions and integratio npm install @apache-superset/core ``` -## 🏗️ Architecture +## 🏗️ Package Structure -The package is organized into logical namespaces, each providing specific functionality: +The source is organized into focused namespaces, each in its own directory: -- **`authentication`** - User authentication and authorization APIs -- **`commands`** - Command registration and execution system -- **`contributions`** - UI contribution points and customization APIs -- **`core`** - Fundamental types, utilities, and lifecycle management -- **`environment`** - Environment detection and configuration APIs -- **`extensions`** - Extension management and metadata APIs -- **`sqlLab`** - SQL Lab integration and event handling +``` +src/ +├── authentication/ +├── commands/ +├── common/ +├── components/ +├── contributions/ +├── editors/ +├── extensions/ +├── menus/ +├── sqlLab/ +├── theme/ +├── translation/ +├── utils/ +├── views/ +└── index.ts +``` ## 🚀 Quick Start -### Basic Extension Structure +Frontend contributions are registered as module-level side effects from your extension's entry point. -```typescript -import { - core, - commands, - sqlLab, - authentication, -} from '@apache-superset/core'; +### Views -export function activate(context: core.ExtensionContext) { - // Register a command to save current query - const commandDisposable = commands.registerCommand( - 'my_extension.save_query', - async () => { - const currentTab = sqlLab.getCurrentTab(); - if (currentTab?.editor.content) { - const token = await authentication.getCSRFToken(); - // Use token for secure API calls - console.log('Saving query with CSRF token:', token); - } - }, - ); +Add custom panels or UI components at specific locations in the application: - // Listen for query execution events - const eventDisposable = sqlLab.onDidQueryRun(editor => { - console.log('Query executed:', editor.content.substring(0, 50) + '...'); - }); +```tsx +import { views } from '@apache-superset/core'; +import MyPanel from './MyPanel'; - // Register a simple view - const viewDisposable = core.registerViewProvider( - 'my_extension.panel', - () => ( -
-

My Extension

- -
- ) - ); - - // Cleanup registration - context.subscriptions.push(commandDisposable, eventDisposable, viewDisposable); -} - -export function deactivate() { - // Cleanup handled automatically via disposables -} +views.registerView( + { id: 'my-extension.main', name: 'My Panel Name' }, + 'sqllab.panels', + () => , +); ``` -## 🤝 Contributing +### Commands -We welcome contributions! Please see the [Developer Portal](https://superset.apache.org/developer_portal/) for details. +Define named actions that can be triggered from menus, keyboard shortcuts, or code: + +```typescript +import { commands } from '@apache-superset/core'; + +commands.registerCommand( + { + id: 'my-extension.copy-query', + title: 'Copy Query', + icon: 'CopyOutlined', + description: 'Copy the current query to clipboard', + }, + () => { + /* implementation */ + }, +); +``` + +### Menus + +Attach commands to primary, secondary, or context menus at a given location: + +```typescript +import { menus } from '@apache-superset/core'; + +menus.registerMenuItem( + { view: 'sqllab.editor', command: 'my-extension.copy-query' }, + 'sqllab.editor', + 'primary', +); +``` + +### Editors + +Replace the default text editor for one or more languages: + +```typescript +import { editors } from '@apache-superset/core'; +import MonacoSQLEditor from './MonacoSQLEditor'; + +editors.registerEditor( + { + id: 'my-extension.monaco-sql', + name: 'Monaco SQL Editor', + languages: ['sql'], + }, + MonacoSQLEditor, +); +``` ## 📄 License @@ -105,12 +129,6 @@ Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com ## 🔗 Links -- [Apache Superset](https://superset.apache.org/) -- [Documentation](https://superset.apache.org/docs/) - [Community](https://superset.apache.org/community/) - [GitHub Repository](https://github.com/apache/superset) -- [Extension Development Guide](https://superset.apache.org/docs/extensions/) - ---- - -**Note**: This package is currently in release candidate status. APIs may change before the 1.0.0 release. Please check the [changelog](CHANGELOG.md) for breaking changes between versions. +- [Extensions Documentation](https://superset.apache.org/developer-docs/extensions/overview) diff --git a/superset-frontend/packages/superset-core/package.json b/superset-frontend/packages/superset-core/package.json index c6cae725228..d95b5bea6ec 100644 --- a/superset-frontend/packages/superset-core/package.json +++ b/superset-frontend/packages/superset-core/package.json @@ -1,6 +1,6 @@ { "name": "@apache-superset/core", - "version": "0.0.1-rc11", + "version": "0.1.0-rc1", "description": "This package contains UI elements, APIs, and utility functions used by Superset.", "sideEffects": false, "main": "lib/index.js",