This is an automated email from the ASF dual-hosted git repository.
michaelsmolina pushed a commit to branch 5.0-extensions
in repository https://gitbox.apache.org/repos/asf/superset.git
commit cc62e437dc5fcf72265bda384a4930c09a315e90
Author: Michael S. Molina <70410625+michael-s-mol...@users.noreply.github.com>
AuthorDate: Wed Aug 27 15:49:29 2025 -0300
chore: Adds README and CHANGELOG to apache-superset-core and
apache-superset-cli (#34867)
(cherry picked from commit 30c72ba0a3bfd66ba82b95e7e9c1e76c0ed56c8c)
---
superset-cli/{README.md => CHANGELOG.md} | 4 +-
superset-cli/README.md | 92 ++++++++++++++++-
superset-cli/pyproject.toml | 27 ++++-
.../README.md => superset-core/CHANGELOG.md | 4 +-
superset-core/README.md | 113 +++++++++++++++++++++
superset-core/pyproject.toml | 23 ++++-
6 files changed, 252 insertions(+), 11 deletions(-)
diff --git a/superset-cli/README.md b/superset-cli/CHANGELOG.md
similarity index 89%
copy from superset-cli/README.md
copy to superset-cli/CHANGELOG.md
index b8a77f431e..c6db81dd39 100644
--- a/superset-cli/README.md
+++ b/superset-cli/CHANGELOG.md
@@ -17,6 +17,6 @@ specific language governing permissions and limitations
under the License.
-->
-# Apache Superset SDK
+## Change Log
-This is an SDK tool used for bundling Apache Superset extensions.
+Changelogs will be added once we have the first stable release.
diff --git a/superset-cli/README.md b/superset-cli/README.md
index b8a77f431e..637dce8680 100644
--- a/superset-cli/README.md
+++ b/superset-cli/README.md
@@ -17,6 +17,94 @@ specific language governing permissions and limitations
under the License.
-->
-# Apache Superset SDK
+# apache-superset-cli
-This is an SDK tool used for bundling Apache Superset extensions.
+[](https://badge.fury.io/py/apache-superset-cli)
+[](https://opensource.org/licenses/Apache-2.0)
+[](https://www.python.org/downloads/)
+
+Official command-line interface for building, bundling, and managing Apache
Superset extensions. This CLI tool provides developers with everything needed
to create, develop, and package extensions for the Superset ecosystem.
+
+## 🚀 Features
+
+- **Extension Scaffolding** - Generate initial folder structure and scaffold
new extension projects
+- **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
+
+## 📦 Installation
+
+```bash
+pip install apache-superset-cli
+```
+
+## 🛠️ Quick Start
+
+### Available Commands
+
+```bash
+# Generate initial folder structure and scaffold a new extension project
+superset-extensions init <extension-name>
+
+# 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:
+
+```
+extension_name/
+├── 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
+│ ├── 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
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see the [Contributing
Guide](https://github.com/apache/superset/blob/master/CONTRIBUTING.md) 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.
diff --git a/superset-cli/pyproject.toml b/superset-cli/pyproject.toml
index 30f11fecf4..32b74ee356 100644
--- a/superset-cli/pyproject.toml
+++ b/superset-cli/pyproject.toml
@@ -17,19 +17,33 @@
[project]
name = "apache-superset-cli"
-version = "0.0.1"
-description = "SDK to build Apache Superset extensions"
+version = "0.0.1rc1"
+description = "Official command-line interface for building, bundling, and
managing Apache Superset extensions"
+readme = "README.md"
authors = [
{ name = "Apache Software Foundation", email = "d...@superset.apache.org"
},
]
license = { file="LICENSE.txt" }
requires-python = ">=3.10"
+keywords = ["superset", "apache", "cli", "extensions", "analytics",
"business-intelligence", "development-tools"]
classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Environment :: Console",
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: Apache Software License",
+ "Operating System :: OS Independent",
+ "Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Topic :: Database",
+ "Topic :: Scientific/Engineering :: Visualization",
+ "Topic :: Software Development :: Build Tools",
+ "Topic :: Software Development :: Libraries :: Python Modules",
+ "Topic :: System :: Software Distribution",
]
dependencies = [
- "apache-superset-core>=0.0.1, <0.2",
+ "apache-superset-core>=0.0.1rc1, <0.2",
"click>=8.0.3",
"jinja2>=3.1.4",
"semver>=3.0.4",
@@ -37,6 +51,13 @@ dependencies = [
"watchdog>=6.0.0",
]
+[project.urls]
+Homepage = "https://superset.apache.org/";
+Documentation = "https://superset.apache.org/docs/";
+Repository = "https://github.com/apache/superset";
+"Bug Tracker" = "https://github.com/apache/superset/issues";
+Changelog = "https://github.com/apache/superset/blob/master/CHANGELOG.md";
+
[project.optional-dependencies]
test = [
"pytest",
diff --git a/superset-cli/README.md b/superset-core/CHANGELOG.md
similarity index 89%
copy from superset-cli/README.md
copy to superset-core/CHANGELOG.md
index b8a77f431e..c6db81dd39 100644
--- a/superset-cli/README.md
+++ b/superset-core/CHANGELOG.md
@@ -17,6 +17,6 @@ specific language governing permissions and limitations
under the License.
-->
-# Apache Superset SDK
+## Change Log
-This is an SDK tool used for bundling Apache Superset extensions.
+Changelogs will be added once we have the first stable release.
diff --git a/superset-core/README.md b/superset-core/README.md
new file mode 100644
index 0000000000..53587e2148
--- /dev/null
+++ b/superset-core/README.md
@@ -0,0 +1,113 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# apache-superset-core
+
+[](https://badge.fury.io/py/apache-superset-core)
+[](https://opensource.org/licenses/Apache-2.0)
+[](https://www.python.org/downloads/)
+
+The official core package for building Apache Superset backend extensions and
integrations. This package provides essential building blocks including base
classes, API utilities, type definitions, and decorators for both the host
application and extensions.
+
+## 📦 Installation
+
+```bash
+pip install apache-superset-core
+```
+
+## 🏗️ Architecture
+
+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
+
+## 🚀 Quick Start
+
+### Basic Extension Structure
+
+```python
+from flask import request, Response
+from flask_appbuilder.api import expose, permission_name, protect, safe
+from superset_core.api import models, query, rest_api
+from superset_core.api.types.rest_api import RestApi
+
+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)
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see the [Contributing
Guide](https://github.com/apache/superset/blob/master/CONTRIBUTING.md) 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/)
+- [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.
diff --git a/superset-core/pyproject.toml b/superset-core/pyproject.toml
index 692e157fbe..5d14fb1735 100644
--- a/superset-core/pyproject.toml
+++ b/superset-core/pyproject.toml
@@ -18,21 +18,40 @@
[project]
name = "apache-superset-core"
-version = "0.0.1"
-description = "Common components for Apache Superset"
+version = "0.0.1rc1"
+description = "Core Python package for building Apache Superset backend
extensions and integrations"
+readme = "README.md"
authors = [
{ name = "Apache Software Foundation", email = "d...@superset.apache.org"
},
]
license = { file="LICENSE.txt" }
requires-python = ">=3.10"
+keywords = ["superset", "apache", "analytics", "business-intelligence",
"extensions", "visualization"]
classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Environment :: Web Environment",
+ "Intended Audience :: Developers",
+ "License :: OSI Approved :: Apache Software License",
+ "Operating System :: OS Independent",
+ "Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Topic :: Database",
+ "Topic :: Scientific/Engineering :: Visualization",
+ "Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = [
"flask-appbuilder>=4.5.3, <5.0.0",
]
+[project.urls]
+Homepage = "https://superset.apache.org/";
+Documentation = "https://superset.apache.org/docs/";
+Repository = "https://github.com/apache/superset";
+"Bug Tracker" = "https://github.com/apache/superset/issues";
+Changelog = "https://github.com/apache/superset/blob/master/CHANGELOG.md";
+
[build-system]
requires = ["setuptools>=76.0.0", "wheel"]
build-backend = "setuptools.build_meta"
