Replace argparse with typer

Author: ptrstn

README.md

@@ -9,14 +9,16 @@
   <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
 </p>
 
-Shellsmith is a Python toolkit and CLI for managing Asset Administration Shells (AAS), Submodels, and related resources. 
-It is designed to interact with [Eclipse BaSyx](https://www.eclipse.org/basyx/), a middleware platform for AAS that follows the [Industry 4.0 standard](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).
+**Shellsmith** is a Python SDK and CLI for managing [Asset Administration Shells (AAS)](https://industrialdigitaltwin.org/en/content-hub/aasspecifications), Submodels, and Submodel Elements via the [Eclipse BaSyx](https://www.eclipse.org/basyx/) REST API.  
+ 
+It provides full client-side access to AAS resources with a clean Python interface and a powerful `typer`-based CLI — ideal for scripting, automation, and digital twin integration workflows.
 
 ### Features
 
-- Python API for CRUD operations on shells, submodels, and submodel elements
-- CLI interface for quick scripting
-- `.env`-based configuration
+- 🔧 **Python SDK** for full CRUD access to Shells, Submodels, and Submodel Elements  
+- ⚡ **CLI tool** powered by [Typer](https://typer.tiangolo.com/) for fast scripting and automation  
+- ⚙️ Simple `.env`-based configuration for flexible environment switching  
+- 🔁 Seamless integration with the [Eclipse BaSyx](https://www.eclipse.org/basyx/) AAS REST API  
 
 ## 🚀 Installation
 
@@ -34,56 +36,114 @@ The default AAS environment host is:
 http://localhost:8081
 ```
 
-You can override it by setting the `SHELLSMITH_BASYX_ENV_HOST` environment variable, or by creating a `.env` file in your project root with:
+You can override it by setting the `SHELLSMITH_BASYX_ENV_HOST` environment variable, or by creating a `.env` file in the current working directory or your project root.
 
 ```bash
 SHELLSMITH_BASYX_ENV_HOST=http://your-host:1234
 ```
 
-## 🛠️ Usage
+## 🧠 CLI Usage
 
-```bash
-aas --help
-```
-
-Common commands:
+Shellsmith provides a powerful command-line interface:
 
 ```bash
-aas info                  # Show all shells and submodels
-aas upload <file|folder>  # Upload AAS file or folder
-
-aas shell delete <id>     # Delete a shell
-aas submodel delete <id>  # Delete a submodel
-
-aas sme get <id> <path>               # Get Submodel element value
-aas sme patch <id> <path> <new_value> # Set Submodel element value
-```
-
-Use `--cascade` or `--unlink` to control deletion behavior:
-
-```bash
-aas shell delete <id> --cascade      # Also delete referenced submodels
-aas submodel delete <id> --unlink    # Remove references from shells
+aas --help
 ```
 
-## 📡 API Usage
-
-You can also use `shellsmith` as a Python package:
+| Command  | Description                                              |
+|----------|----------------------------------------------------------|
+| `upload` | Upload a single AAS file or all AAS files from a folder. |
+| `info`   | Display the current Shell tree and identify issues.      |
+| `nuke`   | ☢️ Delete all Shells and Submodels (irrevocable).        |
+| `encode` | Encode a value (e.g. Shell ID) to Base64.                |
+| `decode` | Decode a Base64-encoded value.                           |
+| `get`    | Get Shells, Submodels, and Submodel Elements.            |
+| `delete` | Delete Shells, Submodels, or Submodel Elements.          |
+| `update` | Update Shells, Submodels, or Submodel Elements.          |
+| `create` | Create new Shells, Submodels, or Submodel Elements.      |
+
+> ℹ️ Run `aas <command> --help` to view subcommands and options.
+
+### 🔎 Get Commands
+
+| Command                                         | Description                                 |
+|-------------------------------------------------|---------------------------------------------|
+| `aas get shells`                                | 🔹 Get all available Shells.                |
+| `aas get shell <id>`                            | 🔹 Get a specific Shell by ID.              |
+| `aas get submodel-refs <shell-id>`              | 🔹 Get all Submodel References of a Shell.  |
+| `aas get submodels`                             | 🔸 Get all Submodels.                       |
+| `aas get submodel <id>`                         | 🔸 Get a specific Submodel by ID.           |
+| `aas get submodel-value <id>`                   | 🔸 Get the `$value` of a Submodel.          |
+| `aas get submodel-meta <id>`                    | 🔸 Get the `$metadata` of a Submodel.       |
+| `aas get elements <submodel-id>`                | 🔻 Get all Submodel Elements of a Submodel. |
+| `aas get element <submodel-id> <idShort>`       | 🔻 Get a specific Submodel Element.         |
+| `aas get element-value <submodel-id> <idShort>` | 🔻 Get the `$value` of a Submodel Element.  |
+
+### 🛠️ Create Commands
+
+| Command                                                                      | Description                             |
+|------------------------------------------------------------------------------|-----------------------------------------|
+| `aas create shell [--data <json>] [--file <path>]`                           | 🔹 Create a new Shell.                  |
+| `aas create submodel-ref <shell-id> [--data <json>] [--file <path>]`         | 🔹 Add a Submodel Reference to a Shell. |
+| `aas create submodel [--data <json>] [--file <path>]`                        | 🔸 Create a new Submodel.               |
+| `aas create element <submodel-id> [--data <json>] [--file <path>]`           | 🔻 Create a new Submodel Element.       |
+| `aas create element <submodel-id> <idShort> [--data <json>] [--file <path>]` | 🔻 Create an Element at a nested path.  |
+
+> ℹ️ Input can be passed via `--data "<json>"` or `--file <*.json|*.yaml>`, but **not both**
+
+### 🧬 Update Commands
+
+| Command                                                                      | Description                                                    |
+|------------------------------------------------------------------------------|----------------------------------------------------------------|
+| `aas update shell <id> [--data <json>] [--file <path>]`                      | 🔹 Update a Shell (full replacement).                          |
+| `aas update submodel <id> [--data <json>] [--file <path>]`                   | 🔸 Update a Submodel (full replacement).                       |
+| `aas update submodel-value <id> [--data <json>] [--file <path>]`             | 🔸 Update the `$value` of a Submodel (partial update).         |
+| `aas update element <submodel-id> <idShort> [--data <json>] [--file <path>]` | 🔻 Update a Submodel Element (full replacement).               |
+| `aas update element-value <submodel-id> <idShort> <value>`                   | 🔻 Update the `$value` of a Submodel Element (partial update). |
+
+> ℹ️ All updates are either full replacements (`PUT`) or partial updates (`PATCH`)
+
+### 🧹 Delete Commands
+
+| Command                                            | Description                                                    |
+|----------------------------------------------------|----------------------------------------------------------------|
+| `aas delete shell <id> [--cascade]`                | 🔹 Delete a Shell and optionally all referenced Submodels.     |
+| `aas delete submodel-ref <shell-id> <submodel-id>` | 🔹 Remove a Submodel reference from a Shell.                   |
+| `aas delete submodel <id> [--remove-refs]`         | 🔸 Delete a Submodel and optionally unlink it from all Shells. |
+| `aas delete element <submodel-id> <idShort>`       | 🔻 Delete a Submodel Element.                                  |
+
+
+## 🐍 Python API Usage
+
+You can also use `shellsmith` as a Python client library to interact with the BaSyx Environment REST API.
 
 ```python
 import shellsmith
 
-# Get all available shells
+# List all AAS Shells
 shells = shellsmith.get_shells()
 
-# Get a specific shell by ID (automatically base64-encoded)
-shell = shellsmith.get_shell("example_aas_id")
+# Fetch a specific Shell by ID
+shell = shellsmith.get_shell("https://example.com/aas/my-asset")
+
+# List Submodels or Submodel References of a Shell
+submodels = shellsmith.get_submodels()
+refs = shellsmith.get_submodel_refs("https://example.com/aas/my-asset")
+
+# Fetch a specific Submodel
+submodel = shellsmith.get_submodel("https://example.com/submodels/my-submodel")
+
+# Read and update a Submodel Element's value
+value = shellsmith.get_submodel_element_value(submodel["id"], "temperature")
+shellsmith.patch_submodel_element_value(submodel["id"], "temperature", "42.0")
 
-# Disable base64 encoding if your ID is already encoded
-submodel = shellsmith.get_submodel("ZXhhbXBsZV9hYXNfaWQ=", encode=False)
+# Upload a single AAS file or an entire folder (.aasx / .json / .xml)
+shellsmith.upload_aas("MyAsset.aasx")
+shellsmith.upload_aas_folder("aas_folder/")
 
-# Use a custom AAS environment host
-submodel_refs = shellsmith.get_submodel_refs("example_aas_id", host="http://localhost:8081")
+# Delete a Shell or Submodel by ID
+shellsmith.delete_shell("https://example.com/aas/my-asset")
+shellsmith.delete_submodel("https://example.com/submodels/my-submodel")
 ```
 
 > ℹ️ `shell_id` and `submodel_id` are automatically base64-encoded unless you set `encode=False`. This is required by the BaSyx API for identifier-based URLs.
@@ -94,7 +154,7 @@ The tables below show the mapping between BaSyx AAS REST API endpoints and the i
 
 ### Shells
 
-| Method | BaSyx Endpoint                                               | Shellsmith Function   |
+| Method | BaSyx Endpoint                                               | `shellsmith` Function |
 |--------|--------------------------------------------------------------|-----------------------|
 | GET    | `/shells`                                                    | `get_shells`          |
 | POST   | `/shells`                                                    | `post_shell`          |

pyproject.toml

@@ -5,18 +5,40 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "shellsmith"
 version = "0.2.1"
-description = "A Python toolkit and CLI for managing Asset Administration Shells"
 authors = [{ name = "Peter Stein", email = "peterstein@dfki.de" }]
+description = "Python client and CLI for Eclipse BaSyx to manage Asset Administration Shells (AAS)"
 license = { file = "LICENSE" }
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"
 classifiers = [
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = [
+    "aas",
+    "asset-administration-shell",
+    "basyx",
+    "eclipse-basyx",
+    "industry40",
+    "i40",
+    "digital-twin",
+    "cli",
+    "typer",
+    "rest-client",
+    "python",
 ]
 dependencies = [
     "pydantic-settings",
+    "pyyaml",
     "requests",
+    "typer",
 ]
 
 [project.optional-dependencies]
@@ -32,7 +54,7 @@ neo4j = [
 ]
 
 [project.scripts]
-aas = "shellsmith.cli.main:main"
+aas = "shellsmith.cli.app:main"
 
 [project.urls]
 Homepage = "https://github.com/ptrstn/shellsmith"

pytest.ini

@@ -1,3 +1,2 @@
 [pytest]
 pythonpath = .
-

scripts/section.py

@@ -0,0 +1,27 @@
+"""Utility to generate formatted section headers for the CLI."""
+
+import sys
+
+TOTAL_WIDTH = 88
+CHAR = "─"
+
+
+def section(title: str) -> str:
+    """Creates a formatted section header for organizing code in a Python file."""
+    title = title.strip()
+    prefix = "# "
+    padding = TOTAL_WIDTH - len(prefix) - len(title) - 2  # 2 spaces around title
+    if padding < 0:
+        return f"{prefix}{title}"
+    pad_left = padding // 2 - len(prefix)
+    pad_right = padding - pad_left
+    return f"{prefix}{CHAR * pad_left} {title} {CHAR * pad_right}"
+
+
+if __name__ == "__main__":
+    NUM_ARGS = 2
+    if len(sys.argv) != NUM_ARGS:
+        print('Usage: python section.py "Your Section Title"')
+        sys.exit(1)
+
+    print(section(sys.argv[1]))

src/shellsmith/__init__.py

@@ -1,29 +1,28 @@
 __version__ = "0.2.1"
 
-from .crud.shells import (
+from .crud import (
     delete_shell,
+    delete_submodel,
+    delete_submodel_element,
     delete_submodel_ref,
     get_shell,
     get_shells,
-    get_submodel_refs,
-    post_shell,
-    post_submodel_ref,
-    put_shell,
-)
-from .crud.submodels import (
-    delete_submodel,
-    delete_submodel_element,
     get_submodel,
     get_submodel_element,
     get_submodel_element_value,
     get_submodel_elements,
     get_submodel_metadata,
+    get_submodel_refs,
     get_submodel_value,
     get_submodels,
     patch_submodel_element_value,
     patch_submodel_value,
+    post_shell,
     post_submodel,
     post_submodel_element,
+    post_submodel_ref,
+    put_shell,
     put_submodel,
     put_submodel_element,
 )
+from .upload import upload_aas, upload_aas_folder

src/shellsmith/__main__.py

@@ -1,6 +1,6 @@
 """Entry point for running shellsmith as a CLI tool."""
 
-from shellsmith.cli.main import main
+from shellsmith.cli.app import main
 
 if __name__ == "__main__":
     main()

src/shellsmith/cli/app.py

@@ -0,0 +1,44 @@
+"""Main CLI entry point for shellsmith with Typer."""
+
+import requests
+import typer
+
+from .commands.decode import app as decode_app
+from .commands.encode import app as encode_app
+from .commands.groups.create import app as create_app
+from .commands.groups.delete import app as delete_app
+from .commands.groups.get import app as get_app
+from .commands.groups.update import app as update_app
+from .commands.info import app as info_app
+from .commands.nuke import app as nuke_app
+from .commands.upload import app as upload_app
+
+app = typer.Typer(
+    help="shellsmith - AAS Toolkit command-line interface.",
+    no_args_is_help=True,
+)
+
+app.add_typer(upload_app)
+app.add_typer(info_app)
+app.add_typer(nuke_app)
+app.add_typer(encode_app)
+app.add_typer(decode_app)
+app.add_typer(get_app)
+app.add_typer(delete_app)
+app.add_typer(update_app)
+app.add_typer(create_app)
+
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    try:
+        app()
+    except requests.exceptions.ConnectionError as e:
+        typer.secho(f"😩 {e}", fg=typer.colors.RED)
+    except Exception as e:
+        typer.secho(f"💥 Unexpected error: {e}", fg=typer.colors.RED)
+        raise
+
+
+if __name__ == "__main__":
+    main()

src/shellsmith/cli/args.py

@@ -0,0 +1,30 @@
+"""Reusable CLI arguments in commands."""
+
+import typer
+
+SHELL_ID: typer.Argument = typer.Argument(
+    ...,
+    help="The unique identifier of the Shell.",
+)
+
+SUBMODEL_ID: typer.Argument = typer.Argument(
+    ...,
+    help="The unique identifier of the Submodel.",
+)
+
+ID_SHORT_PATH: typer.Argument = typer.Argument(
+    ...,
+    help="The idShort path for the Submodel Element.",
+)
+
+OPTIONAL_ID_SHORT_PATH: typer.Argument = typer.Argument(
+    None,
+    help="Optional idShort path for a nested Submodel Element.",
+)
+
+AAS_PATH: typer.Argument = typer.Argument(
+    ...,
+    help="The path to the AAS file or folder to upload. Accepts: .json, .xml, .aasx",
+)
+
+VALUE: typer.Argument = typer.Argument(..., help="The new value as string.")

src/shellsmith/cli/commands/__init__.py

@@ -1,6 +0,0 @@
-from .info import info
-from .nuke import nuke
-from .shell import shell_delete
-from .sme import submodel_element_get, submodel_element_patch
-from .submodel import submodel_delete
-from .upload import upload