thingsboard-cli 4.3.1.2__tar.gz → 4.3.1.2.post1__tar.gz

thingsboard_cli-4.3.1.2.post1/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Notes for working on `thingsboard-cli` locally.
+
+## Local development
+
+Editable install — changes take effect immediately:
+
+```bash
+uv tool install -e .
+```
+
+> **Note:** `uv tool install` overwrites any previous installation. When switching between editable and published installs, uninstall first to avoid stale cache issues:
+> ```bash
+> uv tool uninstall thingsboard-cli
+> ```
+
+## Updating `tb-pe-client`
+
+The `tb-pe-client` dependency is pulled from PyPI and updated frequently. To pick up a new version:
+
+```bash
+uv lock --refresh-package tb-pe-client && uv sync
+```
+
+## Regenerating help text
+
+After updating `tb-pe-client`, regenerate the verbose-help (`-H`) text from the API docs:
+
+```bash
+./scripts/generate-help.sh
+```
+
+This reads the markdown docs from `../thingsboard-java-client/pe/docs/` and generates Python modules in `src/thingsboard_cli/help/_generated/`.
+
+## Publishing
+
+Requires [twine](https://twine.readthedocs.io/) for uploading and credentials configured in `~/.pypirc`:
+
+```bash
+uv tool install twine
+```
+
+```bash
+./scripts/release.sh --version 4.3.1.2.post1         # TestPyPI (default, staging)
+./scripts/release.sh --version 4.3.1.2 --prod        # PyPI (production)
+./scripts/release.sh --version 4.3.1.2 --dry-run     # Build only, no upload
+```
+
+> TestPyPI is the default on purpose — a misfire goes to staging, not to the real index. Add `--prod` only when you intend to publish a production release.
+
+The publish script automatically updates the scaffold content hash in `scaffold/manifest.json` before building. If you change scaffold files without publishing, update the hash manually:
+
+```bash
+uv run python scripts/update_scaffold_hash.py
+```
+
+CI enforces that the hash matches — if scaffold files change but `manifest.json` isn't updated, `test_scaffold_hash_matches_manifest` will fail.

thingsboard_cli-4.3.1.2.post1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: thingsboard-cli
+Version: 4.3.1.2.post1
+Summary: CLI tool for managing ThingsBoard resources
+Project-URL: Homepage, https://github.com/thingsboard/thingsboard-cli
+Project-URL: Source, https://github.com/thingsboard/thingsboard-cli
+Project-URL: Issues, https://github.com/thingsboard/thingsboard-cli/issues
+Requires-Python: <3.15,>=3.11
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: filelock<4.0,>=3.13
+Requires-Dist: httpx<1.0,>=0.28
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic-settings<3.0,>=2.13
+Requires-Dist: pydantic<3.0,>=2.12
+Requires-Dist: rich<15.0,>=14.0
+Requires-Dist: tb-pe-client==4.3.1.2
+Requires-Dist: textual<2.0,>=0.83
+Requires-Dist: typer<1.0,>=0.24.1
+Requires-Dist: tzdata>=2024.1
+Description-Content-Type: text/markdown
+
+# ThingsBoard CLI
+
+CLI tool for managing ThingsBoard resources from the terminal.
+
+## Installation
+
+Install [uv](https://docs.astral.sh/uv/) if you don't have it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then install the CLI:
+
+```bash
+uv tool install thingsboard-cli
+```
+
+### Upgrading
+
+The CLI checks for updates automatically on launch and prompts to upgrade. You can also upgrade manually:
+
+```bash
+tb update
+```
+
+### Shell Completion
+
+```bash
+# Bash
+tb --install-completion bash
+
+# Zsh
+tb --install-completion zsh
+
+# Fish
+tb --install-completion fish
+```
+
+Restart your terminal after installing completion.
+
+## Usage
+
+```bash
+tb --help
+tb config set --url https://thingsboard.cloud --api-key YOUR_KEY
+tb device list
+```
+
+## Verbose Help
+
+Use `-H` or `--help-verbose` on any command to see detailed API documentation, JSON schemas, and field descriptions:
+
+```bash
+tb device create -H
+tb dashboard save -H
+```
+
+## Contributing
+
+For local development setup, editable installs, regenerating help text, and publishing, see [CONTRIBUTING.md](https://github.com/thingsboard/thingsboard-cli/blob/master/CONTRIBUTING.md).

thingsboard_cli-4.3.1.2.post1/README.md

@@ -0,0 +1,61 @@
+# ThingsBoard CLI
+
+CLI tool for managing ThingsBoard resources from the terminal.
+
+## Installation
+
+Install [uv](https://docs.astral.sh/uv/) if you don't have it:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then install the CLI:
+
+```bash
+uv tool install thingsboard-cli
+```
+
+### Upgrading
+
+The CLI checks for updates automatically on launch and prompts to upgrade. You can also upgrade manually:
+
+```bash
+tb update
+```
+
+### Shell Completion
+
+```bash
+# Bash
+tb --install-completion bash
+
+# Zsh
+tb --install-completion zsh
+
+# Fish
+tb --install-completion fish
+```
+
+Restart your terminal after installing completion.
+
+## Usage
+
+```bash
+tb --help
+tb config set --url https://thingsboard.cloud --api-key YOUR_KEY
+tb device list
+```
+
+## Verbose Help
+
+Use `-H` or `--help-verbose` on any command to see detailed API documentation, JSON schemas, and field descriptions:
+
+```bash
+tb device create -H
+tb dashboard save -H
+```
+
+## Contributing
+
+For local development setup, editable installs, regenerating help text, and publishing, see [CONTRIBUTING.md](https://github.com/thingsboard/thingsboard-cli/blob/master/CONTRIBUTING.md).

thingsboard_cli-4.3.1.2.post1/extension-starter/Dockerfile

@@ -0,0 +1,30 @@
+#
+# Copyright © 2026-2026 ThingsBoard, Inc.
+#
+# Licensed 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.
+#
+
+FROM thingsboard/openjdk25:trixie-slim
+
+WORKDIR /home/thingsboard
+
+# --chmod sets the exec bit at copy time so there is no RUN step. A RUN would
+# execute in the target architecture, forcing QEMU emulation on cross-arch
+# builds (e.g. building linux/arm64 on an amd64 host); COPY --chmod avoids that
+# entirely. Requires BuildKit (default on Docker 23+).
+COPY --chmod=0755 extension/target/classes/docker/start-extension.sh /home/thingsboard/
+COPY extension/target/thingsboard-extension-*.jar /home/thingsboard/thingsboard-extension.jar
+
+USER thingsboard
+
+CMD ["./start-extension.sh"]

thingsboard_cli-4.3.1.2.post1/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "thingsboard-cli"
+version = "4.3.1.2.post1"
+description = "CLI tool for managing ThingsBoard resources"
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+dependencies = [
+    "typer>=0.24.1,<1.0",
+    "click>=8.1,<9.0",
+    "pydantic>=2.12,<3.0",
+    "pydantic-settings>=2.13,<3.0",
+    "rich>=14.0,<15.0",
+    "textual>=0.83,<2.0",
+    "httpx>=0.28,<1.0",
+    "tb-pe-client==4.3.1.2",
+    "packaging>=24.0",
+    "filelock>=3.13,<4.0",
+    # IANA time-zone database for `zoneinfo`. Windows ships no system tz data,
+    # so emulator timeZone validation (ZoneInfo("UTC")) fails without this.
+    "tzdata>=2024.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/thingsboard/thingsboard-cli"
+Source = "https://github.com/thingsboard/thingsboard-cli"
+Issues = "https://github.com/thingsboard/thingsboard-cli/issues"
+
+[project.scripts]
+thingsboard = "thingsboard_cli.main:app"
+tb = "thingsboard_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/thingsboard_cli"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"scaffold" = "thingsboard_cli/scaffold"
+"extension-starter" = "thingsboard_cli/extension-starter"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+src = ["src", "tests"]
+exclude = ["src/thingsboard_cli/help/_generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "UP", "B", "SIM", "RUF", "I"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+exclude = ["src/thingsboard_cli/help/_generated"]
+disallow_any_generics = false
+warn_return_any = false
+
+[[tool.mypy.overrides]]
+module = "tb_pe_client.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "e2e: end-to-end tests requiring real ThingsBoard instance",
+    "requires_tb: e2e tests that require TB_URL/TB_API_KEY (auto-applied to most e2e files; test_extension.py opts out)",
+    "maven_e2e: e2e tests that require a working Maven wrapper + JDK 17+",
+    "docker_e2e: e2e tests that require a reachable Docker daemon",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.20.0",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "respx>=0.22.0",
+    "ruff>=0.15.8",
+]

thingsboard_cli-4.3.1.2.post1/scripts/generate_help.py

@@ -0,0 +1,374 @@
+"""Build-time script to parse ThingsBoard API markdown docs and generate Python help modules.
+
+Reads markdown documentation produced by the thingsboard-python-client package and
+generates Python modules containing pre-processed help text for the CLI's verbose
+help system.
+
+Usage::
+
+    uv run python scripts/generate_help.py
+    uv run python scripts/generate_help.py --docs-path /path/to/docs --output-path /path/to/output
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+
+def parse_controller_doc(content: str) -> dict[str, dict]:
+    """Parse a controller API markdown doc into a dict of method metadata.
+
+    Splits on ``## method_name`` headers and extracts HTTP method/path,
+    description text, parameters table, and return type for each method.
+
+    Args:
+        content: Raw markdown content of a controller doc file.
+
+    Returns:
+        Dict mapping method names to dicts with keys:
+        ``http``, ``description``, ``parameters``, ``return_type``.
+    """
+    methods: dict[str, dict] = {}
+
+    # Split on ## headers that represent method names (not ### or deeper)
+    # We look for lines starting with "## " followed by a word-character method name
+    sections = re.split(r"(?m)^## (\w+)\s*$", content)
+
+    # sections[0] is preamble (before first ## method), then alternating name/body pairs
+    for i in range(1, len(sections), 2):
+        raw_name = sections[i]
+        # Convert camelCase to snake_case to match @api_docs decorator values
+        method_name = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", raw_name).lower()
+        body = sections[i + 1] if i + 1 < len(sections) else ""
+
+        method_data: dict[str, str] = {}
+
+        # Extract HTTP method and path: **POST** `/api/...`
+        http_match = re.search(r"\*\*(\w+)\*\*\s+`([^`]+)`", body)
+        if http_match:
+            method_data["http"] = f"{http_match.group(1)} {http_match.group(2)}"
+        else:
+            method_data["http"] = ""
+
+        # Extract description: text between the HTTP line and ### Parameters
+        # The HTTP line is **METHOD** `/path`, description follows after it
+        desc_text = ""
+        if http_match:
+            after_http = body[http_match.end() :]
+            params_match = re.search(r"### Parameters", after_http)
+            if params_match:
+                desc_text = after_http[: params_match.start()].strip()
+            else:
+                # No parameters section, take everything up to ### Return type
+                return_match = re.search(r"### Return type", after_http)
+                desc_text = after_http[: return_match.start()].strip() if return_match else after_http.strip()
+        method_data["description"] = desc_text
+
+        # Extract parameters: text under ### Parameters until ### Return type or end
+        params_match = re.search(
+            r"### Parameters\s*\n(.*?)(?=### Return type|\Z)",
+            body,
+            re.DOTALL,
+        )
+        method_data["parameters"] = params_match.group(1).strip() if params_match else ""
+
+        # Extract return type: text after ### Return type
+        return_match = re.search(r"### Return type\s*\n(.*?)(?=\n## |\Z)", body, re.DOTALL)
+        if return_match:
+            raw_return = return_match.group(1).strip()
+            # Clean ** markdown bold markers
+            raw_return = raw_return.replace("**", "")
+            # Detect "empty response" variants
+            if "empty response" in raw_return.lower() or raw_return.lower() == "none":
+                method_data["return_type"] = "None"
+            else:
+                method_data["return_type"] = raw_return
+        else:
+            method_data["return_type"] = ""
+
+        methods[method_name] = method_data
+
+    return methods
+
+
+def parse_model_doc(content: str) -> dict:
+    """Parse a model markdown doc into structured metadata.
+
+    Extracts the model name, properties table, readonly fields, and
+    referenced types section.
+
+    Args:
+        content: Raw markdown content of a model doc file.
+
+    Returns:
+        Dict with keys: ``name``, ``fields``, ``readonly_fields``,
+        ``referenced_types``.
+    """
+    result: dict = {}
+
+    # Extract name from # ModelName header
+    name_match = re.search(r"^#\s+(\w+)", content, re.MULTILINE)
+    result["name"] = name_match.group(1) if name_match else ""
+
+    # Extract fields: text between ## Properties and ## Referenced Types (or standalone ---)
+    # The --- must be on its own line (not inside a table separator row like |---|---|)
+    fields_match = re.search(
+        r"## Properties\s*\n(.*?)(?=## Referenced Types|^---$|\Z)",
+        content,
+        re.DOTALL | re.MULTILINE,
+    )
+    result["fields"] = fields_match.group(1).strip() if fields_match else ""
+
+    # Extract readonly_fields: field names where Notes column contains [readonly]
+    readonly_fields: list[str] = []
+    # Look for table rows with [readonly] in the last column
+    for row_match in re.finditer(
+        r"\|\s*\*\*(\w+)\*\*\s*\|[^|]*\|[^|]*\|\s*([^|]*)\|",
+        result["fields"],
+    ):
+        field_name = row_match.group(1)
+        notes = row_match.group(2)
+        if "[readonly]" in notes:
+            readonly_fields.append(field_name)
+    result["readonly_fields"] = readonly_fields
+
+    # Extract referenced_types: text under ## Referenced Types until standalone ---
+    # The --- must be on its own line (not inside a table separator like |---|---|)
+    ref_match = re.search(
+        r"## Referenced Types\s*\n(.*?)(?=^---$|\Z)",
+        content,
+        re.DOTALL | re.MULTILINE,
+    )
+    result["referenced_types"] = ref_match.group(1).strip() if ref_match else ""
+
+    return result
+
+
+def _escape_triple_quotes(text: str) -> str:
+    """Escape triple-quote sequences in text destined for triple-quoted strings.
+
+    Replaces ``\"\"\"`` with ``\"\"\\\"`` so the generated Python source remains valid.
+    """
+    return text.replace('"""', '""\\"')
+
+
+def generate_command_module(methods: dict[str, dict]) -> str:
+    """Generate Python source code for a command help module.
+
+    Produces a module with a ``COMMANDS`` dict mapping method names to dicts
+    containing ``description``, ``http``, ``parameters``, and ``return_type``.
+
+    Args:
+        methods: Dict of method metadata as returned by :func:`parse_controller_doc`.
+
+    Returns:
+        Valid Python source code as a string.
+    """
+    lines: list[str] = []
+    lines.append('"""Auto-generated command help. Do not edit manually."""')
+    lines.append("")
+    lines.append("COMMANDS: dict[str, dict[str, str]] = {")
+
+    for method_name, data in methods.items():
+        lines.append(f"    {method_name!r}: {{")
+
+        for key in ("description", "http", "parameters", "return_type"):
+            value = data.get(key, "")
+            if "\n" in value:
+                escaped = _escape_triple_quotes(value)
+                lines.append(f'        {key!r}: r"""\\')
+                for line in escaped.split("\n"):
+                    lines.append(line)
+                lines.append('"""')
+                lines[-1] = lines[-1] + ","
+            else:
+                lines.append(f"        {key!r}: {value!r},")
+
+        lines.append("    },")
+
+    lines.append("}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def generate_model_module(model_data: dict) -> str:
+    """Generate Python source code for a model help module.
+
+    Produces a module with a ``MODEL`` dict containing ``name``, ``fields``,
+    ``readonly_fields``, and ``referenced_types``.
+
+    Args:
+        model_data: Dict of model metadata as returned by :func:`parse_model_doc`.
+
+    Returns:
+        Valid Python source code as a string.
+    """
+    lines: list[str] = []
+    lines.append('"""Auto-generated model help. Do not edit manually."""')
+    lines.append("")
+    lines.append("MODEL: dict = {")
+
+    # name — always a simple string
+    lines.append(f'    "name": {model_data["name"]!r},')
+
+    # fields — may be multiline
+    fields = model_data.get("fields", "")
+    if "\n" in fields:
+        escaped = _escape_triple_quotes(fields)
+        lines.append('    "fields": r"""\\')
+        for line in escaped.split("\n"):
+            lines.append(line)
+        lines.append('""",')
+    else:
+        lines.append(f'    "fields": {fields!r},')
+
+    # readonly_fields — list of strings
+    lines.append(f'    "readonly_fields": {model_data.get("readonly_fields", [])!r},')
+
+    # referenced_types — may be multiline
+    ref_types = model_data.get("referenced_types", "")
+    if "\n" in ref_types:
+        escaped = _escape_triple_quotes(ref_types)
+        lines.append('    "referenced_types": r"""\\')
+        for line in escaped.split("\n"):
+            lines.append(line)
+        lines.append('""",')
+    else:
+        lines.append(f'    "referenced_types": {ref_types!r},')
+
+    lines.append("}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def controller_name_from_filename(filename: str) -> str:
+    """Convert a controller doc filename to a snake_case module name.
+
+    Examples::
+
+        controller_name_from_filename("DeviceControllerApi.md") -> "device"
+        controller_name_from_filename("EntityRelationControllerApi.md") -> "entity_relation"
+    """
+    # Strip the "ControllerApi.md" suffix
+    stem = filename.replace("ControllerApi.md", "")
+    # Convert PascalCase to snake_case
+    s1 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", stem)
+    return s1.lower()
+
+
+def model_name_to_module(name: str) -> str:
+    """Convert a PascalCase model name to a snake_case module name.
+
+    Examples::
+
+        model_name_to_module("DeviceProfile") -> "device_profile"
+        model_name_to_module("Device") -> "device"
+    """
+    s1 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name)
+    return s1.lower()
+
+
+def generate_all(docs_path: Path, output_path: Path) -> dict[str, int]:
+    """Process all markdown docs and generate Python help modules.
+
+    Creates the output directory structure with ``__init__.py`` files,
+    processes all ``*ControllerApi.md`` files into command modules, and
+    processes remaining ``*.md`` files into model modules.
+
+    Args:
+        docs_path: Path to directory containing markdown doc files.
+        output_path: Path to output directory for generated Python modules.
+
+    Returns:
+        Dict with counts: ``{"controllers": N, "models": N}``.
+    """
+    # Create output directory structure
+    commands_dir = output_path / "commands"
+    models_dir = output_path / "models"
+
+    output_path.mkdir(parents=True, exist_ok=True)
+    commands_dir.mkdir(parents=True, exist_ok=True)
+    models_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create __init__.py files
+    for dir_path in (output_path, commands_dir, models_dir):
+        init_file = dir_path / "__init__.py"
+        if not init_file.exists():
+            init_file.write_text("", encoding="utf-8")
+
+    controller_count = 0
+    model_count = 0
+
+    # Process controller docs
+    for md_file in sorted(docs_path.glob("*ControllerApi.md")):
+        content = md_file.read_text(encoding="utf-8")
+        methods = parse_controller_doc(content)
+        if not methods:
+            continue
+
+        module_name = controller_name_from_filename(md_file.name)
+        module_code = generate_command_module(methods)
+        (commands_dir / f"{module_name}.py").write_text(module_code, encoding="utf-8")
+        controller_count += 1
+
+    # Process model docs (all .md files that are NOT controller docs)
+    for md_file in sorted(docs_path.glob("*.md")):
+        if "ControllerApi" in md_file.name:
+            continue
+
+        content = md_file.read_text(encoding="utf-8")
+        model_data = parse_model_doc(content)
+        if not model_data.get("name"):
+            continue
+
+        module_name = model_name_to_module(model_data["name"])
+        module_code = generate_model_module(model_data)
+        (models_dir / f"{module_name}.py").write_text(module_code, encoding="utf-8")
+        model_count += 1
+
+    return {"controllers": controller_count, "models": model_count}
+
+
+def main() -> None:
+    """CLI entry point for the help generation script."""
+    script_dir = Path(__file__).resolve().parent
+
+    parser = argparse.ArgumentParser(
+        description="Generate Python help modules from ThingsBoard API markdown docs.",
+    )
+    parser.add_argument(
+        "--docs-path",
+        type=Path,
+        default=script_dir / ".." / "thingsboard-java-client" / "pe" / "docs",
+        help="Path to the directory containing markdown doc files.",
+    )
+    parser.add_argument(
+        "--output-path",
+        type=Path,
+        default=script_dir / ".." / "src" / "thingsboard_cli" / "help" / "_generated",
+        help="Path to the output directory for generated Python modules.",
+    )
+    args = parser.parse_args()
+
+    docs_path: Path = args.docs_path.resolve()
+    output_path: Path = args.output_path.resolve()
+
+    if not docs_path.exists():
+        parser.error(f"Docs path does not exist: {docs_path}")
+
+    if not docs_path.is_dir():
+        parser.error(f"Docs path is not a directory: {docs_path}")
+
+    print(f"Docs path:   {docs_path}")
+    print(f"Output path: {output_path}")
+
+    result = generate_all(docs_path, output_path)
+
+    print(f"Generated {result['controllers']} controller modules")
+    print(f"Generated {result['models']} model modules")
+
+
+if __name__ == "__main__":
+    main()