lvtypedesc 0.2.0__tar.gz

lvtypedesc-0.2.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

lvtypedesc-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: jlianesglrs

lvtypedesc-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

lvtypedesc-0.2.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0]
+
+- Command-line interface: a `lvtypedesc` console script with `decode` (optional
+  `--tree`), `codes`, `--version` and runnable `--help` examples. Errors go to
+  stderr with exit code 1.
+- `to_bytes` re-emits the canonical short-form descriptor for every modelled
+  node, so parsing and emission are inverses for the supported subset.
+- New public API: `TypeCode` enum, `known_codes()`, `pretty()`, `to_bytes()`,
+  and the `FixedPoint` and `Refnum` node types.
+- Fixed-point (`FXP`) and refnum descriptors are now recognised. Their
+  type-specific bytes are preserved verbatim rather than interpreted, because
+  their internal layout is version-specific and not fully documented.
+- `LVString` now carries the descriptor's 32-bit `size` word (`VARIABLE` when not
+  fixed), so fixed-size strings round-trip exactly.
+- README now states the provenance plainly: the code table is community
+  reverse-engineering from the LabVIEW wiki, not an official NI byte spec.
+
+## [0.1.0]
+
+- First release.
+- `parse_type_descriptor` reads a LabVIEW type-descriptor byte string into a
+  typed tree of frozen dataclasses, and `describe` renders it as a readable line.
+- Supported subset: numeric scalars (I8 to U64, SGL, DBL, EXT, complex),
+  booleans, strings, paths, pictures, n-dimensional arrays and nested clusters.
+- Out-of-scope codes (enums, variants, waveforms, refnums) and truncated input
+  raise `TypeDescError`. Fills the gap left by VI-file parsers, which do not
+  decode the runtime type-descriptor byte string.

lvtypedesc-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/lvtypedesc/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests inject time, disk and network; they
+  never touch the real thing.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

lvtypedesc-0.2.0/IMPROVEMENTS-round.md

@@ -0,0 +1,63 @@
+# Improvements round
+
+Ranked, substantial improvements for this round. Each is additive: the existing
+`parse_type_descriptor` / `describe` API keeps working unchanged.
+
+## Provenance note (read first)
+
+The type-descriptor code table this library uses is the community
+reverse-engineering published at the LabVIEW wiki
+(https://labviewwiki.org/wiki/Type_descriptor). It is consistent with the
+scattered fragments NI has published, but it is **not** an official, byte-exact
+NI specification. Codes can also differ between LabVIEW versions and between the
+in-memory 16-bit-word form and the flattened byte form. So every code and layout
+below is treated as the common documented set, not a guarantee, and the parser
+reports honest errors rather than guessing. Where a payload cannot be verified
+(fixed-point and refnum internals), the raw bytes are preserved instead of being
+invented into fields.
+
+## Ranked improvements
+
+1. **Command-line interface.** A real `lvtypedesc` console script (argparse,
+   `[project.scripts]`): `decode` a hex descriptor into a readable type, a
+   `codes` listing of every code the library knows, `--version`, and a `--help`
+   with runnable examples. Errors go to stderr with exit code 1. This is the
+   single biggest reach improvement: it makes the library usable without writing
+   Python.
+
+2. **Expose the type-code enum.** A public `TypeCode` `IntEnum` so callers can
+   refer to `TypeCode.DBL` instead of a bare `0x0A`, plus `known_codes()` that
+   returns the full `(code, name, category)` table that backs the CLI listing.
+
+3. **Round-trip emission.** `to_bytes(node)` re-emits the canonical descriptor
+   for every node type the library models, so `parse` and `to_bytes` are
+   inverses for the supported subset. This is round-trip "where defined": it
+   emits the short-form descriptor and refuses (honest error) when the length
+   would overflow the 16-bit short-form length word.
+
+4. **Recognise fixed-point and refnum.** FXP (`0x5F`) and Refnum (`0x70`) move
+   from "unsupported, raises" to recognised nodes. Because their internal
+   payload layout is version-specific and not fully verifiable, the parser keeps
+   the raw payload bytes rather than inventing fields. The refnum subtype word is
+   surfaced as a best-effort `subtype` and documented as provisional.
+
+5. **Faithful string sizing.** `LVString` now carries the descriptor's 32-bit
+   size word (`VARIABLE` for `0xFFFFFFFF`), so fixed-size strings, paths and
+   pictures round-trip exactly and the size is inspectable.
+
+6. **Multi-line pretty-print.** `pretty(node)` renders a parsed descriptor as an
+   indented tree, complementing the existing one-line `describe`. The CLI uses it
+   for `decode --tree`.
+
+7. **Stronger tests.** A contract test that parses representative descriptors for
+   every structural family (scalar, string, array of DBL, cluster) and asserts
+   the whole typed tree; round-trip property tests; a CLI unit test; and a real
+   end-to-end test that pip-installs the package editable and drives the actual
+   installed `lvtypedesc` console script through a subprocess.
+
+## Deliberately out of scope
+
+Enums, variants and waveforms stay unsupported with a clear error: their payloads
+are not documented well enough to parse honestly. No codes are invented. The
+long-form (32-bit length) descriptor variant is not emitted; `to_bytes` reports
+when a tree is too large for the short form instead of guessing the long form.

lvtypedesc-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+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.

lvtypedesc-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: lvtypedesc
+Version: 0.2.0
+Summary: Parse LabVIEW type-descriptor byte strings into a readable, typed schema
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/lvtypedesc
+Project-URL: Issues, https://github.com/JaviLianes8/lvtypedesc/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/lvtypedesc/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lvtypedesc
+
+Parse LabVIEW type-descriptor byte strings into a readable, typed schema
+
+## Install
+
+```
+pip install lvtypedesc
+```
+
+A LabVIEW type descriptor is the small, length-prefixed block of type codes that
+precedes flattened LabVIEW data. This library turns that block into a typed tree
+you can inspect, which is the schema a generic unflatten needs.
+
+## Usage
+
+```python
+from lvtypedesc import parse_type_descriptor, describe, pretty, to_bytes
+
+# A 1D array of clusters, each holding an I32 and a string.
+data = bytes.fromhex(
+    "001C 0040 0001 FFFFFFFF 0012 0050 0002 0004 0003 0008 0030 FFFFFFFF".replace(" ", "")
+)
+
+node = parse_type_descriptor(data)
+print(describe(node))  # 1D Array of Cluster { I32, String }
+print(node.rank)  # 1
+print(node.element.fields[0].name)  # I32
+print(to_bytes(node) == data)  # True, round-trips exactly
+print(pretty(node))
+# Array (rank 1, dims [variable])
+#   Cluster (2 fields)
+#     [0] I32
+#     [1] String (size variable)
+```
+
+The tree is built from frozen dataclasses: `Scalar`, `Boolean`, `LVString` (with
+`size`), `Array` (with `element` and `dimensions`), `Cluster` (with `fields`),
+`FixedPoint` and `Refnum`. A dimension or string whose size is not fixed in the
+descriptor uses the sentinel `VARIABLE`. Trailing bytes, such as the flattened
+data after the descriptor, are ignored. Truncated, unknown or out-of-scope input
+raises `TypeDescError`.
+
+`to_bytes` re-emits the canonical short-form descriptor for any node the library
+models, so `parse_type_descriptor` and `to_bytes` are inverses for the supported
+subset. `TypeCode` exposes the recognised codes by name and `known_codes()`
+returns the full table.
+
+## Command line
+
+Installing the package also installs a `lvtypedesc` console script:
+
+```
+$ lvtypedesc decode 00040003
+I32
+$ lvtypedesc decode 000E00400001FFFFFFFF0004000A
+1D Array of DBL
+$ lvtypedesc decode --tree 000E00500002000400030004000A
+Cluster (2 fields)
+  [0] I32
+  [1] DBL
+$ lvtypedesc codes          # list every recognised type code
+$ lvtypedesc --version
+```
+
+Whitespace in the hex is ignored. Errors go to stderr with exit code 1. Run
+`lvtypedesc --help` for the full list of examples.
+
+## Supported subset
+
+Fully parsed: the numeric scalars (`I8` to `U64`, `SGL`, `DBL`, `EXT` and the
+complex variants), booleans, strings, paths, pictures, n-dimensional arrays and
+clusters, nested to any depth. Fixed-point (`FXP`) and refnum descriptors are
+recognised and their type-specific bytes preserved, but their internal layout is
+not interpreted (see provenance below).
+
+Not covered, and reported with a clear error: enums, variants and waveforms,
+whose payloads are not documented well enough to parse honestly.
+
+## Provenance (please read)
+
+The type-descriptor code table used here is **community reverse-engineering**,
+documented at the [LabVIEW wiki](https://labviewwiki.org/wiki/Type_descriptor).
+It is consistent with the fragments NI has published but it is **not** an
+official, byte-exact NI specification. Two further caveats:
+
+- Codes can change between LabVIEW versions, so treat them as the common
+  documented set rather than a guarantee for every build.
+- The in-memory 16-bit-word form and the flattened byte form can differ. This
+  library parses the flattened byte form.
+
+Because of this, anything that cannot be verified is treated as provisional:
+unknown codes raise an honest error instead of a guess, and the fixed-point and
+refnum payloads are kept as raw bytes rather than invented into fields. The
+refnum `subtype` word is surfaced best-effort and is itself provisional.
+
+## Why
+
+LabVIEW ships flattened data with a leading type descriptor, and decoding it in
+Python needs that descriptor parsed into a schema first. OpenG's Variant Data
+Library parses descriptors inside LabVIEW, but it is LabVIEW VIs, not Python. The
+existing PyPI packages read LabVIEW source files instead: `pylabview` and `lvkit`
+parse the `.vi` binary, `pylavi` validates VI files. None of them exposes a parser
+for the raw runtime type-descriptor byte string that precedes flattened data or
+sits inside a variant. This library fills that gap with a zero-dependency, fully
+typed reader for the common documented types.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

lvtypedesc-0.2.0/README.md

@@ -0,0 +1,116 @@
+# lvtypedesc
+
+Parse LabVIEW type-descriptor byte strings into a readable, typed schema
+
+## Install
+
+```
+pip install lvtypedesc
+```
+
+A LabVIEW type descriptor is the small, length-prefixed block of type codes that
+precedes flattened LabVIEW data. This library turns that block into a typed tree
+you can inspect, which is the schema a generic unflatten needs.
+
+## Usage
+
+```python
+from lvtypedesc import parse_type_descriptor, describe, pretty, to_bytes
+
+# A 1D array of clusters, each holding an I32 and a string.
+data = bytes.fromhex(
+    "001C 0040 0001 FFFFFFFF 0012 0050 0002 0004 0003 0008 0030 FFFFFFFF".replace(" ", "")
+)
+
+node = parse_type_descriptor(data)
+print(describe(node))  # 1D Array of Cluster { I32, String }
+print(node.rank)  # 1
+print(node.element.fields[0].name)  # I32
+print(to_bytes(node) == data)  # True, round-trips exactly
+print(pretty(node))
+# Array (rank 1, dims [variable])
+#   Cluster (2 fields)
+#     [0] I32
+#     [1] String (size variable)
+```
+
+The tree is built from frozen dataclasses: `Scalar`, `Boolean`, `LVString` (with
+`size`), `Array` (with `element` and `dimensions`), `Cluster` (with `fields`),
+`FixedPoint` and `Refnum`. A dimension or string whose size is not fixed in the
+descriptor uses the sentinel `VARIABLE`. Trailing bytes, such as the flattened
+data after the descriptor, are ignored. Truncated, unknown or out-of-scope input
+raises `TypeDescError`.
+
+`to_bytes` re-emits the canonical short-form descriptor for any node the library
+models, so `parse_type_descriptor` and `to_bytes` are inverses for the supported
+subset. `TypeCode` exposes the recognised codes by name and `known_codes()`
+returns the full table.
+
+## Command line
+
+Installing the package also installs a `lvtypedesc` console script:
+
+```
+$ lvtypedesc decode 00040003
+I32
+$ lvtypedesc decode 000E00400001FFFFFFFF0004000A
+1D Array of DBL
+$ lvtypedesc decode --tree 000E00500002000400030004000A
+Cluster (2 fields)
+  [0] I32
+  [1] DBL
+$ lvtypedesc codes          # list every recognised type code
+$ lvtypedesc --version
+```
+
+Whitespace in the hex is ignored. Errors go to stderr with exit code 1. Run
+`lvtypedesc --help` for the full list of examples.
+
+## Supported subset
+
+Fully parsed: the numeric scalars (`I8` to `U64`, `SGL`, `DBL`, `EXT` and the
+complex variants), booleans, strings, paths, pictures, n-dimensional arrays and
+clusters, nested to any depth. Fixed-point (`FXP`) and refnum descriptors are
+recognised and their type-specific bytes preserved, but their internal layout is
+not interpreted (see provenance below).
+
+Not covered, and reported with a clear error: enums, variants and waveforms,
+whose payloads are not documented well enough to parse honestly.
+
+## Provenance (please read)
+
+The type-descriptor code table used here is **community reverse-engineering**,
+documented at the [LabVIEW wiki](https://labviewwiki.org/wiki/Type_descriptor).
+It is consistent with the fragments NI has published but it is **not** an
+official, byte-exact NI specification. Two further caveats:
+
+- Codes can change between LabVIEW versions, so treat them as the common
+  documented set rather than a guarantee for every build.
+- The in-memory 16-bit-word form and the flattened byte form can differ. This
+  library parses the flattened byte form.
+
+Because of this, anything that cannot be verified is treated as provisional:
+unknown codes raise an honest error instead of a guess, and the fixed-point and
+refnum payloads are kept as raw bytes rather than invented into fields. The
+refnum `subtype` word is surfaced best-effort and is itself provisional.
+
+## Why
+
+LabVIEW ships flattened data with a leading type descriptor, and decoding it in
+Python needs that descriptor parsed into a schema first. OpenG's Variant Data
+Library parses descriptors inside LabVIEW, but it is LabVIEW VIs, not Python. The
+existing PyPI packages read LabVIEW source files instead: `pylabview` and `lvkit`
+parse the `.vi` binary, `pylavi` validates VI files. None of them exposes a parser
+for the raw runtime type-descriptor byte string that precedes flattened data or
+sits inside a variant. This library fills that gap with a zero-dependency, fully
+typed reader for the common documented types.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

lvtypedesc-0.2.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lvtypedesc"
+version = "0.2.0"
+description = "Parse LabVIEW type-descriptor byte strings into a readable, typed schema"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.scripts]
+lvtypedesc = "lvtypedesc._cli:main"
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/lvtypedesc"
+Issues = "https://github.com/JaviLianes8/lvtypedesc/issues"
+Changelog = "https://github.com/JaviLianes8/lvtypedesc/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lvtypedesc"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

lvtypedesc-0.2.0/requirements-dev.txt

@@ -0,0 +1,3 @@
+# Development dependencies: the package in editable mode plus its dev extras
+# (ruff, mypy, pytest, build, twine). Install with:  pip install -r requirements-dev.txt
+-e .[dev]

lvtypedesc-0.2.0/scripts/check.ps1

@@ -0,0 +1,16 @@
+# Local quality gate. Run before every commit. No CI runs in the cloud.
+# $ErrorActionPreference does NOT stop on a native command's non-zero exit, so each tool's
+# exit code is checked explicitly: a red gate must fail, never pass silently.
+$ErrorActionPreference = "Stop"
+
+function Invoke-Step($label, [scriptblock]$cmd) {
+    Write-Host "== $label =="
+    & $cmd
+    if ($LASTEXITCODE -ne 0) { Write-Host "FAILED: $label (exit $LASTEXITCODE)"; exit $LASTEXITCODE }
+}
+
+Invoke-Step "ruff format" { ruff format --check src tests }
+Invoke-Step "ruff lint"   { ruff check src tests }
+Invoke-Step "mypy"        { mypy src tests }
+Invoke-Step "pytest"      { pytest }
+Write-Host "gate green"

lvtypedesc-0.2.0/scripts/release.ps1

@@ -0,0 +1,28 @@
+# Build and upload to PyPI. Run scripts/check.ps1 first.
+# The name must not already exist on PyPI; the token is read from a secret store, never git.
+$ErrorActionPreference = "Stop"
+
+# Works on both Windows PowerShell 5.1 and pwsh 7 (generic catch, no PS7-only types).
+$taken = $true
+try {
+    Invoke-WebRequest -UseBasicParsing "https://pypi.org/pypi/lvtypedesc/json" | Out-Null
+} catch {
+    if ($_.Exception.Response.StatusCode.value__ -eq 404) { $taken = $false } else { throw }
+}
+if ($taken) { throw "The name 'lvtypedesc' already exists on PyPI. Choose another before publishing." }
+
+$token = $env:PYPI_TOKEN
+if (-not $token -and (Test-Path "C:\secrets\pypi-token.txt")) {
+    $token = (Get-Content "C:\secrets\pypi-token.txt" -Raw).Trim()
+}
+if (-not $token) {
+    throw "No PyPI token. Set `$env:PYPI_TOKEN or save it to C:\secrets\pypi-token.txt (never commit it)."
+}
+
+Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue
+python -m build
+python -m twine check dist/*
+
+$env:TWINE_USERNAME = "__token__"
+$env:TWINE_PASSWORD = $token
+try { python -m twine upload dist/* } finally { Remove-Item Env:\TWINE_PASSWORD -ErrorAction SilentlyContinue }

lvtypedesc-0.2.0/src/lvtypedesc/__init__.py

@@ -0,0 +1,43 @@
+"""Parse LabVIEW type-descriptor byte strings into a readable, typed schema."""
+
+from __future__ import annotations
+
+from ._codes import Category, TypeCode, known_codes
+from ._emit import to_bytes
+from ._errors import TypeDescError
+from ._model import (
+    VARIABLE,
+    Array,
+    Boolean,
+    Cluster,
+    FixedPoint,
+    LVString,
+    Refnum,
+    Scalar,
+    TypeDesc,
+    describe,
+)
+from ._parser import parse_type_descriptor
+from ._pretty import pretty
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "VARIABLE",
+    "Array",
+    "Boolean",
+    "Category",
+    "Cluster",
+    "FixedPoint",
+    "LVString",
+    "Refnum",
+    "Scalar",
+    "TypeCode",
+    "TypeDesc",
+    "TypeDescError",
+    "describe",
+    "known_codes",
+    "parse_type_descriptor",
+    "pretty",
+    "to_bytes",
+]

lvtypedesc-0.2.0/src/lvtypedesc/_cli.py

@@ -0,0 +1,91 @@
+"""Command-line interface for lvtypedesc.
+
+Decode a hex type descriptor into a readable type, or list the codes the library
+knows. Errors are written to stderr and the process exits with status 1.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from ._codes import known_codes
+from ._errors import TypeDescError
+from ._model import describe
+from ._parser import parse_type_descriptor
+from ._pretty import pretty
+
+_EXAMPLES = """\
+examples:
+  lvtypedesc decode 00040003                          -> I32
+  lvtypedesc decode "0004 000A"                       -> DBL (spaces are ignored)
+  lvtypedesc decode 000E00400001FFFFFFFF0004000A      -> 1D Array of DBL
+  lvtypedesc decode --tree 000E00500002000400030004000A
+  lvtypedesc codes                                    -> list every known type code
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="lvtypedesc",
+        description="Parse LabVIEW type-descriptor byte strings into a readable type.",
+        epilog=_EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"lvtypedesc {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    decode = sub.add_parser(
+        "decode",
+        help="decode a hex type descriptor into a readable type",
+        description="Decode a hex type descriptor. Whitespace in the hex is ignored.",
+    )
+    decode.add_argument("hex", help="the type descriptor as hex, for example 00040003")
+    decode.add_argument(
+        "--tree",
+        action="store_true",
+        help="print an indented tree instead of a one-line summary",
+    )
+
+    sub.add_parser(
+        "codes",
+        help="list every type code the library recognises",
+        description="List every recognised type code, with its name and category.",
+    )
+    return parser
+
+
+def _run_decode(hex_text: str, tree: bool) -> int:
+    try:
+        data = bytes.fromhex(hex_text)
+    except ValueError as exc:
+        print(f"error: not valid hex: {exc}", file=sys.stderr)
+        return 1
+    try:
+        node = parse_type_descriptor(data)
+    except TypeDescError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(pretty(node) if tree else describe(node))
+    return 0
+
+
+def _run_codes() -> int:
+    for code, name, category in known_codes():
+        print(f"0x{code:02X}  {name:<10} {category.value}")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the ``lvtypedesc`` console script."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "decode":
+        return _run_decode(args.hex, args.tree)
+    return _run_codes()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())