python-gdb 0.1.0__tar.gz → 0.2.1__tar.gz

python_gdb-0.1.0/README.md → python_gdb-0.2.1/PKG-INFO

@@ -1,3 +1,41 @@
+Metadata-Version: 2.4
+Name: python-gdb
+Version: 0.2.1
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=2.2
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: xarray ; extra == 'dev'
+Requires-Dist: geoh5py ; extra == 'dev'
+Requires-Dist: pandas ; extra == 'dev'
+Requires-Dist: zensical ; extra == 'docs'
+Requires-Dist: mkdocstrings-python ; extra == 'docs'
+Requires-Dist: geoh5py ; extra == 'geoh5'
+Requires-Dist: pandas ; extra == 'pandas'
+Requires-Dist: xarray ; extra == 'xarray'
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: geoh5
+Provides-Extra: pandas
+Provides-Extra: xarray
+License-File: LICENSE
+Summary: A clean-room Python reader for Geosoft .gdb database and .grd grid files
+Author-email: Joseph Capriotti <josephrcapriotti@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://jcapriot.github.io/pygdb/
+Project-URL: Homepage, https://github.com/jcapriot/pygdb
+Project-URL: Issues, https://github.com/jcapriot/pygdb/issues
+Project-URL: Repository, https://github.com/jcapriot/pygdb
+
 # pygdb
 
 A clean-room Python reader for Geosoft's proprietary `.gdb` ("Geosoft
@@ -21,7 +59,10 @@ real, publicly downloaded `.gdb` files. No Geosoft software of any kind
 Desktop, or the free Geosoft Viewer) was installed, imported, or
 executed at any point in producing it.
 
-Reading only — writing or mutating `.gdb`/`.grd` files is out of scope.
+Reading only — writing or mutating `.gdb`/`.grd` files (Geosoft's own
+proprietary formats) is out of scope. Exporting what's been read into a
+different, openly-specified format is a separate concern and *is*
+supported -- see `to_xarray`/`to_geoh5`/`to_dataframe` below.
 
 ## Installation
 
@@ -48,6 +89,8 @@ db = GDB("example.gdb")
 
 db.compression           # CompressionInfo(code=0, name='DB_COMP_NONE', ...)
 db.coordinate_systems     # ['NAD83 / UTM zone 11N', 'WGS 84'] (best-effort, may be [])
+db.coordinate_channels    # {'X': 'Easting', 'Y': 'Northing', 'Z': None} (from the
+                          #  file's own internal registry, may be all-None)
 
 db.line_names[:5]         # ['L1000', 'L1001', 'L1010', 'L1020', 'L1030']
 db.channels_on_line("L1000")   # channels that actually have data on this line
@@ -60,10 +103,23 @@ db.read("L1000", "Easting")    # random access by (line name, channel name)
 See [the docs](docs/index.md) for the lower-level, slot-index-based
 functions `GDB` is built on.
 
-`db.to_xarray("L1000")` exports one line to an `xarray.Dataset`
-(`pip install python-gdb[xarray]`, an optional dependency) — see
-[the docs](docs/index.md#exporting-to-xarray) for how VA/array channels
-and duplicate channel names come through.
+`db.to_xarray("L1000")` exports one line (or `db.to_xarray()` for the
+whole file, every line stacked along a `"line"` coordinate) to an
+`xarray.Dataset` (`pip install python-gdb[xarray]`, an optional
+dependency) — see
+[the docs](docs/index.md#exporting-to-xarray) for how VA/array channels,
+duplicate channel names, and whole-file fill values come through.
+
+`db.to_geoh5("survey.geoh5")` exports the whole file to a
+`geoh5py.Workspace` (`pip install python-gdb[geoh5]`, an optional
+dependency) — see [the docs](docs/index.md#exporting-to-geoh5) for how
+line geometry and VA/array channels come through.
+
+`db.to_dataframe()` exports the whole file (or `db.to_dataframe("L1000")`
+for just one line) to a `pandas.DataFrame` (`pip install
+python-gdb[pandas]`, an optional dependency) — see
+[the docs](docs/index.md#exporting-to-pandas) for how row-count
+mismatches and VA/array channels come through.
 
 ## Optional Rust-accelerated backend
 
@@ -74,9 +130,12 @@ so that an optional Rust extension (`pygdb._native`, source under
 [`rust/`](rust/)) rides along and is used automatically when present:
 it accelerates the two real CPU-bound hot paths profiling found in this
 reader — LZRW1 decompression and fixed-width string decoding — roughly
-3-6x on real files, measured against this project's own sample corpus.
-`pygdb/lzrw1.py`/`pygdb/gdb_reader.py` detect it at import time and fall
-back to plain Python transparently if it isn't there.
+3-6x on real files, measured against this project's own sample corpus,
+and decompresses `DB_COMP_SIZE` (zlib) data ~11% faster than the stdlib
+fallback with one fewer copy, using the `flate2` crate on its
+`zlib-rs` backend. `pygdb/lzrw1.py`/`pygdb/gdb_reader.py` detect it at
+import time and fall back to plain Python transparently if it isn't
+there.
 
 Building it yourself (e.g. for local development, or a platform without
 a published wheel) needs a Rust toolchain:
@@ -107,9 +166,12 @@ option — `abi3t` only exists from 3.15 onward).
 ## Documentation
 
 Full documentation — the format specification, usage, contributing
-guide, and research provenance — lives under [`docs/`](docs/index.md)
-and is built with [Zensical](https://zensical.org/). To view it
-locally:
+guide, and research provenance — is published at
+**[jcapriot.github.io/pygdb](https://jcapriot.github.io/pygdb/)**,
+built from [`docs/`](docs/index.md) with [Zensical](https://zensical.org/)
+(published on every GitHub Release — see
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml)). To view a
+work-in-progress version locally instead:
 
 ```sh
 pip install -e ".[docs]"
@@ -120,11 +182,15 @@ zensical serve
   for the `.gdb`/`.grd` on-disk format, with a confidence rating
   (confirmed / likely / guess / unknown) on every field. Updated as
   more real example files are tested against it.
+- [`docs/reference.md`](docs/reference.md) — API reference for
+  `pygdb`'s public surface, generated from its own numpydoc-style
+  docstrings via [`mkdocstrings`](https://mkdocstrings.github.io/).
 - [`docs/contributing.md`](docs/contributing.md) — how to report bugs
   (reproducible example files welcome) and this project's hard
   boundary on reverse engineering.
 - [`docs/provenance/`](docs/provenance/index.md) — the original
   research log and write-up this implementation was derived from.
+- [`CHANGELOG.md`](CHANGELOG.md) — what changed in each release.
 
 ## Testing
 
@@ -153,3 +219,4 @@ can be re-downloaded independently.
 ## License
 
 [MIT](LICENSE) — Copyright (c) 2026 Joseph Capriotti.
+

python_gdb-0.1.0/PKG-INFO → python_gdb-0.2.1/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.4
-Name: python-gdb
-Version: 0.1.0
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Science/Research
-Classifier: Topic :: Scientific/Engineering :: GIS
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Operating System :: OS Independent
-Requires-Dist: numpy>=2.2
-Requires-Dist: pytest>=7.0 ; extra == 'dev'
-Requires-Dist: xarray ; extra == 'dev'
-Requires-Dist: zensical ; extra == 'docs'
-Requires-Dist: xarray ; extra == 'xarray'
-Provides-Extra: dev
-Provides-Extra: docs
-Provides-Extra: xarray
-License-File: LICENSE
-Summary: A clean-room Python reader for Geosoft .gdb database and .grd grid files
-Author-email: Joseph Capriotti <josephrcapriotti@gmail.com>
-License-Expression: MIT
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-
 # pygdb
 
 A clean-room Python reader for Geosoft's proprietary `.gdb` ("Geosoft
@@ -48,7 +21,10 @@ real, publicly downloaded `.gdb` files. No Geosoft software of any kind
 Desktop, or the free Geosoft Viewer) was installed, imported, or
 executed at any point in producing it.
 
-Reading only — writing or mutating `.gdb`/`.grd` files is out of scope.
+Reading only — writing or mutating `.gdb`/`.grd` files (Geosoft's own
+proprietary formats) is out of scope. Exporting what's been read into a
+different, openly-specified format is a separate concern and *is*
+supported -- see `to_xarray`/`to_geoh5`/`to_dataframe` below.
 
 ## Installation
 
@@ -75,6 +51,8 @@ db = GDB("example.gdb")
 
 db.compression           # CompressionInfo(code=0, name='DB_COMP_NONE', ...)
 db.coordinate_systems     # ['NAD83 / UTM zone 11N', 'WGS 84'] (best-effort, may be [])
+db.coordinate_channels    # {'X': 'Easting', 'Y': 'Northing', 'Z': None} (from the
+                          #  file's own internal registry, may be all-None)
 
 db.line_names[:5]         # ['L1000', 'L1001', 'L1010', 'L1020', 'L1030']
 db.channels_on_line("L1000")   # channels that actually have data on this line
@@ -87,10 +65,23 @@ db.read("L1000", "Easting")    # random access by (line name, channel name)
 See [the docs](docs/index.md) for the lower-level, slot-index-based
 functions `GDB` is built on.
 
-`db.to_xarray("L1000")` exports one line to an `xarray.Dataset`
-(`pip install python-gdb[xarray]`, an optional dependency) — see
-[the docs](docs/index.md#exporting-to-xarray) for how VA/array channels
-and duplicate channel names come through.
+`db.to_xarray("L1000")` exports one line (or `db.to_xarray()` for the
+whole file, every line stacked along a `"line"` coordinate) to an
+`xarray.Dataset` (`pip install python-gdb[xarray]`, an optional
+dependency) — see
+[the docs](docs/index.md#exporting-to-xarray) for how VA/array channels,
+duplicate channel names, and whole-file fill values come through.
+
+`db.to_geoh5("survey.geoh5")` exports the whole file to a
+`geoh5py.Workspace` (`pip install python-gdb[geoh5]`, an optional
+dependency) — see [the docs](docs/index.md#exporting-to-geoh5) for how
+line geometry and VA/array channels come through.
+
+`db.to_dataframe()` exports the whole file (or `db.to_dataframe("L1000")`
+for just one line) to a `pandas.DataFrame` (`pip install
+python-gdb[pandas]`, an optional dependency) — see
+[the docs](docs/index.md#exporting-to-pandas) for how row-count
+mismatches and VA/array channels come through.
 
 ## Optional Rust-accelerated backend
 
@@ -101,9 +92,12 @@ so that an optional Rust extension (`pygdb._native`, source under
 [`rust/`](rust/)) rides along and is used automatically when present:
 it accelerates the two real CPU-bound hot paths profiling found in this
 reader — LZRW1 decompression and fixed-width string decoding — roughly
-3-6x on real files, measured against this project's own sample corpus.
-`pygdb/lzrw1.py`/`pygdb/gdb_reader.py` detect it at import time and fall
-back to plain Python transparently if it isn't there.
+3-6x on real files, measured against this project's own sample corpus,
+and decompresses `DB_COMP_SIZE` (zlib) data ~11% faster than the stdlib
+fallback with one fewer copy, using the `flate2` crate on its
+`zlib-rs` backend. `pygdb/lzrw1.py`/`pygdb/gdb_reader.py` detect it at
+import time and fall back to plain Python transparently if it isn't
+there.
 
 Building it yourself (e.g. for local development, or a platform without
 a published wheel) needs a Rust toolchain:
@@ -134,9 +128,12 @@ option — `abi3t` only exists from 3.15 onward).
 ## Documentation
 
 Full documentation — the format specification, usage, contributing
-guide, and research provenance — lives under [`docs/`](docs/index.md)
-and is built with [Zensical](https://zensical.org/). To view it
-locally:
+guide, and research provenance — is published at
+**[jcapriot.github.io/pygdb](https://jcapriot.github.io/pygdb/)**,
+built from [`docs/`](docs/index.md) with [Zensical](https://zensical.org/)
+(published on every GitHub Release — see
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml)). To view a
+work-in-progress version locally instead:
 
 ```sh
 pip install -e ".[docs]"
@@ -147,11 +144,15 @@ zensical serve
   for the `.gdb`/`.grd` on-disk format, with a confidence rating
   (confirmed / likely / guess / unknown) on every field. Updated as
   more real example files are tested against it.
+- [`docs/reference.md`](docs/reference.md) — API reference for
+  `pygdb`'s public surface, generated from its own numpydoc-style
+  docstrings via [`mkdocstrings`](https://mkdocstrings.github.io/).
 - [`docs/contributing.md`](docs/contributing.md) — how to report bugs
   (reproducible example files welcome) and this project's hard
   boundary on reverse engineering.
 - [`docs/provenance/`](docs/provenance/index.md) — the original
   research log and write-up this implementation was derived from.
+- [`CHANGELOG.md`](CHANGELOG.md) — what changed in each release.
 
 ## Testing
 
@@ -180,4 +181,3 @@ can be re-downloaded independently.
 ## License
 
 [MIT](LICENSE) — Copyright (c) 2026 Joseph Capriotti.
-

{python_gdb-0.1.0 → python_gdb-0.2.1}/pygdb/__init__.py

@@ -57,4 +57,13 @@ __all__ = [
     "read_lines",
 ]
 
-__version__ = "0.1.0"
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Reads the installed distribution's metadata -- itself sourced
+    # from rust/Cargo.toml's [package].version via pyproject.toml's
+    # dynamic version (see [project] there), so this never needs its
+    # own hardcoded copy to keep in sync.
+    __version__ = version("python-gdb")
+except PackageNotFoundError:  # pragma: no cover -- only when not installed
+    __version__ = "0.0.0+unknown"