lvpath 0.3.1__py3-none-any.whl

lvpath/__init__.py

@@ -0,0 +1,48 @@
+"""Convert between LabVIEW path strings and native OS paths.
+
+The textual surface (:func:`to_os_path`, :func:`to_lv_path`, :func:`path_kind`)
+models LabVIEW's ``Path To String`` / ``String To Path``. The flattened surface
+(:class:`FlatPath`, :func:`to_flat_path`, :func:`from_flat_path` and friends)
+models the binary ``Flatten To String`` ``PTH0`` form. The portable surface
+(:func:`from_portable_path`, :func:`to_portable_path`) models the
+platform-independent form LabVIEW writes into configuration and project files,
+such as ``/C/DIR1/DIR2`` for ``C:\\DIR1\\DIR2``.
+"""
+
+from __future__ import annotations
+
+from ._convert import path_kind, to_lv_path, to_os_path
+from ._flatbridge import from_flat_path, to_flat_path
+from ._flatten import (
+    SIGNATURE,
+    FlatPath,
+    FlatPathError,
+    FlatPathType,
+    build_flat_path,
+    parse_flat_path,
+)
+from ._kinds import NotAPathError, PathKind
+from ._platform import Platform
+from ._portable import PortablePathError, from_portable_path, to_portable_path
+
+__version__ = "0.3.1"
+
+__all__ = [
+    "SIGNATURE",
+    "FlatPath",
+    "FlatPathError",
+    "FlatPathType",
+    "NotAPathError",
+    "PathKind",
+    "Platform",
+    "PortablePathError",
+    "build_flat_path",
+    "from_flat_path",
+    "from_portable_path",
+    "parse_flat_path",
+    "path_kind",
+    "to_flat_path",
+    "to_lv_path",
+    "to_os_path",
+    "to_portable_path",
+]

lvpath/_cli.py

@@ -0,0 +1,134 @@
+"""Command-line interface for LabVIEW path strings and the flattened path form.
+
+``lvpath to-native`` turns LabVIEW's portable path string (``/C/DIR1/DIR2``) into
+a native path; ``lvpath to-labview`` does the reverse. ``lvpath decode`` turns the
+hex of a flattened ``PTH0`` byte string into a native path; ``lvpath encode``
+turns a native path into that hex. Errors are written to standard error and the
+process exits with status ``1``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from ._flatbridge import from_flat_path, to_flat_path
+from ._portable import from_portable_path, to_portable_path
+
+_EXAMPLES = """\
+examples:
+  # LabVIEW's portable path string, as written in .ini and .lvproj files, to Windows.
+  lvpath to-native --platform windows "/C/Program Files (x86)/Arduino"
+  # prints C:\\Program Files (x86)\\Arduino
+
+  # A UNC share and a relative path.
+  lvpath to-native --platform windows //server/share/dir
+  lvpath to-native --platform windows "../builds/Main Application"
+
+  # A native Windows path to the portable string LabVIEW writes.
+  lvpath to-labview --platform windows "C:\\DIR1\\DIR2"
+  # prints /C/DIR1/DIR2
+
+  # Decode the NI C:\\File flattened example into a path.
+  lvpath decode --platform windows 505448300000000b0000000201430466696c65
+
+  # Encode a path into its flattened hex form (spaces in the hex are accepted on decode).
+  lvpath encode --platform posix /usr/local/bin
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="lvpath",
+        description=(
+            "Convert LabVIEW's portable path strings to and from native paths, and decode "
+            "or encode the LabVIEW PTH0 flattened path form."
+        ),
+        epilog=_EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"lvpath {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    commands = [
+        (
+            "to-native",
+            "text",
+            "a LabVIEW portable path string to a native path",
+            "Convert a LabVIEW portable path string (/C/DIR1/DIR2, //server/share, a/b) "
+            "into a native path. An empty string is <Not A Path> and is an error.",
+        ),
+        (
+            "to-labview",
+            "path",
+            "a native path to a LabVIEW portable path string",
+            "Convert a native path into the portable path string LabVIEW writes into "
+            "configuration and project files. An empty path prints an empty line, "
+            "LabVIEW's <Not A Path>.",
+        ),
+        (
+            "decode",
+            "hex",
+            "hex of flattened PTH0 bytes to a native path",
+            "Decode the hex of a flattened PTH0 byte string into a native path.",
+        ),
+        (
+            "encode",
+            "path",
+            "a native path to flattened PTH0 hex",
+            "Encode a native path into the hex of its flattened PTH0 byte string.",
+        ),
+    ]
+    for name, argument, short, long in commands:
+        sub = subparsers.add_parser(name, help=short, description=long)
+        sub.add_argument(argument, help=f"the {argument} to convert")
+        _add_platform(sub)
+    return parser
+
+
+def _add_platform(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--platform",
+        choices=["windows", "posix"],
+        default=None,
+        help="native path flavor to use (default: the current operating system)",
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line interface. Returns the process exit status."""
+    args = _build_parser().parse_args(argv)
+    # Paths may hold any Unicode character; a pipe on Windows defaults to a
+    # legacy code page, so write UTF-8 to standard output and standard error.
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(encoding="utf-8")
+    try:
+        print(_run(args.command, args, args.platform))
+    except ValueError as error:
+        print(f"lvpath: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _run(command: str, args: argparse.Namespace, platform: str | None) -> str:
+    if command == "to-native":
+        return str(from_portable_path(args.text, platform=platform))
+    if command == "to-labview":
+        return to_portable_path(args.path, platform=platform)
+    if command == "decode":
+        return str(from_flat_path(_hex_bytes(args.hex), platform=platform))
+    return to_flat_path(args.path, platform=platform).hex()
+
+
+def _hex_bytes(raw_hex: str) -> bytes:
+    try:
+        return bytes.fromhex(raw_hex.replace(" ", ""))
+    except ValueError as error:
+        raise ValueError(f"not valid hex: {error}") from error
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lvpath/_convert.py

@@ -0,0 +1,48 @@
+"""Conversion between LabVIEW path strings and native OS paths."""
+
+from __future__ import annotations
+
+from pathlib import PurePath
+
+from ._kinds import NotAPathError, PathKind
+from ._platform import Platform, flavor, resolve
+
+
+def path_kind(lv_path: str, *, platform: Platform | str | None = None) -> PathKind:
+    """Classify a LabVIEW path string as absolute, relative or not-a-path.
+
+    An empty string is LabVIEW's ``<Not A Path>`` value on every platform.
+    """
+    if lv_path == "":
+        return PathKind.NOT_A_PATH
+    pure = flavor(resolve(platform))(lv_path)
+    return PathKind.ABSOLUTE if pure.is_absolute() else PathKind.RELATIVE
+
+
+def to_os_path(lv_path: str, *, platform: Platform | str | None = None) -> PurePath:
+    """Parse a LabVIEW path string into a ``PurePath`` of the platform flavor.
+
+    Raises :class:`NotAPathError` for the empty not-a-path value, which has no
+    operating-system path. Forward slashes are accepted when parsing a Windows
+    path, matching LabVIEW's lenient reader. This reads the host's native text
+    form; for the portable form LabVIEW writes into configuration and project
+    files (``/C/DIR1/DIR2``) use :func:`lvpath.from_portable_path`.
+    """
+    if lv_path == "":
+        raise NotAPathError("LabVIEW not-a-path has no OS path")
+    return flavor(resolve(platform))(lv_path)
+
+
+def to_lv_path(os_path: PurePath | str | None, *, platform: Platform | str | None = None) -> str:
+    """Serialize an OS path into a LabVIEW path string for ``platform``.
+
+    ``None`` or an empty string becomes LabVIEW's not-a-path value (``""``).
+    The components of ``os_path`` are rendered with the separators of the
+    target platform, so a relative path crosses platforms cleanly.
+    """
+    if os_path is None or os_path == "":
+        return ""
+    target = flavor(resolve(platform))
+    if isinstance(os_path, str):
+        return str(target(os_path))
+    return str(target(*os_path.parts))

lvpath/_flatbridge.py

@@ -0,0 +1,69 @@
+"""Bridge the PTH0 flattened form to and from ``pathlib.PurePath``.
+
+Only the two documented path type codes are interpreted here: absolute (``0``)
+and relative (``1``). UNC, driveless and empty / not-a-path forms carry type
+codes the NI documentation does not state, so they are refused with a clear
+error rather than guessed. The low-level :mod:`lvpath._flatten` codec still
+round-trips their raw bytes faithfully.
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePath, PurePosixPath, PureWindowsPath
+
+from ._flatten import FlatPath, FlatPathError, FlatPathType, parse_flat_path
+from ._platform import Platform, flavor, resolve
+
+
+def to_flat_path(os_path: PurePath | str, *, platform: Platform | str | None = None) -> bytes:
+    """Encode an OS path into its PTH0 flattened byte string.
+
+    Absolute Windows paths store the drive letter without its colon as the first
+    component (matching NI's ``C:\\File`` example); absolute POSIX paths store the
+    components after the leading root. UNC, driveless and not-a-path forms are
+    refused because their flattened type codes are not documented.
+    """
+    target = flavor(resolve(platform))
+    pure = target(os_path) if isinstance(os_path, str) else target(*os_path.parts)
+    if pure.is_absolute():
+        return _encode_absolute(pure, target).to_bytes()
+    if pure.drive:
+        raise FlatPathError(f"drive-relative paths have no documented flattened form: {pure}")
+    return FlatPath(path_type=int(FlatPathType.RELATIVE), components=pure.parts).to_bytes()
+
+
+def from_flat_path(data: bytes, *, platform: Platform | str | None = None) -> PurePath:
+    """Decode PTH0 flattened bytes into a ``PurePath`` of the platform flavor.
+
+    Raises :class:`FlatPathError` for a path type with no documented PurePath
+    meaning, so an un-interpretable flattened path is reported rather than
+    silently reconstructed. Use :func:`lvpath.parse_flat_path` to inspect its raw
+    type and components instead.
+    """
+    flat = parse_flat_path(data)
+    target = flavor(resolve(platform))
+    if flat.is_relative:
+        return target(*flat.components) if flat.components else target(".")
+    if flat.is_absolute:
+        return _decode_absolute(flat, target)
+    raise FlatPathError(f"path type {flat.path_type} has no documented PurePath meaning")
+
+
+def _encode_absolute(pure: PurePath, target: type[PurePath]) -> FlatPath:
+    if target is PureWindowsPath:
+        drive = pure.drive
+        if drive.startswith("\\\\") or not drive:
+            raise FlatPathError(f"UNC and driveless absolute paths are not supported: {pure}")
+        components = (drive.rstrip(":"), *pure.parts[1:])
+    else:
+        components = pure.parts[1:]
+    return FlatPath(path_type=int(FlatPathType.ABSOLUTE), components=components)
+
+
+def _decode_absolute(flat: FlatPath, target: type[PurePath]) -> PurePath:
+    if target is PureWindowsPath:
+        if not flat.components:
+            raise FlatPathError("absolute Windows flattened path has no drive component")
+        drive, *rest = flat.components
+        return PureWindowsPath(f"{drive}:\\", *rest)
+    return PurePosixPath("/", *flat.components)

lvpath/_flatten.py

@@ -0,0 +1,139 @@
+"""The PTH0 binary flattened form of a LabVIEW path.
+
+LabVIEW's ``Flatten To String`` renders a Path value as a small big-endian
+container: the ASCII signature ``PTH0``, a u32 total length, a u16 path type, a
+u16 component count and then one length-prefixed (Pascal) string per component.
+The absolute path documented by NI as ``C:\\File`` flattens to::
+
+    50 54 48 30  00 00 00 0B  00 00  00 02  01 43  04 66 69 6C 65
+
+This module is a faithful codec for that container. It keeps the numeric path
+type as read so any flattened path round-trips byte for byte, and it never
+invents a meaning for a type code the NI documentation does not state.
+"""
+
+from __future__ import annotations
+
+import struct
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import IntEnum
+
+SIGNATURE: bytes = b"PTH0"
+"""The four ASCII bytes that open every flattened LabVIEW path."""
+
+_HEADER = struct.Struct(">4sIHH")  # signature, total length, path type, count
+
+
+class FlatPathType(IntEnum):
+    """The path type codes documented and verifiable from the NI example.
+
+    Only these two are stated by the public documentation. UNC and the empty /
+    not-a-path forms carry their own codes that the documentation does not give,
+    so they are deliberately absent here rather than guessed.
+    """
+
+    ABSOLUTE = 0
+    RELATIVE = 1
+
+
+class FlatPathError(ValueError):
+    """Raised when flattened path bytes are malformed or cannot be interpreted.
+
+    The message names the problem: a wrong signature, a truncated stream, a
+    declared length that disagrees with the body, a component that overruns the
+    buffer, or a path type with no documented meaning.
+    """
+
+
+@dataclass(frozen=True)
+class FlatPath:
+    """A parsed PTH0 flattened path: the raw path type and its components.
+
+    ``path_type`` is kept as the integer read from the stream, so a flattened
+    path with an un-interpreted type code still round-trips through
+    :meth:`to_bytes` byte for byte. ``components`` are the decoded Pascal-string
+    parts in order.
+    """
+
+    path_type: int
+    components: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not 0 <= self.path_type <= 0xFFFF:
+            raise FlatPathError(f"path type out of u16 range: {self.path_type}")
+        if len(self.components) > 0xFFFF:
+            raise FlatPathError(f"too many components to flatten: {len(self.components)}")
+
+    @property
+    def is_absolute(self) -> bool:
+        """Whether the path type is the documented absolute code (``0``)."""
+        return self.path_type == FlatPathType.ABSOLUTE
+
+    @property
+    def is_relative(self) -> bool:
+        """Whether the path type is the documented relative code (``1``)."""
+        return self.path_type == FlatPathType.RELATIVE
+
+    def to_bytes(self) -> bytes:
+        """Serialize this path to its PTH0 flattened byte string."""
+        body = bytearray(struct.pack(">HH", self.path_type, len(self.components)))
+        for component in self.components:
+            encoded = _encode_component(component)
+            body.append(len(encoded))
+            body += encoded
+        return struct.pack(">4sI", SIGNATURE, len(body)) + bytes(body)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> FlatPath:
+        """Parse a PTH0 flattened byte string into a :class:`FlatPath`."""
+        if len(data) < _HEADER.size:
+            raise FlatPathError(
+                f"flattened path is too short: {len(data)} bytes, need at least {_HEADER.size}"
+            )
+        signature, total, path_type, count = _HEADER.unpack_from(data)
+        if signature != SIGNATURE:
+            raise FlatPathError(f"bad signature: expected {SIGNATURE!r}, got {signature!r}")
+        body = data[8:]
+        if len(body) != total:
+            raise FlatPathError(f"declared length {total} does not match body of {len(body)} bytes")
+        components, offset = _read_components(body, count)
+        if offset != len(body):
+            raise FlatPathError(f"{len(body) - offset} trailing byte(s) after {count} component(s)")
+        return cls(path_type=path_type, components=tuple(components))
+
+
+def build_flat_path(path_type: int, components: Iterable[str]) -> bytes:
+    """Build PTH0 bytes from a numeric path type and its components."""
+    return FlatPath(path_type=path_type, components=tuple(components)).to_bytes()
+
+
+def parse_flat_path(data: bytes) -> FlatPath:
+    """Parse PTH0 bytes into a typed :class:`FlatPath` result."""
+    return FlatPath.from_bytes(data)
+
+
+def _encode_component(component: str) -> bytes:
+    try:
+        encoded = component.encode("ascii")
+    except UnicodeEncodeError as error:
+        raise FlatPathError(f"component is not ASCII: {component!r}") from error
+    if len(encoded) > 0xFF:
+        raise FlatPathError(f"component too long to flatten: {len(encoded)} bytes")
+    return encoded
+
+
+def _read_components(body: bytes, count: int) -> tuple[list[str], int]:
+    components: list[str] = []
+    offset = 4  # past the path type and count already read from the header
+    for index in range(count):
+        if offset >= len(body):
+            raise FlatPathError(f"stream ends before component {index} length byte")
+        length = body[offset]
+        offset += 1
+        end = offset + length
+        if end > len(body):
+            raise FlatPathError(f"component {index} of {length} bytes overruns the buffer")
+        components.append(body[offset:end].decode("ascii"))
+        offset = end
+    return components, offset

lvpath/_kinds.py

@@ -0,0 +1,21 @@
+"""The three LabVIEW path kinds and the not-a-path error."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class PathKind(Enum):
+    """Whether a LabVIEW path is absolute, relative or the not-a-path value."""
+
+    ABSOLUTE = "absolute"
+    RELATIVE = "relative"
+    NOT_A_PATH = "not_a_path"
+
+
+class NotAPathError(ValueError):
+    """Raised when a LabVIEW not-a-path value is converted to an OS path.
+
+    LabVIEW's ``<Not A Path>`` has no operating-system equivalent, so there is
+    no ``PurePath`` to return. Check :func:`lvpath.path_kind` first to avoid it.
+    """

lvpath/_platform.py

@@ -0,0 +1,36 @@
+"""Target platform selection and the matching pure-path flavor."""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from pathlib import PurePath, PurePosixPath, PureWindowsPath
+
+
+class Platform(Enum):
+    """A LabVIEW host platform whose path convention a string follows."""
+
+    WINDOWS = "windows"
+    POSIX = "posix"
+
+
+def current_platform() -> Platform:
+    """The platform convention of the operating system running this code."""
+    return Platform.WINDOWS if os.name == "nt" else Platform.POSIX
+
+
+def resolve(platform: Platform | str | None) -> Platform:
+    """Normalise the ``platform`` argument, defaulting to the current OS."""
+    if platform is None:
+        return current_platform()
+    if isinstance(platform, Platform):
+        return platform
+    try:
+        return Platform(platform.lower())
+    except ValueError:
+        raise ValueError(f"unknown platform: {platform!r}") from None
+
+
+def flavor(platform: Platform) -> type[PurePath]:
+    """The ``PurePath`` subclass that parses and renders ``platform`` paths."""
+    return PureWindowsPath if platform is Platform.WINDOWS else PurePosixPath

lvpath/_portable.py

@@ -0,0 +1,139 @@
+"""LabVIEW's portable path string form and native ``pathlib`` paths.
+
+When LabVIEW writes a path value into a configuration file or a project file it
+uses a platform-independent text form instead of the host's native one:
+
+- a Windows drive becomes a leading single-letter component, so ``C:\\DIR1\\DIR2``
+  is stored as ``/C/DIR1/DIR2`` and a bare drive ``C:\\`` as ``/C``;
+- a UNC share keeps a leading double slash, ``//server/share/dir``;
+- every separator is a forward slash, so relative paths read ``../builds/app``;
+- a POSIX absolute path (Linux, macOS) is already in this form;
+- the empty string is ``<Not A Path>``.
+
+This module converts that form to and from ``PureWindowsPath`` and
+``PurePosixPath``. Values with no faithful counterpart on the target platform
+(a POSIX absolute path read on Windows, a drive-relative ``C:file``, a rooted
+path with no drive, a ``\\\\?\\`` device path) raise :class:`PortablePathError`
+instead of being turned into a different path.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import PurePath, PurePosixPath, PureWindowsPath
+
+from ._kinds import NotAPathError
+from ._platform import Platform, flavor, resolve
+
+_PORTABLE_DRIVE = re.compile(r"^/([A-Za-z])(?:/(.*))?$", re.DOTALL)
+_MALFORMED_DRIVE = re.compile(r"^/[A-Za-z][:\\]")
+_DEVICE_PREFIXES = ("\\\\?\\", "\\\\.\\")
+
+
+class PortablePathError(ValueError):
+    """Raised when a path has no faithful equivalent in the requested form.
+
+    The message names the value and why it cannot be converted, for example a
+    POSIX absolute path read as a Windows path or a drive-relative ``C:file``.
+    """
+
+
+def from_portable_path(text: str, *, platform: Platform | str | None = None) -> PurePath:
+    """Parse LabVIEW's portable path string into a ``PurePath`` for ``platform``.
+
+    On Windows ``/C/DIR1/DIR2`` becomes ``PureWindowsPath('C:/DIR1/DIR2')``,
+    ``//server/share/dir`` becomes a UNC path and ``../a/b`` a relative path.
+    A value already written in native Windows form (``C:\\DIR1``) is accepted
+    as is. On POSIX the portable form is already native and is parsed directly.
+
+    Raises :class:`NotAPathError` for the empty ``<Not A Path>`` value and
+    :class:`PortablePathError` for a value with no Windows equivalent.
+    """
+    if text == "":
+        raise NotAPathError("LabVIEW not-a-path has no OS path")
+    if resolve(platform) is Platform.POSIX:
+        return PurePosixPath(text)
+    match = _PORTABLE_DRIVE.fullmatch(text)
+    if match:
+        drive, rest = match.groups()
+        return PureWindowsPath(f"{drive}:\\{rest or ''}")
+    if _MALFORMED_DRIVE.match(text):
+        raise PortablePathError(f"{text!r} has a malformed drive component, expected /C/...")
+    if text.startswith("/") and not text.startswith(("//", "/\\")):
+        raise PortablePathError(f"{text!r} is a POSIX absolute path with no Windows equivalent")
+    pure = PureWindowsPath(text)
+    _check_windows(pure, text)
+    return pure
+
+
+def to_portable_path(
+    os_path: PurePath | str | None, *, platform: Platform | str | None = None
+) -> str:
+    """Serialize a native path into LabVIEW's portable path string.
+
+    ``C:\\DIR1\\DIR2`` becomes ``/C/DIR1/DIR2``, ``\\\\server\\share\\dir``
+    becomes ``//server/share/dir`` and a relative path joins its parts with
+    forward slashes. ``None`` or ``""`` becomes the ``<Not A Path>`` value ``""``;
+    an empty ``PurePath`` is pathlib's current directory and becomes ``"."``.
+
+    A ``str`` is parsed with the flavor of ``platform`` (default: the running
+    operating system). A ``PurePath`` keeps its own flavor; when ``platform``
+    names the other flavor, only a relative path may be carried across.
+
+    Raises :class:`PortablePathError` for a Windows path with no portable form.
+    """
+    if os_path is None or os_path == "":
+        return ""
+    original = os_path if isinstance(os_path, str) else str(os_path)
+    pure = _as_pure(os_path, platform)
+    if isinstance(pure, PureWindowsPath):
+        return _windows_to_portable(pure, original)
+    return str(pure)
+
+
+def _as_pure(os_path: PurePath | str, platform: Platform | str | None) -> PurePath:
+    if isinstance(os_path, str):
+        return flavor(resolve(platform))(os_path)
+    if platform is None:
+        return os_path
+    target = flavor(resolve(platform))
+    if isinstance(os_path, target):
+        return os_path
+    if os_path.anchor:
+        raise PortablePathError(
+            f"cannot carry the anchored path {str(os_path)!r} to the {target.__name__} flavor"
+        )
+    if target is PureWindowsPath and any("\\" in part for part in os_path.parts):
+        raise PortablePathError(
+            f"a component of {str(os_path)!r} contains a backslash, a Windows separator"
+        )
+    return target(*os_path.parts)
+
+
+def _windows_to_portable(pure: PureWindowsPath, original: str) -> str:
+    _check_windows(pure, original)
+    if not pure.drive:
+        return "/".join(pure.parts) or "."
+    rest = "/".join(pure.parts[1:])
+    if pure.drive.startswith("\\\\"):
+        head = "//" + pure.drive[2:].replace("\\", "/")
+    else:
+        head = "/" + pure.drive[0]
+    return f"{head}/{rest}" if rest else head
+
+
+def _check_windows(pure: PureWindowsPath, original: str) -> None:
+    # The UNC and device forms are judged on the text itself: pathlib parses an
+    # incomplete UNC prefix differently across Python versions.
+    text = original.replace("/", "\\")
+    if text.startswith(_DEVICE_PREFIXES):
+        raise PortablePathError(f"{original!r} is a device path with no portable form")
+    if text.startswith("\\\\"):
+        server, _, rest = text[2:].partition("\\")
+        if not server or not rest.partition("\\")[0] or not pure.drive.startswith("\\\\"):
+            raise PortablePathError(f"{original!r} is not a //server/share UNC path")
+        return
+    if pure.drive and not pure.root:
+        raise PortablePathError(f"{original!r} is drive-relative and has no portable form")
+    if pure.root and not pure.drive:
+        raise PortablePathError(f"{original!r} is rooted without a drive or UNC share")

lvpath-0.3.1.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.5
+Name: lvpath
+Version: 0.3.1
+Summary: Convert LabVIEW path strings, the portable /C/DIR form of config and project files, and the flattened PTH0 form to and from native paths.
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/lvpath
+Project-URL: Issues, https://github.com/JaviLianes8/lvpath/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/lvpath/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
+Keywords: flatten,ini,labview,lvproj,ni,path,pathlib
+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
+
+# lvpath
+
+Convert between LabVIEW path strings and native OS paths: the host text form, the
+portable form LabVIEW writes into config and project files (`/C/DIR1/DIR2`), and the
+flattened `PTH0` binary form, with absolute, relative and not-a-path detection.
+
+## Install
+
+```
+pip install lvpath
+```
+
+## Usage
+
+```python
+from lvpath import to_os_path, to_lv_path, path_kind, PathKind, NotAPathError
+
+# Parse a LabVIEW path string into a PurePath of the chosen platform flavor.
+to_os_path("C:\\Users\\test\\data.txt", platform="windows")
+# PureWindowsPath('C:/Users/test/data.txt')
+
+to_os_path("/usr/local/bin", platform="posix")
+# PurePosixPath('/usr/local/bin')
+
+# Serialize an OS path back into a LabVIEW path string.
+to_lv_path("logs/run.txt", platform="windows")
+# 'logs\\run.txt'
+
+# A relative path object crosses platforms cleanly.
+win = to_os_path("reports\\q1\\data.txt", platform="windows")
+to_lv_path(win, platform="posix")
+# 'reports/q1/data.txt'
+
+# Detect the kind. The empty string is LabVIEW's <Not A Path> on every platform.
+path_kind("", platform="posix")  # PathKind.NOT_A_PATH
+path_kind("sub\\file", platform="windows")  # PathKind.RELATIVE
+path_kind("C:\\x", platform="windows")  # PathKind.ABSOLUTE
+
+# Not-a-path has no OS equivalent, so to_os_path refuses it.
+try:
+    to_os_path("", platform="posix")
+except NotAPathError:
+    ...
+
+# None (or "") serializes back to the not-a-path value.
+to_lv_path(None, platform="windows")  # ''
+```
+
+`platform` accepts `"windows"`, `"posix"`, a `Platform` member, or `None` to use
+the convention of the operating system running the code.
+
+## Portable form (config and project files)
+
+When LabVIEW writes a path value into a configuration (`.ini`) file or a project
+(`.lvproj`) file, it does not use the native Windows text. It uses a
+platform-independent form: the drive letter becomes a leading component, every
+separator is a forward slash, a UNC share keeps a leading double slash and the empty
+string is `<Not A Path>`. `C:\DIR1\DIR2` is stored as `/C/DIR1/DIR2`.
+
+```python
+from lvpath import from_portable_path, to_portable_path, PortablePathError
+
+# Read a stored value into a native path.
+from_portable_path("/C/Program Files (x86)/Arduino", platform="windows")
+# PureWindowsPath('C:/Program Files (x86)/Arduino')
+from_portable_path("//server/share/dir", platform="windows")
+# PureWindowsPath('//server/share/dir')
+from_portable_path("../builds/Main Application", platform="windows")
+# PureWindowsPath('../builds/Main Application')
+from_portable_path("/home/lvuser/natinst/bin", platform="posix")
+# PurePosixPath('/home/lvuser/natinst/bin')
+
+# Write a native path back in the stored form.
+to_portable_path("C:\\DIR1\\DIR2", platform="windows")  # '/C/DIR1/DIR2'
+to_portable_path("D:\\", platform="windows")  # '/D'
+to_portable_path("\\\\server\\share\\dir", platform="windows")  # '//server/share/dir'
+to_portable_path(None)  # '' (<Not A Path>)
+
+# Values with no faithful counterpart are refused, never rewritten into another path.
+try:
+    from_portable_path("/home/lvuser", platform="windows")
+except PortablePathError:
+    ...
+```
+
+The rules below are checked against path values in files shipped with LabVIEW 2026
+(`tests/fixtures/labview2026_paths.json` records each value with the file and setting it
+was found in; the NI files themselves are not copied).
+No shipped file holds a bare drive or a UNC value, so the `/D` and `//server/share/dir`
+rows are covered by synthetic tests that follow the same convention:
+
+| Stored value                     | Windows                        | POSIX                            |
+| -------------------------------- | ------------------------------ | -------------------------------- |
+| `/C/Program Files (x86)/Arduino` | `C:\Program Files (x86)\Arduino` | `/C/Program Files (x86)/Arduino` |
+| `/c/ni-rt/startup`               | `c:\ni-rt\startup`             | `/c/ni-rt/startup`               |
+| `/D`                             | `D:\`                          | `/D`                             |
+| `//server/share/dir`             | `\\server\share\dir`           | `//server/share/dir`             |
+| `../builds/Main Application`     | `..\builds\Main Application`   | `../builds/Main Application`     |
+| `/home/lvuser/natinst/bin`       | `PortablePathError`            | `/home/lvuser/natinst/bin`       |
+| empty                            | `NotAPathError`                | `NotAPathError`                  |
+
+- The drive letter keeps its case, so a value in normal form (no trailing slash,
+  repeated separator or `.` component, as LabVIEW writes it) round-trips exactly.
+- A value already in native Windows form (`C:\NI Installers`), which some NI files
+  store, is accepted as is when reading on Windows.
+- On POSIX the stored form is already native and is parsed unchanged. A one-letter
+  first directory is therefore ambiguous: `/C/x` reads as the drive `C:` on Windows
+  and as the directory `/C/x` on POSIX. Pick `platform` for the system that will
+  use the path.
+- `PortablePathError` is raised for a POSIX absolute path read as Windows, a
+  drive-relative `C:file`, a rooted Windows path without a drive (`\dir`), a UNC
+  path without a share and a `\\?\` device path.
+- A `str` is parsed with the flavor of `platform`; a `PurePath` keeps its own
+  flavor, and only a relative one may be carried to the other flavor.
+- Text is normalised by `pathlib`: repeated separators collapse, a trailing slash and
+  `.` components are dropped, so `/C/x/` writes back as `/C/x`. A backslash inside a
+  value read on Windows is a separator (`/C/x\y` reads as `C:\x\y`).
+- The sibling `lvconfig` library (0.3.0 and later) gives the same results on drive,
+  UNC and relative values in normal form, and refuses the same values lvpath refuses
+  (`C:file`, `D:`, `\dir`, `//server`, a POSIX absolute path on Windows). The one
+  difference left: lvpath normalises text through `pathlib`, where lvconfig only
+  swaps separators.
+
+## Flattened form
+
+`Flatten To String` renders a LabVIEW Path as a small big-endian binary
+container: the ASCII signature `PTH0`, a `u32` total length, a `u16` path type, a
+`u16` component count and then one length-prefixed (Pascal) string per component.
+NI documents the absolute path `C:\File` flattening to the bytes
+`50 54 48 30  00 00 00 0B  00 00  00 02  01 43  04 66 69 6C 65`.
+
+```python
+from lvpath import FlatPath, parse_flat_path, from_flat_path, to_flat_path
+
+golden = bytes.fromhex("505448300000000b0000000201430466696c65")
+
+# Parse the flattened bytes into a typed result.
+parse_flat_path(golden)
+# FlatPath(path_type=0, components=('C', 'file'))
+
+# Round-trips byte for byte.
+parse_flat_path(golden).to_bytes() == golden  # True
+
+# Bridge to and from pathlib on a chosen platform flavor.
+from_flat_path(golden, platform="windows")  # PureWindowsPath('C:/file')
+to_flat_path("C:/file", platform="windows")  # the golden bytes
+to_flat_path("/usr/local/bin", platform="posix")  # a POSIX absolute flattened path
+```
+
+Only the two documented path type codes are interpreted: `0` absolute and `1`
+relative, exposed as `FlatPathType`. UNC and empty / not-a-path forms carry type
+codes the public NI documentation does not state, so they are not guessed: the
+low-level codec still round-trips their raw bytes faithfully through `FlatPath`,
+while `to_flat_path` and `from_flat_path` refuse an un-interpretable type code
+with a clear `FlatPathError` instead of inventing a meaning.
+
+## Command line
+
+Installing the package provides an `lvpath` command for the portable string form and
+the flattened form.
+
+```
+# A stored LabVIEW path string to a native path, and back.
+lvpath to-native --platform windows "/C/Program Files (x86)/Arduino"
+# C:\Program Files (x86)\Arduino
+lvpath to-labview --platform windows "C:\DIR1\DIR2"
+# /C/DIR1/DIR2
+
+# Decode the NI C:\File flattened example into a path.
+lvpath decode --platform windows 505448300000000b0000000201430466696c65
+# C:\file
+
+# Encode a path into its flattened hex form.
+lvpath encode --platform windows "C:\file"
+# 505448300000000b0000000201430466696c65
+
+lvpath --version
+```
+
+`lvpath decode` accepts hex with or without spaces. `lvpath to-labview ""` prints an
+empty line, the `<Not A Path>` value, while `lvpath to-native ""` is an error. Errors
+are written to standard error and the command exits with status 1. Output is UTF-8.
+A value that starts with `-` goes after `--`. Under Git Bash on Windows, set
+`MSYS_NO_PATHCONV=1` so the shell passes POSIX-looking arguments such as `/C/x`
+unchanged. Run `lvpath --help` for the full usage.
+
+## Covered conventions
+
+LabVIEW's `Path To String` and `String To Path` render and parse a path in the
+standard textual form of a host platform. `to_os_path`, `to_lv_path` and `path_kind`
+model that native textual form (so `to_os_path("/C/foo", platform="windows")` is the
+rooted Windows path `\C\foo`; read stored values with `from_portable_path` instead):
+
+- **Separators:** `\` on Windows, `/` on POSIX. Forward slashes are also accepted
+  when parsing a Windows path, matching LabVIEW's lenient reader.
+- **Absolute, Windows:** drive-letter paths (`C:\dir\file`) and UNC paths
+  (`\\server\share\dir`).
+- **Absolute, POSIX:** a leading `/` (modern LabVIEW on macOS and Linux).
+- **Relative:** any other non-empty string, including up-level (`..\up`) and
+  drive-relative (`C:file`) forms.
+- **Not-a-path:** the empty string, LabVIEW's `<Not A Path>` value, on every
+  platform. `None` serializes back to it.
+
+### What it does not do
+
+- It does not touch the filesystem, resolve symbolic links, or normalise `.`/`..`
+  beyond what `pathlib` does.
+- It does not handle classic Mac OS colon-separated paths (pre-OS X). Modern
+  LabVIEW on macOS uses POSIX `/`.
+- The flattened codec interprets only the documented absolute and relative path
+  type codes. It does not guess the undocumented UNC or not-a-path type codes, and
+  it does not touch the textual-form behaviour above.
+- It does not expand LabVIEW symbolic path prefixes such as `<vilib>` or
+  `<instrlib>`, and it does not resolve a relative stored value against the file
+  it came from.
+
+## Why
+
+LabVIEW uses two text forms for a path: the native form of its host platform for
+`Path To String` / `String To Path`, and a platform-independent form (`/C/DIR1/DIR2`
+for `C:\DIR1\DIR2`) when it writes a path into configuration and project files. Read
+with plain string handling, the stored form names the wrong file on Windows, and a
+native string only means something together with the platform convention it was
+written in, so round-tripping LabVIEW path data in Python needs explicit,
+platform-aware handling.
+
+The standard library already does most of this. `pathlib`'s `PureWindowsPath` and
+`PurePosixPath` are built to manipulate foreign-platform paths with no I/O, so they
+cover the bulk of the separator and anchor handling on their own, and this library is
+a thin wrapper over them rather than a reimplementation. What they do not know is the
+genuinely LabVIEW-specific residue: the stored drive and UNC form (`/C/foo` to
+`C:\foo` and back, through `from_portable_path` and `to_portable_path`), the empty
+string standing for `<Not A Path>`, and LabVIEW's exact serialization rules. No PyPI package targets those conventions. `lvpath` adds exactly
+that layer on top of `pathlib`, with a small, typed, zero-dependency surface.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

lvpath-0.3.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+lvpath/__init__.py,sha256=vu-gM9D1hAdkm8ne5gN7766ZQub-LSceU63gJw3Mg58,1391
+lvpath/_cli.py,sha256=dXCnsBD6YCIEbX7qBOExAFSUzjoCs2KUl5bBV6hbqms,4952
+lvpath/_convert.py,sha256=DyxgMwQYMIoxrq_oSTB9HWM8Amcbjm076WO_cbAolmw,1946
+lvpath/_flatbridge.py,sha256=gDnFhyE0fcSaDPYTyLGraGUU94PaNRkt5YppQ2OqJ7o,3155
+lvpath/_flatten.py,sha256=t87NqCOhkVLbdyIUWL5JX2g-M4dbyVrwjJzPa_0PsSM,5496
+lvpath/_kinds.py,sha256=-EUYDTFl8K2bjouBGMwFF6QGK91J3-sqmnaB2VX15V4,585
+lvpath/_platform.py,sha256=QudH7SeeHYMVVNf35wEfo6F9Ha0FxBcRt6rLfqA9jdE,1135
+lvpath/_portable.py,sha256=hHeYICGEXnhO0nBQ_KOYzW82VrGGqOYf9HT2U3L5a9s,6074
+lvpath/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lvpath-0.3.1.dist-info/METADATA,sha256=L6EcoRRWnV7HQjrh-UrVFDFUv85NiQ-R8W7KfkzL0og,12678
+lvpath-0.3.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lvpath-0.3.1.dist-info/entry_points.txt,sha256=G1ZaJMn30SluLurjE2tZROWJ1tK4TcDtss1SGDfQkKA,44
+lvpath-0.3.1.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+lvpath-0.3.1.dist-info/RECORD,,

lvpath-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

lvpath-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lvpath = lvpath._cli:main

lvpath-0.3.1.dist-info/licenses/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.