Update docs for #322

kinverarity1 · May 13, 2022 · 9ba407d · 9ba407d
1 parent 26ed8a4
commit 9ba407d
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 4 deletions.
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -1,6 +1,32 @@
 List of changes
 ===============================
 
+Unreleased changes (Available on GitHub)
+----------------------------------------
+- Fix `#322`_ - provide a way to consistently retrieve header items which may
+  or may not be present in the header:
+
+  If you try ordinary item-style access,
+  as is normal in Python, a KeyError exception will be raised if it is missing:
+
+  .. code-block:: python
+
+      >>> permit = las.well['PRMT']
+      Traceback (most recent call last):
+        File "<stdin>", line 1, in <module>
+        File "c:\devapps\kinverarity\projects\lasio\lasio\las_items.py", line 313, in __getitem__
+          raise KeyError("%s not in %s" % (key, self.keys()))
+      KeyError: "PRMT not in ['STRT', 'STOP', 'STEP', 'NULL', 'COMP', 'WELL', 'FLD', 'LOC', 'PROV', 'SRVC', 'DATE', 'UWI']"
+
+  A better pattern is to use the :meth:`lasio.SectionItems.get` method, which
+  allows you to specify a default value in the case of it missing:
+
+  .. code-block:: python
+
+      >>> permit = las.well.get('PRMT', 'unknown')
+      >>> permit
+      HeaderItem(mnemonic="PRMT", unit="", value="unknown", descr="")
+
 Version 0.30 (12 May 2022)
 --------------------------
 - Fixes for `#446`_ (Implement a numpy-based reader for the data section; `#452`_) and 
@@ -308,6 +334,7 @@ Version 0.2 (2015-07-08)
 .. _#318: https://github.com/kinverarity1/lasio/issues/318
 .. _#319: https://github.com/kinverarity1/lasio/issues/319
 .. _#321: https://github.com/kinverarity1/lasio/issues/321
+.. _#322: https://github.com/kinverarity1/lasio/issues/322
 .. _#325: https://github.com/kinverarity1/lasio/issues/325
 .. _#326: https://github.com/kinverarity1/lasio/issues/326
 .. _#327: https://github.com/kinverarity1/lasio/issues/327
@@ -387,7 +414,7 @@ Version 0.2 (2015-07-08)
 .. _#268: https://github.com/kinverarity1/lasio/issues/268
 .. _#451: https://github.com/kinverarity1/lasio/issues/451
 .. _#453: https://github.com/kinverarity1/lasio/issues/453
-.. _#455: https://github.com/kinverarity1/lasio/issues/455.. _#83: https://github.com/kinverarity1/lasio/issues/83
+.. _#455: https://github.com/kinverarity1/lasio/issues/455
 .. _#265: https://github.com/kinverarity1/lasio/issues/265
 .. _#332: https://github.com/kinverarity1/lasio/issues/332
 .. _#375: https://github.com/kinverarity1/lasio/issues/375

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -26,7 +26,7 @@
 master_doc = "index"
 
 project = u"lasio"
-copyright = u"2013-2021, lasio contributors"
+copyright = u"2013-2022, lasio contributors"
 author = u"lasio contributors"
 
 from pkg_resources import get_distribution

diff --git a/docs/source/header-section.rst b/docs/source/header-section.rst
@@ -258,6 +258,28 @@ There are methods intended for removing curves. Say you want to remove the PR cu
      CurveItem(mnemonic="DFAR", unit="G/CM3", value="", descr="DFAR", original_mnemonic="DFAR", data.shape=(121,)),
      CurveItem(mnemonic="DNEAR", unit="G/CM3", value="", descr="DNEAR", original_mnemonic="DNEAR", data.shape=(121,))]
 
+Another common task is to retrieve a header item that may or may not be in the
+file. If you try ordinary item-style access,
+as is normal in Python, a KeyError exception will be raised if it is missing:
+
+.. code-block:: python
+
+    >>> permit = las.well['PRMT']
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File "c:\devapps\kinverarity\projects\lasio\lasio\las_items.py", line 313, in __getitem__
+        raise KeyError("%s not in %s" % (key, self.keys()))
+    KeyError: "PRMT not in ['STRT', 'STOP', 'STEP', 'NULL', 'COMP', 'WELL', 'FLD', 'LOC', 'PROV', 'SRVC', 'DATE', 'UWI']"
+
+A better pattern is to use the :meth:`lasio.SectionItems.get` method, which
+allows you to specify a default value in the case of it missing:
+
+.. code-block:: python
+
+    >>> permit = las.well.get('PRMT', 'unknown')
+    >>> permit
+    HeaderItem(mnemonic="PRMT", unit="", value="unknown", descr="")
+
 Handling special cases of header lines
 --------------------------------------
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -45,8 +45,7 @@ The final version of lasio with Python 2.7 support is v0.26.
    encodings
    lasio
    contributing
-
-.. include:: changelog.rst
+   changelog
 
 * :ref:`genindex`
 * :ref:`search`
diff --git a/docs/source/lasio.rst b/docs/source/lasio.rst
@@ -41,6 +41,11 @@ Reading data
 .. autoattribute:: lasio.LASFile.data
 .. automethod:: lasio.LASFile.stack_curves
 
+Reading and modifying header data
+---------------------------------
+.. autoclass:: lasio.SectionItems
+    :members:
+
 Modifying data
 --------------
 .. automethod:: lasio.LASFile.set_data