diff --git a/README.md b/README.md index b12a3e2..9e62e88 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,24 @@ CLI tool for easy usage of the Superset API. -[![License](https://img.shields.io/badge/license-bsd-3.svg)](https://choosealicense.com/licenses/bsd-3-clause/) [![Repo Status](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![CI](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml/badge.svg)](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml) - -* [Installation](#installation) -* [Overview](#overview) -* [Usage](#usage) -* [Commands](#commands) -* [Examples](#examples) -* [Used Libraries](#used-libraries) -* [Issues, Ideas And Bugs](#issues-ideas-and-bugs) -* [License](#license) -* [Contribution](#contribution) +[![License](https://img.shields.io/badge/license-bsd-3.svg)](https://choosealicense.com/licenses/bsd-3-clause/) [![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![CI](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml/badge.svg)](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml) + +- [Overview](#overview) +- [Installation](#installation) +- [Usage](#usage) + - [Flags](#flags) + - [Login options](#login-options) +- [Commands](#commands) +- [Examples](#examples) +- [Compile into an executable](#compile-into-an-executable) +- [Used Libraries](#used-libraries) +- [Issues, Ideas And Bugs](#issues-ideas-and-bugs) +- [License](#license) +- [Contribution](#contribution) + +## Overview + +More information on the deployment and architecture can be found in the [doc](./doc/README.md) folder. ## Installation @@ -22,31 +29,54 @@ cd pySupersetCli pip install . ``` -## Overview - -WIP - ## Usage Show help information: ```cmd -pySupersetCli --help +pySupersetCli [-h] -u -p -s [--version] [-v] [--no_ssl] [--basic_auth] {command} {command_options} ``` +### Flags + +| Flag | Description | +| :-----------: | ----------------------------------------------------------------------------------------------- | +| --verbose , -v | Print full command details before executing the command. Enables logs of type INFO and WARNING. | +| --version | Import a ticket from a JSON file. | +| --help , -h | Show the help message and exit. | +| --no_ssl | Disables SSL certificate verification. | +| --basic_auth | Use basic authentication instead of LDAP. | + +### Login options + +To connect to the Superset server, provide all credentials via Command Line arguments: + - `--server ` is required. + - ID using `--user ` and `--password ` + ## Commands -WIP +| Command | Description | +| :-----------------------------------------: | --------------------------------------------------- | +|[upload](./doc/commands/upload.md) | Upload a JSON file to a Superset instance. | ## Examples Check out the all the [Examples](./examples) on how to use the pySupersetCli tool. +## Compile into an executable + +It is possible to create an executable file that contains the tool and all its dependencies. "PyInstaller" is used for this. +Just run the following command on the root of the folder: + +```cmd +pyinstaller --noconfirm --onefile --console --name "pySupersetCli" --add-data "./pyproject.toml;." "./src/pySupersetCli/__main__.py" +``` + ## Used Libraries Used 3rd party libraries which are not part of the standard Python package: -* [toml](https://github.com/uiri/toml) - Parsing [TOML](https://en.wikipedia.org/wiki/TOML) - MIT License +- [toml](https://github.com/uiri/toml) - Parsing [TOML](https://en.wikipedia.org/wiki/TOML) - MIT License ## Issues, Ideas And Bugs diff --git a/design/README.md b/design/README.md deleted file mode 100644 index e69de29..0000000 diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..a595c55 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,9 @@ +# Documentation + +## Deployment + +![deployment](https://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/NewTec-GmbH/pySupersetCli/main/doc/uml/deployment.puml) + +## Architecture + +![architecture](https://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/NewTec-GmbH/pySupersetCli/main/doc/uml/architecture.puml) diff --git a/doc/commands/upload.md b/doc/commands/upload.md new file mode 100644 index 0000000..d160eb8 --- /dev/null +++ b/doc/commands/upload.md @@ -0,0 +1,19 @@ +# Upload + +Upload a JSON file to a Superset instance. + +The user mus supply the following parameters: + +- database: DB to upload the data to. +- table: Existing table in the database to save the data to. +- file: JSON-formatted file containing the data. + +```cmd +pySupersetCli -u -p -s --basic_auth --no_ssl upload --database "TEST" --table "dummy" --file "input.json" +``` + +## JSON File format + +The JSON file must contain a JSON Object, in which the keys are interpreted as the columns of the table. Nested objects are not accepted and the command will fail in case a nested object is supplied. Each time the command is called, a new row will be appended to the database/table specified. + +If the table already exists, it is not possible to change the column names/order (no changes in the schema allowed). diff --git a/doc/uml/architecture.puml b/doc/uml/architecture.puml new file mode 100644 index 0000000..6d532c4 --- /dev/null +++ b/doc/uml/architecture.puml @@ -0,0 +1,20 @@ +@startuml ArchitectureDiagram + +package "pySupersetCli" as pySupersetCli { + component "Main Entry Point" as main + component "superset"as server + component "Commands" <> as cmd +} + +package "Python" as python { + component "Argparse" as argparse + component "Requests" as requests +} + +main *--> server +main o--> cmd : 0..* +main *--> argparse + +server *--> requests + +@enduml \ No newline at end of file diff --git a/doc/uml/deployment.puml b/doc/uml/deployment.puml new file mode 100644 index 0000000..a5041d2 --- /dev/null +++ b/doc/uml/deployment.puml @@ -0,0 +1,33 @@ +@startuml DeploymentDiagram + +node "Apache Superset"<> as superset + +database "DB Server" { + component "Database" as supersetDb + + note bottom of supersetDb + The database is project specific, means + one database per project. + end note +} + +interface "REST API" as supersetRestApi + +superset --- supersetRestApi +superset -- supersetDb + +node "Continuous Integration Server"<> { + + package "scripts" { + component "pySupersetCli" as pySupersetCli + } +} + +supersetRestApi )-- pySupersetCli + +note top of superset + Report frontend for project metrics. +end note + + +@enduml \ No newline at end of file