lvpath 0.3.1__tar.gz → 1.0.0__tar.gz

{lvpath-0.3.1 → lvpath-1.0.0}/.gitignore

@@ -10,3 +10,5 @@ dist/
 .ruff_cache/
 .coverage
 htmlcov/
+tests/fixtures/sources/*
+!tests/fixtures/sources/MANIFEST.json

lvpath-1.0.0/CHANGELOG.md

@@ -0,0 +1,140 @@
+# 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]
+
+## [1.0.0] - 2026-10-15
+
+The public surface is now stable: the seventeen names of 0.3.1 (three of them exception classes) with the same
+parameters and defaults (some annotations widened, listed below), the `lvpath` command and `python -m lvpath`.
+The flattened form is checked against NI's published example and against the
+349,566 flattened paths LabVIEW 2026 stores in its own installed files.
+
+### Changed
+
+- An empty flattened component now decodes as `..` and `..` encodes as an empty
+  component, which is how LabVIEW 2026 stores relative links (21,765 links in its own
+  files resolve that way). 0.3.1 dropped the empty components, so
+  `('', '', 'NI_MDF.lvlib')` decoded as `NI_MDF.lvlib`, and wrote `..` as two dots.
+- `<Not A Path>` in the flattened form is path type 2 with no component, the code
+  LabVIEW's `cintools/extcode.h` gives it and the record LabVIEW 2026 stores in
+  `resource/labview.rsc`. `to_flat_path("")` and `to_flat_path(None)` now write it (0.3.1
+  wrote `""` as an empty relative path, which decodes as `.`, and raised
+  `AttributeError` for `None`), and `from_flat_path` raises `NotAPathError` for it (0.3.1:
+  `FlatPathError`). `FlatPathType` gains `NOT_A_PATH` (2) and `UNC` (3); a UNC flattened
+  path is still refused with `FlatPathError`.
+- `from_flat_path` refuses with `FlatPathError` what 0.3.1 misread: a symbolic
+  `<vilib>`-style first component of an absolute path, a first Windows component that is
+  not one drive letter (0.3.1 produced `usr:\lib`), literal `.` and `..` components, and
+  components holding `/` (or `\` or `:` on Windows).
+- `to_flat_path` refuses a POSIX path starting with `//` (0.3.1 dropped one slash) and a
+  rooted Windows path without a drive such as `\usr\x` (0.3.1 wrote it as a relative path
+  whose first component was a backslash).
+- One flavor rule for `PurePath` arguments in every function: a `PurePath` keeps its own
+  flavor unless `platform` names the other one, and then only a relative path may cross,
+  with no backslash or colon inside a component on the way to Windows; anything else
+  raises `PortablePathError` (`FlatPathError` in `to_flat_path`). 0.3.1 re-read a
+  `PurePath` with the flavor of `platform` (or of the running system) in `to_lv_path`,
+  `to_flat_path`, `to_os_path`, `path_kind` and, on POSIX, `from_portable_path`, producing a different path for anchored
+  ones, and `from_portable_path` raised `TypeError` for a `PurePath` on Windows. The
+  annotations of `to_os_path`, `path_kind` and `from_portable_path` now include
+  `PurePath`, and that of `to_flat_path` includes `None`.
+- `platform` is checked before anything else in every function: an unknown name raises
+  `ValueError` and a value that is not a `str`, `Platform` or `None` raises `TypeError`
+  (0.3.1 raised `AttributeError`), even when the path is empty or the bytes are malformed.
+  In 0.3.1, `path_kind("", platform="bogus")` returned `NOT_A_PATH`, `to_lv_path` and
+  `to_portable_path` returned `""`, `to_os_path` and `from_portable_path` raised
+  `NotAPathError` and `from_flat_path` raised `FlatPathError` for bad bytes.
+- Arguments of the wrong type raise `TypeError` with a short message. 0.3.1 returned
+  `'5'` for `to_portable_path(5)` and `"b'x'"` for `to_portable_path(b"x")`, raised
+  `AttributeError` for `to_lv_path(5)` and `to_flat_path(5)`, and raised `FlatPathError`
+  for `parse_flat_path` given a short `str`.
+- `FlatPath` checks its fields when built: a `bool` or non-integer path type and a
+  non-`str` component raise `TypeError` (0.3.1 accepted `FlatPath(0, "ab")`); a non-ASCII
+  or over-long component raises `FlatPathError` at once (0.3.1 raised it later, in
+  `to_bytes`). The path type is stored as a plain `int` (0.3.1 kept an `IntEnum` member as
+  given) and the components as a tuple. `build_flat_path` refuses a `str` as its
+  components with `TypeError` (0.3.1 split it into one-character components). A pickle
+  written by 0.3.1 loads with its fields normalised the same way.
+- Non-ASCII flattened bytes raise `FlatPathError` instead of `UnicodeDecodeError`.
+  `parse_flat_path`, `FlatPath.from_bytes` and `from_flat_path` read the raw bytes of any
+  object with the buffer protocol (`bytes`, `bytearray`, `memoryview`, `array`, `mmap`)
+  and are typed for `bytes | bytearray | memoryview`. 0.3.1 read `bytes` and
+  `bytearray` only: a `memoryview` or `array` holding a component raised
+  `AttributeError`, and a wide `array` was measured in items.
+- Error messages quote at most 40 characters of a value and several are reworded; the
+  exception types are unchanged except where listed here. The public classes
+  (`FlatPath`, `FlatPathType`, `PathKind`, `Platform` and the three exceptions) report
+  their module as `lvpath`, so pickles name `lvpath.<class>`; pickles made by 0.3.1 still
+  load.
+- Command line: a usage mistake still exits 2, now with lines of at most 200 characters;
+  a refused value prints one bounded line and exits 1; a closed output pipe exits 1
+  quietly; invalid hex no longer echoes the parser's detail; `lvpath encode ''` prints the
+  not-a-path bytes and `lvpath decode` of them is refused. A POSIX argument that is not
+  valid UTF-8 is written back as its original bytes (0.3.1 stopped with a
+  `UnicodeEncodeError` traceback); a lone surrogate UTF-8 cannot write at all (possible
+  in Windows arguments) is refused in one line with status 1; a missing standard stream
+  no longer raises.
+- A `str` subclass is read through its plain text: an overridden `__eq__` or `__len__`
+  no longer changes a result or slips past the component limits.
+
+### Added
+
+- `python -m lvpath`.
+- `FlatPathType.NOT_A_PATH` and `FlatPathType.UNC`.
+- `GUIDE.md` with the rules, the errors table, the ground truth and upgrade notes.
+- Docstring examples for every public name, run as doctests.
+
+## [0.3.1]
+
+- The LabVIEW 2026 path fixture no longer carries source lines copied from NI files: each
+  row keeps only the path value, its expected renderings, and where it was found (file and
+  setting). The sdist is limited to the package, the tests and the docs.
+
+## [0.3.0]
+
+- Added the portable path form LabVIEW writes into configuration and project
+  files. `from_portable_path` reads `/C/DIR1/DIR2` as `C:\DIR1\DIR2`,
+  `//server/share/dir` as a UNC path and `../a/b` as a relative path;
+  `to_portable_path` writes them back, keeping the drive letter case. The empty value is `<Not A Path>`.
+- `PortablePathError` reports a value with no faithful counterpart instead of
+  rewriting it into another path: a POSIX absolute path read as Windows, a
+  drive-relative `C:file`, a rooted Windows path without a drive, a UNC path
+  without a share and a `\\?\` device path.
+- The `lvpath` command line gains `to-native` and `to-labview`, and its help lists
+  runnable examples for every subcommand.
+- The test suite carries a verbatim excerpt of path values from files shipped with
+  LabVIEW 2026 and checks every value in both directions and through a round trip.
+- The README no longer implies that `to_os_path` translates `/C/foo`; it documents
+  the portable form, its rules and its one ambiguity.
+
+## [0.2.0]
+
+- Added the binary flattened path form (`Flatten To String` `PTH0`). `FlatPath` is
+  a typed, frozen result with `to_bytes` and `from_bytes`; `parse_flat_path` and
+  `build_flat_path` are the codec entry points. The NI `C:\File` example round-trips
+  byte for byte in both directions.
+- `to_flat_path` and `from_flat_path` bridge the flattened form to and from
+  `pathlib.PurePath` on a chosen platform flavor.
+- `FlatPathType` exposes the two documented path type codes (absolute `0`, relative
+  `1`). UNC and not-a-path codes are undocumented, so they are not guessed: the
+  codec still round-trips their raw bytes, while the PurePath bridge refuses an
+  un-interpretable type code with `FlatPathError`.
+- Added an `lvpath` command line with `decode` and `encode` subcommands and
+  `--version`.
+
+## [0.1.0]
+
+- First release.
+- `to_os_path` parses a LabVIEW path string into a `PurePath` of the Windows or
+  POSIX flavor; `to_lv_path` serializes an OS path back into a LabVIEW string.
+- `path_kind` and `PathKind` detect absolute, relative and not-a-path values;
+  the empty string is the not-a-path value on every platform.
+- `NotAPathError` is raised when the not-a-path value is converted to an OS path.
+- Covers the textual `Path To String` / `String To Path` conventions: Windows
+  drive and UNC anchors, POSIX roots, lenient forward slashes, and clean
+  cross-platform conversion of relative path objects. Classic Mac OS colon paths
+  and the binary flatten path type are out of scope.

{lvpath-0.3.1 → lvpath-1.0.0}/CONTRIBUTING.md

@@ -1,19 +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/lvpath/__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.
+# 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/lvpath/__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.

lvpath-1.0.0/GUIDE.md

@@ -0,0 +1,290 @@
+# lvpath guide
+
+LabVIEW keeps a path in three forms. lvpath converts each of them to and from
+`pathlib.PurePath` without touching the file system:
+
+| Form | Where LabVIEW uses it | lvpath |
+| --- | --- | --- |
+| Portable text, `/C/DIR1/DIR2` | path values in `.ini` and `.lvproj` files | `from_portable_path`, `to_portable_path` |
+| Native text, `C:\DIR1\DIR2` | `Path To String`, `String To Path` | `to_os_path`, `to_lv_path`, `path_kind` |
+| Flattened bytes, `PTH0...` | `Flatten To String`, VI files, datalogs | `from_flat_path`, `to_flat_path`, `FlatPath` |
+
+## The platform argument
+
+Every conversion takes `platform`: `"windows"` or `"posix"` in any letter case, a
+`Platform` member, or `None` for the system running the code. A `str` argument is
+parsed with that flavor. A `PurePath` argument keeps its own flavor; when `platform`
+names the other flavor, only a relative path may cross, and a component holding a
+backslash or a colon may not cross to Windows.
+
+```pycon
+>>> from pathlib import PurePosixPath, PureWindowsPath
+>>> from lvpath import Platform, to_lv_path
+>>> to_lv_path(PureWindowsPath("reports\\q1.txt"), platform="posix")
+'reports/q1.txt'
+>>> to_lv_path(PureWindowsPath("C:/x"), platform=Platform.POSIX)
+Traceback (most recent call last):
+...
+lvpath.PortablePathError: cannot carry the anchored path 'C:\\x' to the PurePosixPath flavor
+
+```
+
+## Portable text form
+
+When LabVIEW writes a path value into a configuration or project file it uses a
+platform-independent text: a Windows drive becomes a leading one-letter component, every
+separator is `/`, a UNC share keeps its leading `//` and the empty string is
+`<Not A Path>`.
+
+| Stored value | `platform="windows"` | `platform="posix"` |
+| --- | --- | --- |
+| `/C/Program Files (x86)/Arduino` | `C:\Program Files (x86)\Arduino` | unchanged |
+| `/c/ni-rt/startup` | `c:\ni-rt\startup` | unchanged |
+| `/D` | `D:\` | unchanged |
+| `//server/share/dir` | `\\server\share\dir` | unchanged |
+| `../builds/Main Application` | `..\builds\Main Application` | unchanged |
+| `/home/lvuser/natinst/bin` | `PortablePathError` | unchanged |
+| empty | `NotAPathError` | `NotAPathError` |
+
+```pycon
+>>> from lvpath import from_portable_path, to_portable_path
+>>> from_portable_path("/D", platform="windows")
+PureWindowsPath('D:/')
+>>> to_portable_path("\\\\server\\share\\dir", platform="windows")
+'//server/share/dir'
+>>> to_portable_path("C:file", platform="windows")
+Traceback (most recent call last):
+...
+lvpath.PortablePathError: 'C:file' is drive-relative and has no portable form
+
+```
+
+- The drive letter keeps its case, so a value in the normal form LabVIEW writes (no
+  trailing slash, repeated separator or `.` part) 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, so `/C/x` is a
+  drive on Windows and a directory on POSIX. Pick `platform` for the system that will
+  use the path.
+- Refused with `PortablePathError`: a POSIX absolute path read as Windows, a malformed
+  drive (`/C:/x`), a drive-relative `C:file`, a rooted path without a drive (`\dir`),
+  a UNC path without a share and the `\\?\` and `\\.\` device forms.
+- `pathlib` normalises the text: repeated separators collapse, a trailing slash and
+  `.` parts are dropped, and a backslash read on Windows is a separator.
+- An empty `PurePath` is pathlib's current directory and writes as `"."`; `None` and
+  `""` write as `""`.
+
+The table rows are checked against values found in files shipped with LabVIEW 2026
+(`tests/fixtures/labview2026_paths.json` records each value with its file and setting,
+not the file text). No shipped file holds a bare drive or a UNC value; those rows are
+covered by tests written by hand that follow the same convention.
+
+## Native text form
+
+`to_os_path` and `path_kind` read the text of a host platform, `to_lv_path` writes it.
+On Windows forward slashes are accepted, and only a drive with a root or a UNC share is
+absolute, so `C:file` and `\dir` count as relative, as `pathlib` decides.
+
+```pycon
+>>> from lvpath import NotAPathError, PathKind, path_kind, to_os_path
+>>> path_kind("C:file", platform="windows")
+<PathKind.RELATIVE: 'relative'>
+>>> to_os_path("/C/foo", platform="windows")
+PureWindowsPath('/C/foo')
+>>> try:
+...     to_os_path("", platform="posix")
+... except NotAPathError as error:
+...     print(error)
+LabVIEW not-a-path has no OS path
+
+```
+
+Read stored values with `from_portable_path`: `to_os_path` keeps `/C/foo` as the rooted
+Windows path `\C\foo`.
+
+## Flattened form
+
+`Flatten To String` writes a path as `PTH0`, a u32 byte count of the rest, a u16 path
+type, a u16 component count and one length-prefixed ASCII string per component, all
+big-endian. `FlatPath`, `parse_flat_path` and `build_flat_path` read and write that
+container exactly and keep any path type as a number.
+
+```pycon
+>>> from lvpath import FlatPath, build_flat_path, from_flat_path, parse_flat_path, to_flat_path
+>>> parse_flat_path(build_flat_path(1, ["", "", "NI_MDF.lvlib"]))
+FlatPath(path_type=1, components=('', '', 'NI_MDF.lvlib'))
+>>> from_flat_path(build_flat_path(1, ["", "", "NI_MDF.lvlib"]), platform="windows")
+PureWindowsPath('../../NI_MDF.lvlib')
+>>> from_flat_path(build_flat_path(0, []), platform="posix")
+PurePosixPath('/')
+>>> from_flat_path(build_flat_path(0, ["<vilib>", "Utility"]), platform="posix")
+Traceback (most recent call last):
+...
+lvpath.FlatPathError: symbolic path prefix '<vilib>' has no PurePath meaning
+
+```
+
+The path type codes are those LabVIEW's `cintools/extcode.h` lists in order (`fAbsPath`,
+`fRelPath`, `fNotAPath`, `fUNCPath`), exposed as `FlatPathType`, and
+`from_flat_path` and `to_flat_path` interpret three of them:
+
+- `0`, absolute (`ABSOLUTE`). On Windows the first component is the drive letter
+  without its colon; on POSIX the components follow the root, and no component at all
+  is `/`. That empty absolute path (LabVIEW's empty path, common in VI files) has no
+  Windows `PurePath` and raises `FlatPathError` there.
+- `1`, relative (`RELATIVE`). No component at all is `.`.
+- In both, an empty component means one level up, `..` in text.
+- `2`, `<Not A Path>` (`NOT_A_PATH`), with no component. `to_flat_path("")` and
+  `to_flat_path(None)` write it; `from_flat_path` raises `NotAPathError` for it.
+
+Everything else raises `FlatPathError` in the bridge: `3`, UNC (`UNC`; no UNC record
+exists in the LabVIEW install to confirm its component layout, so it is not guessed),
+any other code, a symbolic first component such as `<vilib>`, a first Windows component
+that is not one letter, a literal `.` or `..` component, a component holding `/` (or `\`
+or `:` on Windows), UNC and driveless rooted Windows paths, drive-relative paths and
+POSIX paths starting with `//`. Components are ASCII, at most 255 characters, and at
+most 65535 of them.
+
+### Ground truth for the flattened form
+
+- NI's flattened-data page gives `C:\File` as
+  `5054 4830 0000 000B 0000 0002 0143 0466 696C 65` and names type `0` only. Its bytes
+  spell `file` in lower case. `tests/test_sources_truth.py` reads the example from a
+  copy fetched by `scripts/fetch_sources.py` (not committed; `MANIFEST.json` keeps the
+  URL, date and SHA-256).
+- `scripts/scan_labview_paths.py` walked a LabVIEW 2026 install on 2026-10-15, skipping
+  files over 50 MB (`LabVIEW.exe`, `resource/libcef.dll` and the object cache
+  `VIObjCache/26.0.0r0/objFileDB.vidb`, whose records include split, corrupted
+  fragments), and found
+  321,686 records of type `0`, 27,879 of type `1` and one of type `2`. Of the 24,024
+  relative links that start with empty components, 21,765 name an existing file when
+  each empty component is read as one level up from the file holding the link; no
+  record holds a literal `..`. The one type `2` record, `PTH0 00000004 0002 0000`, is
+  exactly what `to_flat_path("")` writes. Eleven chosen records, with file and offset,
+  are in `tests/fixtures/labview2026_flat.json`.
+- `cintools/extcode.h` of LabVIEW 2026 lists the path type codes in order: absolute,
+  relative, not-a-path, UNC.
+
+## Errors
+
+| Exception | Base | Raised for |
+| --- | --- | --- |
+| `NotAPathError` | `ValueError` | `<Not A Path>` (an empty string, or flattened type `2`) read as an OS path |
+| `PortablePathError` | `ValueError` | a value with no faithful counterpart in the portable or native form |
+| `FlatPathError` | `ValueError` | malformed `PTH0` bytes, bad components, a path the bridge cannot represent |
+| `ValueError` | | an unknown `platform` name |
+| `TypeError` | | an argument of the wrong type (a path that is not `str` or `PurePath`, bytes that are not bytes-like, a non-integer path type) |
+
+A message quotes at most 40 characters of any value and states the full length of a
+longer one. The public classes report their module as `lvpath`.
+
+```pycon
+>>> from lvpath import FlatPathError, PortablePathError
+>>> try:
+...     to_portable_path("C:" + "x" * 1000, platform="windows")
+... except PortablePathError as error:
+...     print(error)
+'C:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' (first 40 of 1002 characters) is drive-relative and has no portable form
+>>> issubclass(FlatPathError, ValueError)
+True
+
+```
+
+## Command line
+
+```console
+$ lvpath to-native --platform windows //server/share/dir
+\\server\share\dir
+$ lvpath to-labview --platform posix ''
+
+$ lvpath decode --platform posix '50544830 00000007 0001 0002 00 0161'
+../a
+$ lvpath to-native --platform windows /home/lvuser
+lvpath: '/home/lvuser' is a POSIX absolute path with no Windows equivalent
+```
+
+Output is UTF-8, and a POSIX argument that is not valid UTF-8 is written back as its
+original bytes. A refused value prints one line on standard error and exits with
+status 1; a usage mistake prints the usage and one line and exits with status 2; a
+closed output pipe exits with status 1 quietly. A value starting with `-` goes after
+`--`. Under Git Bash on Windows set `MSYS_NO_PATHCONV=1` so `/C/x` reaches lvpath
+unchanged.
+
+## Upgrading from 0.3
+
+The public names and parameters are the same; `python -m lvpath`,
+`FlatPathType.NOT_A_PATH` and `FlatPathType.UNC` are new. Behaviour that changed (the
+same list as CHANGELOG 1.0.0):
+
+- An empty flattened component now decodes as `..` and `..` encodes as an empty
+  component, which is how LabVIEW 2026 stores relative links (21,765 links in its own
+  files resolve that way). 0.3.1 dropped the empty components, so
+  `('', '', 'NI_MDF.lvlib')` decoded as `NI_MDF.lvlib`, and wrote `..` as two dots.
+- `<Not A Path>` in the flattened form is path type 2 with no component, the code
+  LabVIEW's `cintools/extcode.h` gives it and the record LabVIEW 2026 stores in
+  `resource/labview.rsc`. `to_flat_path("")` and `to_flat_path(None)` now write it (0.3.1
+  wrote `""` as an empty relative path, which decodes as `.`, and raised
+  `AttributeError` for `None`), and `from_flat_path` raises `NotAPathError` for it (0.3.1:
+  `FlatPathError`). `FlatPathType` gains `NOT_A_PATH` (2) and `UNC` (3); a UNC flattened
+  path is still refused with `FlatPathError`.
+- `from_flat_path` refuses with `FlatPathError` what 0.3.1 misread: a symbolic
+  `<vilib>`-style first component of an absolute path, a first Windows component that is
+  not one drive letter (0.3.1 produced `usr:\lib`), literal `.` and `..` components, and
+  components holding `/` (or `\` or `:` on Windows).
+- `to_flat_path` refuses a POSIX path starting with `//` (0.3.1 dropped one slash) and a
+  rooted Windows path without a drive such as `\usr\x` (0.3.1 wrote it as a relative path
+  whose first component was a backslash).
+- One flavor rule for `PurePath` arguments in every function: a `PurePath` keeps its own
+  flavor unless `platform` names the other one, and then only a relative path may cross,
+  with no backslash or colon inside a component on the way to Windows; anything else
+  raises `PortablePathError` (`FlatPathError` in `to_flat_path`). 0.3.1 re-read a
+  `PurePath` with the flavor of `platform` (or of the running system) in `to_lv_path`,
+  `to_flat_path`, `to_os_path`, `path_kind` and, on POSIX, `from_portable_path`, producing a different path for anchored
+  ones, and `from_portable_path` raised `TypeError` for a `PurePath` on Windows. The
+  annotations of `to_os_path`, `path_kind` and `from_portable_path` now include
+  `PurePath`, and that of `to_flat_path` includes `None`.
+- `platform` is checked before anything else in every function: an unknown name raises
+  `ValueError` and a value that is not a `str`, `Platform` or `None` raises `TypeError`
+  (0.3.1 raised `AttributeError`), even when the path is empty or the bytes are malformed.
+  In 0.3.1, `path_kind("", platform="bogus")` returned `NOT_A_PATH`, `to_lv_path` and
+  `to_portable_path` returned `""`, `to_os_path` and `from_portable_path` raised
+  `NotAPathError` and `from_flat_path` raised `FlatPathError` for bad bytes.
+- Arguments of the wrong type raise `TypeError` with a short message. 0.3.1 returned
+  `'5'` for `to_portable_path(5)` and `"b'x'"` for `to_portable_path(b"x")`, raised
+  `AttributeError` for `to_lv_path(5)` and `to_flat_path(5)`, and raised `FlatPathError`
+  for `parse_flat_path` given a short `str`.
+- `FlatPath` checks its fields when built: a `bool` or non-integer path type and a
+  non-`str` component raise `TypeError` (0.3.1 accepted `FlatPath(0, "ab")`); a non-ASCII
+  or over-long component raises `FlatPathError` at once (0.3.1 raised it later, in
+  `to_bytes`). The path type is stored as a plain `int` (0.3.1 kept an `IntEnum` member as
+  given) and the components as a tuple. `build_flat_path` refuses a `str` as its
+  components with `TypeError` (0.3.1 split it into one-character components). A pickle
+  written by 0.3.1 loads with its fields normalised the same way.
+- Non-ASCII flattened bytes raise `FlatPathError` instead of `UnicodeDecodeError`.
+  `parse_flat_path`, `FlatPath.from_bytes` and `from_flat_path` read the raw bytes of any
+  object with the buffer protocol (`bytes`, `bytearray`, `memoryview`, `array`, `mmap`)
+  and are typed for `bytes | bytearray | memoryview`. 0.3.1 read `bytes` and
+  `bytearray` only: a `memoryview` or `array` holding a component raised
+  `AttributeError`, and a wide `array` was measured in items.
+- Error messages quote at most 40 characters of a value and several are reworded; the
+  exception types are unchanged except where listed here. The public classes
+  (`FlatPath`, `FlatPathType`, `PathKind`, `Platform` and the three exceptions) report
+  their module as `lvpath`, so pickles name `lvpath.<class>`; pickles made by 0.3.1 still
+  load.
+- Command line: a usage mistake still exits 2, now with lines of at most 200 characters;
+  a refused value prints one bounded line and exits 1; a closed output pipe exits 1
+  quietly; invalid hex no longer echoes the parser's detail; `lvpath encode ''` prints the
+  not-a-path bytes and `lvpath decode` of them is refused. A POSIX argument that is not
+  valid UTF-8 is written back as its original bytes (0.3.1 stopped with a
+  `UnicodeEncodeError` traceback); a lone surrogate UTF-8 cannot write at all (possible
+  in Windows arguments) is refused in one line with status 1; a missing standard stream
+  no longer raises.
+- A `str` subclass is read through its plain text: an overridden `__eq__` or `__len__`
+  no longer changes a result or slips past the component limits.
+
+## What it does not do
+
+- No file system access, no symbolic links, no `.`/`..` resolution beyond `pathlib`.
+- No classic Mac OS colon paths.
+- No expansion of symbolic prefixes such as `<vilib>` and no resolution of a relative
+  value against the file it came from.

{lvpath-0.3.1 → lvpath-1.0.0}/LICENSE

@@ -1,21 +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.
+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.

lvpath-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: lvpath
+Version: 1.0.0
+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: Source, 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,portable,pth0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+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 LabVIEW path values to and from Python `pathlib` paths, in all three forms
+LabVIEW uses: the portable text it writes into configuration and project files
+(`/C/DIR1/DIR2`), the native text of `Path To String`, and the flattened `PTH0` bytes
+of `Flatten To String`. Typed, no dependencies, Python 3.10 to 3.14.
+
+## Install
+
+```
+pip install lvpath
+```
+
+## Quick start
+
+Read a path value stored in an `.ini` or `.lvproj` file, and write one back:
+
+```pycon
+>>> from lvpath import from_portable_path, to_portable_path
+>>> from_portable_path("/C/Program Files (x86)/Arduino", platform="windows")
+PureWindowsPath('C:/Program Files (x86)/Arduino')
+>>> from_portable_path("../builds/Main Application", platform="windows")
+PureWindowsPath('../builds/Main Application')
+>>> to_portable_path("C:/DIR1/DIR2", platform="windows")
+'/C/DIR1/DIR2'
+>>> to_portable_path(None)
+''
+
+```
+
+Decode the flattened bytes of a LabVIEW path, such as NI's `C:\File` example:
+
+```pycon
+>>> from lvpath import from_flat_path, parse_flat_path, to_flat_path
+>>> golden = bytes.fromhex("505448300000000b0000000201430466696c65")
+>>> parse_flat_path(golden)
+FlatPath(path_type=0, components=('C', 'file'))
+>>> from_flat_path(golden, platform="windows")
+PureWindowsPath('C:/file')
+>>> to_flat_path("C:/file", platform="windows") == golden
+True
+>>> from_flat_path(to_flat_path("../lib/x.vi", platform="posix"), platform="posix")
+PurePosixPath('../lib/x.vi')
+
+```
+
+Work with the native text form and LabVIEW's `<Not A Path>` (the empty string):
+
+```pycon
+>>> from lvpath import path_kind, to_lv_path, to_os_path
+>>> to_os_path("C:\\Users\\test\\data.txt", platform="windows")
+PureWindowsPath('C:/Users/test/data.txt')
+>>> to_lv_path("logs/run.txt", platform="windows")
+'logs\\run.txt'
+>>> path_kind("", platform="posix")
+<PathKind.NOT_A_PATH: 'not_a_path'>
+
+```
+
+Every `platform` argument takes `"windows"`, `"posix"`, a `Platform` member, or `None`
+for the system running the code. Values with no faithful counterpart raise a typed
+error (`PortablePathError`, `FlatPathError`, `NotAPathError`) instead of being turned
+into a different path.
+
+## Command line
+
+```console
+$ 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
+$ lvpath decode --platform windows 505448300000000b0000000201430466696c65
+C:\file
+$ lvpath encode --platform posix ../lib/x.vi
+505448300000000e0001000300036c696204782e7669
+```
+
+`python -m lvpath` runs the same command. Refused values exit with status 1, usage
+mistakes with status 2. Run `lvpath --help` for every option.
+
+## Why
+
+LabVIEW writes one path in different forms depending on where it goes, and none of
+them reads correctly with plain string handling: `/C/DIR1/DIR2` names the wrong file on
+Windows, a native string means something only with the platform it was written on,
+and the flattened form needs the `PTH0` layout. `pathlib`'s `PureWindowsPath` and
+`PurePosixPath` already handle foreign-platform paths with no file access, so lvpath is
+a thin layer on top of them that adds only the LabVIEW part: the portable drive and UNC
+form, `<Not A Path>`, and the flattened container, including the rule that an empty
+flattened component means one level up.
+
+The conversions are checked against path values in files shipped with LabVIEW 2026,
+against flattened paths LabVIEW 2026 stored in its own installed files, and against
+the example on NI's public flattened-data page.
+
+## Documentation
+
+- [Guide](https://github.com/JaviLianes8/lvpath/blob/main/GUIDE.md): every rule, the
+  errors, the command line and upgrading from 0.3.
+- [Changelog](https://github.com/JaviLianes8/lvpath/blob/main/CHANGELOG.md)
+
+## License
+
+MIT. See [LICENSE](https://github.com/JaviLianes8/lvpath/blob/main/LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/