Merge pull request #171 from prjemian/159-uxml-writer

UXML plugin writer()

.travis.yml

@@ -20,7 +20,7 @@ before_script:
   - bash miniconda.sh -b -p $HOME/miniconda
   - export PATH=$HOME/miniconda/bin:$PATH
   - export PY_ENV=travis-$TRAVIS_PYTHON_VERSION
-  - conda create -y -n $PY_ENV python=$TRAVIS_PYTHON_VERSION numpy MatPlotLib h5py coverage docopt
+  - conda create -y -n $PY_ENV python=$TRAVIS_PYTHON_VERSION numpy lxml MatPlotLib h5py six coverage docopt
   - source activate $PY_ENV
   - which pip
   - which python

CHANGES.rst

@@ -13,7 +13,12 @@ Change History
 Production
 **********
 
-:2021.0.1: *2019.07.13*, plugin loading  and documentation
+:2021.1.0: expected *2019.08*, handle #UXML control lines
+
+    * `#159 <https://github.com/prjemian/spec2nexus/issues/159>`_
+       handle #UXML metadata control lines
+
+:2021.0.1: *2019.07.13*, plugin loading and documentation
 
     * `#170 <https://github.com/prjemian/spec2nexus/issues/170>`_
        describe how to write & load Control Line Handler plugins

conda-recipe/meta.yaml

@@ -23,22 +23,24 @@ package:
 
 build:
   noarch: python
-  script: python setup.py install
+  script: python -m pip install --no-deps --ignore-installed .
 
 requirements:
 
   build:
     - python
     - setuptools
     - h5py
-    - numpy
+    - lxml
     - matplotlib
+    - numpy
     - six
 
   run:
     - h5py
-    - numpy
+    - lxml
     - matplotlib
+    - numpy
     - six
 
 test:

docs/source/plugin.rst

@@ -31,8 +31,10 @@ These plugin modules are supplied:
 
    ~spec2nexus.plugins.spec_common
    ~spec2nexus.plugins.fallback
+   ~spec2nexus.plugins.apstools_specwriter
    ~spec2nexus.plugins.unicat
    ~spec2nexus.plugins.uim
+   ~spec2nexus.plugins.uxml
    ~spec2nexus.plugins.XPCS
 
 .. toctree::

docs/source/supplied_plugins/apstools_specwriter.rst

@@ -0,0 +1,19 @@
+
+.. _apstools_specwriter_plugin:
+
+apstools SpecWriterCallback metadata plugin
+###########################################
+
+Looks for ``#MD`` :index:`control line` control lines.
+These lines contain metadata supplied to the bluesky ``RunEngine``
+and recorded during the execution of a scan.  The data are stored
+in a dictionary of each scan: ``scan.MD``.  If there are no
+``#MD`` control lines, then ``scan.MD`` does not exist.
+
+**see** https://apstools.readthedocs.io/en/latest/source/_filewriters.html#apstools.filewriters.SpecWriterCallback
+
+----
+
+.. automodule:: spec2nexus.plugins.apstools_specwriter
+    :members: 
+    :synopsis: Bluesky metadata from apstools SpecWriterCallback.

docs/source/supplied_plugins/unicat_spec2nexus.rst → docs/source/supplied_plugins/unicat.rst

@@ -1,8 +1,8 @@
 
 .. _unicat_plugin:
 
-UNICAT metadata plugin
-######################
+unicat plugin
+##########################
 
 .. automodule:: spec2nexus.plugins.unicat
     :members: 

docs/source/supplied_plugins/uxml.rst

@@ -0,0 +1,36 @@
+
+.. _uxml_plugin:
+
+UXML metadata plugin
+####################
+
+Looks for ``#UXML`` :index:`control line` control lines.
+These lines contain metadata written as XML structures
+and formatted according to the supplied XML Schema ``uxml.xsd`` 
+in the same directory as the ``uxml.py`` plugin.
+The lines which comprise the XML are written as a list in 
+each scan: ``scan.UXML``.  If there are no
+``#UXML`` control lines, then ``scan.UXML`` does not exist.
+
+Once the scan has been fully read ``scan.UXML`` is converted
+into an XML document structure (using the *lxml.etree* package) 
+which is stored in ``scan.UXML_root``.  The structure is validated
+against the XML Schema ``uxml.xsd``.  If invalid, the error message 
+is reported by raising a ``UXML_Error`` python exception.
+
+A fully-validated structure can be written using the 
+:class:`~spec2nexus.writer.Writer` class.  The UXML metadata is
+written to the scan's ``NXentry`` group as subgroup named ``UXML``
+with NeXus base class ``NXnote``.  The hierarchy within this ``UXML``
+is defined from the content provided in the SPEC scan.
+
+Please consult the XML Schema file for the rules governing the
+use of ``#UXML`` in a SPEC data file: 
+* :download:`uxml.xsd <../../../src/spec2nexus/plugins/uxml.xsd>`
+
+
+----
+
+.. automodule:: spec2nexus.plugins.uxml
+    :members: 
+    :synopsis: UXML structured metadata.

requirements-dev.txt

@@ -0,0 +1,3 @@
+versioneer
+coverage
+coveralls

requirements.txt

@@ -0,0 +1,5 @@
+h5py
+lxml
+matplotlib
+numpy
+six

setup.py

@@ -20,27 +20,27 @@
 # pull in some definitions from the package's __init__.py file
 basedir = os.path.dirname(__file__)
 sys.path.insert(0, os.path.join(basedir, 'src', ))
-import spec2nexus
+import spec2nexus as package
 
 
 verbose=1
 long_description = open(os.path.join(basedir, 'README.md'), 'r').read()
 
 
 setup (
-    name             = spec2nexus.__package_name__,
+    name             = package.__package_name__,
     version          = versioneer.get_version(),
     cmdclass         = versioneer.get_cmdclass(),
-    license          = spec2nexus.__license__,
-    description      = spec2nexus.__description__,
+    license          = package.__license__,
+    description      = package.__description__,
     long_description = long_description,
-    author           = spec2nexus.__author_name__,
-    author_email     = spec2nexus.__author_email__,
-    url              = spec2nexus.__url__,
-    #download_url=spec2nexus.__download_url__,
-    keywords         = spec2nexus.__keywords__,
+    author           = package.__author_name__,
+    author_email     = package.__author_email__,
+    url              = package.__url__,
+    #download_url=package.__download_url__,
+    keywords         = package.__keywords__,
     platforms        = 'any',
-    install_requires = spec2nexus.__install_requires__,
+    install_requires = package.__install_requires__,
     package_dir      = {'': 'src'},
     packages         = ['spec2nexus', 'spec2nexus.plugins', ],
     package_data     = {
@@ -51,7 +51,7 @@
             'LICENSE.txt',
             ],
          },
-    classifiers      = spec2nexus.__classifiers__,
+    classifiers      = package.__classifiers__,
     entry_points     = {
          # create & install scripts in <python>/bin
          'console_scripts': [

src/spec2nexus/__init__.py

@@ -27,7 +27,10 @@
 __url__          = u'http://spec2nexus.readthedocs.org'
 __keywords__     = ['SPEC', 'diffraction', 'data acquisition', 'NeXus', 'HDF5', 'MatPlotLib']
 
-__install_requires__ = ('h5py', 'numpy', 'six', 'matplotlib')
+from ._requirements import learn_requirements
+__install_requires__ = learn_requirements()
+del learn_requirements
+
 __classifiers__ = [
      'Development Status :: 5 - Production/Stable',
      'Environment :: Console',

src/spec2nexus/_requirements.py

@@ -0,0 +1,38 @@
+#-----------------------------------------------------------------------------
+# :author:    Pete R. Jemian
+# :email:     jemian@anl.gov
+# :copyright: (c) 2017-2019, UChicago Argonne, LLC
+#
+# Distributed under the terms of the Creative Commons Attribution 4.0 International Public License.
+#
+# The full license is in the file LICENSE.txt, distributed with this software.
+#-----------------------------------------------------------------------------
+
+
+
+def learn_requirements():
+    """
+    list all installation requirements 
+    
+    ALL packages & version restrictions stated in requirements.txt
+    """
+    req_file = 'requirements.txt'
+    reqs = []
+
+    import os
+    path = os.path.dirname(__file__)
+    req_file = os.path.join(path, '..', req_file)
+    if not os.path.exists(req_file):
+        # not needed with installed package
+        return reqs
+
+    excludes = "versioneer coveralls coverage".split()
+    with open(req_file, 'r') as fp:
+        buf = fp.read().strip().splitlines()
+        for req in buf:
+            req = req.strip()
+            if req != "" \
+                    and not req.startswith('#') \
+                    and req not in excludes:
+                reqs.append(req)
+    return reqs

src/spec2nexus/plugins/__init__.py

@@ -13,4 +13,5 @@
 from . import apstools_specwriter
 from . import uim
 from . import unicat
+from . import uxml
 from . import XPCS