shellsmith 0.2.1__tar.gz → 0.4.0__tar.gz

shellsmith-0.4.0/.gitignore

@@ -0,0 +1,20 @@
+.backup
+.coverage
+.idea
+.pytest_cache
+.ruff_cache
+.venv*
+*.egg-info
+__pycache__
+aasx
+aas-*
+build
+coverage.xml
+dist
+db.sqlite3
+htmlcov
+site
+venv
+*_config.json
+*.log
+settings.local.json

shellsmith-0.4.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: shellsmith
+Version: 0.4.0
+Summary: A Python SDK and CLI for Eclipse BaSyx to manage Asset Administration Shells (AAS)
+Project-URL: Homepage, https://github.com/SmartFactory-KL/shellsmith
+Project-URL: Issues, https://github.com/SmartFactory-KL/shellsmith/issues
+Project-URL: Documentation, https://shellsmith.pages.dev
+Author-email: Peter Stein <peter.stein@dfki.de>
+License: MIT License
+        
+        Copyright (c) 2025 Peter Stein
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: aas,asset-administration-shell,basyx,cli,digital-twin,eclipse-basyx,i40,industry40,python,rest-client,typer
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: fastmcp
+Requires-Dist: httpx
+Requires-Dist: pydantic-settings
+Requires-Dist: pyyaml
+Requires-Dist: typer
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: termynal; extra == 'docs'
+Provides-Extra: neo4j
+Requires-Dist: neo4j; extra == 'neo4j'
+Provides-Extra: test
+Requires-Dist: mypy; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-dotenv; extra == 'test'
+Requires-Dist: ruff; extra == 'test'
+Requires-Dist: types-pyyaml; extra == 'test'
+Requires-Dist: types-requests; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <img src="https://raw.githubusercontent.com/SmartFactory-KL/shellsmith/main/docs/images/logo-purple-500.png" alt="shellsmith">
+</div>
+
+<div align="center">
+  <a href="https://github.com/SmartFactory-KL/shellsmith/actions/workflows/test.yaml"><img src="https://github.com/SmartFactory-KL/shellsmith/actions/workflows/test.yaml/badge.svg" alt="Test"></a>
+  <a href="https://codecov.io/gh/SmartFactory-KL/shellsmith"><img src="https://codecov.io/gh/SmartFactory-KL/shellsmith/branch/main/graph/badge.svg" alt="codecov"></a>
+  <a href="https://pypi.org/project/shellsmith"><img src="https://img.shields.io/pypi/v/shellsmith?color=%2334D058" alt="PyPI - Version"></a>
+  <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>
+</div>
+
+<p align="center">
+    <b>Documentation</b>: <a href="https://shellsmith.pages.dev/" target="_blank">https://shellsmith.pages.dev</a>
+</p>
+
+**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 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/) Environment REST API  
+
+## 🚀 Installation
+
+```bash
+pip install shellsmith
+```
+
+**Requires**: Python 3.10+
+
+## 🧠 CLI Usage
+
+Shellsmith provides a powerful command-line interface:
+
+```bash
+aas --help
+```
+
+| Command  | Description                                              |
+|----------|----------------------------------------------------------|
+| `info`   | Display the current Shell tree and identify issues.      |
+| `upload` | Upload a single AAS file or all AAS files from a folder. |
+| `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.
+
+➡️ Full CLI reference: [shellsmith.pages.dev/cli](https://shellsmith.pages.dev/cli)
+
+## 🐍 Python API Usage
+
+You can also use `shellsmith` as a Python client library to interact with the BaSyx Environment REST API.
+
+```python
+import shellsmith
+
+# Fetch all AAS Shells
+shells = shellsmith.get_shells()
+
+# 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")
+```
+
+> ℹ️ `shell_id` and `submodel_id` are automatically base64-encoded unless you pass `encode=False`.
+
+➡️ Full Python API reference: [shellsmith.pages.dev/api](https://shellsmith.pages.dev/api)
+
+## 🔧 Configuration
+
+The default AAS environment host is:
+
+```
+http://localhost:8081
+```
+
+You can override it in several ways:
+
+- Set the environment variable:  
+  ```bash
+  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234
+  ```
+
+- Create a `.env` file in your project with:  
+  ```dotenv
+  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234
+  ```
+
+- Use the `--host` option with any CLI command:  
+  ```bash
+  aas get shells --host https://your-host:1234
+  ```
+
+- Pass the `host` parameter in any `shellsmith` Python function:  
+  ```python
+  shellsmith.get_shells(host="https://your-host:1234")
+  ```
+
+> 💡 The `--host` CLI flag and `host=` Python argument **take precedence** over environment variables and `.env`.
+
+## 🤝 Contributing
+
+We welcome contributions!
+
+See the [Contributing Guide](https://shellsmith.pages.dev/contributing/) for setup, testing, and coding standards.
+
+## Resources
+
+- https://github.com/eclipse-basyx/basyx-java-server-sdk
+- https://github.com/admin-shell-io/aas-specs-api
+- https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection

shellsmith-0.4.0/README.md

@@ -0,0 +1,123 @@
+<div align="center">
+    <img src="https://raw.githubusercontent.com/SmartFactory-KL/shellsmith/main/docs/images/logo-purple-500.png" alt="shellsmith">
+</div>
+
+<div align="center">
+  <a href="https://github.com/SmartFactory-KL/shellsmith/actions/workflows/test.yaml"><img src="https://github.com/SmartFactory-KL/shellsmith/actions/workflows/test.yaml/badge.svg" alt="Test"></a>
+  <a href="https://codecov.io/gh/SmartFactory-KL/shellsmith"><img src="https://codecov.io/gh/SmartFactory-KL/shellsmith/branch/main/graph/badge.svg" alt="codecov"></a>
+  <a href="https://pypi.org/project/shellsmith"><img src="https://img.shields.io/pypi/v/shellsmith?color=%2334D058" alt="PyPI - Version"></a>
+  <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>
+</div>
+
+<p align="center">
+    <b>Documentation</b>: <a href="https://shellsmith.pages.dev/" target="_blank">https://shellsmith.pages.dev</a>
+</p>
+
+**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 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/) Environment REST API  
+
+## 🚀 Installation
+
+```bash
+pip install shellsmith
+```
+
+**Requires**: Python 3.10+
+
+## 🧠 CLI Usage
+
+Shellsmith provides a powerful command-line interface:
+
+```bash
+aas --help
+```
+
+| Command  | Description                                              |
+|----------|----------------------------------------------------------|
+| `info`   | Display the current Shell tree and identify issues.      |
+| `upload` | Upload a single AAS file or all AAS files from a folder. |
+| `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.
+
+➡️ Full CLI reference: [shellsmith.pages.dev/cli](https://shellsmith.pages.dev/cli)
+
+## 🐍 Python API Usage
+
+You can also use `shellsmith` as a Python client library to interact with the BaSyx Environment REST API.
+
+```python
+import shellsmith
+
+# Fetch all AAS Shells
+shells = shellsmith.get_shells()
+
+# 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")
+```
+
+> ℹ️ `shell_id` and `submodel_id` are automatically base64-encoded unless you pass `encode=False`.
+
+➡️ Full Python API reference: [shellsmith.pages.dev/api](https://shellsmith.pages.dev/api)
+
+## 🔧 Configuration
+
+The default AAS environment host is:
+
+```
+http://localhost:8081
+```
+
+You can override it in several ways:
+
+- Set the environment variable:  
+  ```bash
+  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234
+  ```
+
+- Create a `.env` file in your project with:  
+  ```dotenv
+  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234
+  ```
+
+- Use the `--host` option with any CLI command:  
+  ```bash
+  aas get shells --host https://your-host:1234
+  ```
+
+- Pass the `host` parameter in any `shellsmith` Python function:  
+  ```python
+  shellsmith.get_shells(host="https://your-host:1234")
+  ```
+
+> 💡 The `--host` CLI flag and `host=` Python argument **take precedence** over environment variables and `.env`.
+
+## 🤝 Contributing
+
+We welcome contributions!
+
+See the [Contributing Guide](https://shellsmith.pages.dev/contributing/) for setup, testing, and coding standards.
+
+## Resources
+
+- https://github.com/eclipse-basyx/basyx-java-server-sdk
+- https://github.com/admin-shell-io/aas-specs-api
+- https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection

shellsmith-0.4.0/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["hatchling >= 1.26", "hatch-vcs>=0.3"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shellsmith"
+dynamic = ["version"]
+authors = [{ name = "Peter Stein", email = "peter.stein@dfki.de" }]
+description = "A Python SDK 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 = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "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 = [
+    "httpx",
+    "pydantic-settings",
+    "fastmcp",
+    "pyyaml",
+    "typer",
+]
+
+[project.optional-dependencies]
+test = [
+    "mypy",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "pytest-dotenv",
+    "ruff",
+    "types-pyyaml",
+    "types-requests"
+]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "termynal",
+]
+neo4j = [
+    "neo4j",
+]
+
+[project.scripts]
+aas = "shellsmith.cli.app:main"
+shellsmith-mcp = "shellsmith.mcp.server:cli_main"
+
+[project.urls]
+Homepage = "https://github.com/SmartFactory-KL/shellsmith"
+Issues = "https://github.com/SmartFactory-KL/shellsmith/issues"
+Documentation = "https://shellsmith.pages.dev"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "ANN",  # flake8-annotations
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "D",    # pydocstyle
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "PL",   # pylint
+    "SIM",  # flake8-simplify
+    "UP",   # pyupgrade
+    "W",    # pycodestyle warnings
+]
+
+ignore = [
+    "ANN401",  # Allow Any types
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["D104", "F401"]
+"tests/**/test_*.py" = ["ANN", "PL"]
+"tests/**/*.py" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

shellsmith-0.4.0/src/shellsmith/__init__.py

@@ -0,0 +1,50 @@
+"""Module level imports."""
+
+from importlib.metadata import version
+
+__version__ = version("shellsmith")
+
+from .api import (
+    create_shell,
+    create_submodel,
+    create_submodel_element,
+    create_submodel_ref,
+    delete_shell,
+    delete_submodel,
+    delete_submodel_element,
+    delete_submodel_ref,
+    get_health_status,
+    get_shell,
+    get_shells,
+    get_submodel,
+    get_submodel_element,
+    get_submodel_element_value,
+    get_submodel_elements,
+    get_submodel_metadata,
+    get_submodel_refs,
+    get_submodel_value,
+    get_submodels,
+    is_healthy,
+    update_shell,
+    update_submodel,
+    update_submodel_element,
+    update_submodel_element_value,
+    update_submodel_value,
+)
+from .clients import AsyncClient, Client
+from .upload import upload_aas, upload_aas_folder
+
+# Aliases for backwards compatibility
+post_shell = create_shell
+put_shell = update_shell
+
+post_submodel = create_submodel
+put_submodel = update_submodel
+post_submodel_ref = create_submodel_ref
+patch_submodel_value = update_submodel_value
+
+post_submodel_element = create_submodel_element
+put_submodel_element = update_submodel_element
+patch_submodel_element_value = update_submodel_element_value
+
+health = get_health_status

shellsmith-0.4.0/src/shellsmith/__main__.py

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