version transparency and help help

version can now be shown with tp.__version__ or by passing the --version option to any tp cli function
help is now shown with -h as well as --help
docs updates

README.rst

@@ -13,7 +13,7 @@
     | |   |___   ___  |___  |_____   ___ :|___/  ___   |___   ___   ___  |___ \
     | |   |   | /   \ |   \ |  |  | /   \:|     /   |  |   \ /     /   \ |   \/
     | |   |   | |___/ |     |  |  | |   |:|     |   |  |     \___  |___/ |    \_____
-    | |   |   | \___  |     |  |  | \___/:|     \___|_ |         \ \___  |    :3.1.3\
+    | |   |   | \___  |     |  |  | \___/:|     \___|_ |         \ \___  |    :3.1.4\
     |____________________________________:_______________________/____________:_____/
 
 
@@ -197,6 +197,13 @@ Roughly chronologically, they are so far:
 * Katarina Brlec
 * Joe Willis
 
+Thanks also to the `JOSS`_ reviewers, Evan Walter Clarke
+Spotte-Smith, Enric Tomás Grau-Luque, and Francesco Nattino; and the
+editor Mojtaba Barzegari. An unintimidating and productive review
+process, which I would recommend if the opportunity arises!
+
+.. _JOSS: https://joss.theoj.org/
+
 License
 -------
 

docs/_modules/tp.html

@@ -83,6 +83,8 @@ <h1>Source code for tp</h1><div class="highlight"><pre>
 <span class="c1">#        default values and metadata</span>
 <span class="c1">#&quot;&quot;&quot;</span>
 
+<span class="n">__version__</span> <span class="o">=</span> <span class="s1">&#39;3.1.4&#39;</span>
+
 <div class="viewcode-block" id="docstring_replace"><a class="viewcode-back" href="../tp.html#tp.docstring_replace">[docs]</a><span class="k">def</span> <span class="nf">docstring_replace</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
     <span class="k">def</span> <span class="nf">d</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
         <span class="n">f</span><span class="o">.</span><span class="vm">__doc__</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="vm">__doc__</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

docs/genindex.html

@@ -125,10 +125,10 @@ <h2 id="A">A</h2>
 </li>
       <li><a href="tp.plot.html#tp.plot.phonons.add_multi">add_multi() (in module tp.plot.phonons)</a>
 </li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="tp.plot.html#tp.plot.heatmap.add_pfdiff">add_pfdiff() (in module tp.plot.heatmap)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="tp.plot.html#tp.plot.heatmap.add_pfmap">add_pfmap() (in module tp.plot.heatmap)</a>
 </li>
       <li><a href="tp.plot.html#tp.plot.phonons.add_projected_dispersion">add_projected_dispersion() (in module tp.plot.phonons)</a>
@@ -142,6 +142,8 @@ <h2 id="A">A</h2>
       <li><a href="tp.plot.html#tp.plot.heatmap.add_ztdiff">add_ztdiff() (in module tp.plot.heatmap)</a>
 </li>
       <li><a href="tp.plot.html#tp.plot.heatmap.add_ztmap">add_ztmap() (in module tp.plot.heatmap)</a>
+</li>
+      <li><a href="tp.cli.html#tp.cli.options.adminsitrative_options">adminsitrative_options() (in module tp.cli.options)</a>
 </li>
       <li><a href="tp.axes.html#tp.axes.legend.alphabetise">alphabetise() (in module tp.axes.legend)</a>
 </li>

docs/index.html

@@ -85,7 +85,7 @@
 <span class="o">|</span> <span class="o">|</span>   <span class="o">|</span><span class="n">___</span>   <span class="n">___</span>  <span class="o">|</span><span class="n">___</span>  <span class="o">|</span><span class="n">_____</span>   <span class="n">___</span> <span class="p">:</span><span class="o">|</span><span class="n">___</span><span class="o">/</span>  <span class="n">___</span>   <span class="o">|</span><span class="n">___</span>   <span class="n">___</span>   <span class="n">___</span>  <span class="o">|</span><span class="n">___</span> \
 <span class="o">|</span> <span class="o">|</span>   <span class="o">|</span>   <span class="o">|</span> <span class="o">/</span>   \ <span class="o">|</span>   \ <span class="o">|</span>  <span class="o">|</span>  <span class="o">|</span> <span class="o">/</span>   \<span class="p">:</span><span class="o">|</span>     <span class="o">/</span>   <span class="o">|</span>  <span class="o">|</span>   \ <span class="o">/</span>     <span class="o">/</span>   \ <span class="o">|</span>   \<span class="o">/</span>
 <span class="o">|</span> <span class="o">|</span>   <span class="o">|</span>   <span class="o">|</span> <span class="o">|</span><span class="n">___</span><span class="o">/</span> <span class="o">|</span>     <span class="o">|</span>  <span class="o">|</span>  <span class="o">|</span> <span class="o">|</span>   <span class="o">|</span><span class="p">:</span><span class="o">|</span>     <span class="o">|</span>   <span class="o">|</span>  <span class="o">|</span>     \<span class="n">___</span>  <span class="o">|</span><span class="n">___</span><span class="o">/</span> <span class="o">|</span>    \<span class="n">_____</span>
-<span class="o">|</span> <span class="o">|</span>   <span class="o">|</span>   <span class="o">|</span> \<span class="n">___</span>  <span class="o">|</span>     <span class="o">|</span>  <span class="o">|</span>  <span class="o">|</span> \<span class="n">___</span><span class="o">/</span><span class="p">:</span><span class="o">|</span>     \<span class="n">___</span><span class="o">|</span><span class="n">_</span> <span class="o">|</span>         \ \<span class="n">___</span>  <span class="o">|</span>    <span class="p">:</span><span class="mf">3.1</span><span class="o">.</span><span class="mi">3</span>\
+<span class="o">|</span> <span class="o">|</span>   <span class="o">|</span>   <span class="o">|</span> \<span class="n">___</span>  <span class="o">|</span>     <span class="o">|</span>  <span class="o">|</span>  <span class="o">|</span> \<span class="n">___</span><span class="o">/</span><span class="p">:</span><span class="o">|</span>     \<span class="n">___</span><span class="o">|</span><span class="n">_</span> <span class="o">|</span>         \ \<span class="n">___</span>  <span class="o">|</span>    <span class="p">:</span><span class="mf">3.1</span><span class="o">.</span><span class="mi">4</span>\
 <span class="o">|</span><span class="n">____________________________________</span><span class="p">:</span><span class="n">_______________________</span><span class="o">/</span><span class="n">____________</span><span class="p">:</span><span class="n">_____</span><span class="o">/</span>
 </pre></div>
 </div>
@@ -247,6 +247,10 @@ <h1>Contributors<a class="headerlink" href="#contributors" title="Permalink to t
 <li><p>Katarina Brlec</p></li>
 <li><p>Joe Willis</p></li>
 </ul>
+<p>Thanks also to the <a class="reference external" href="https://joss.theoj.org/">JOSS</a> reviewers, Evan Walter Clarke
+Spotte-Smith, Enric Tomás Grau-Luque, and Francesco Nattino; and the
+editor Mojtaba Barzegari. An unintimidating and productive review
+process, which I would recommend if the opportunity arises!</p>
 </div>
 <div class="section" id="license">
 <h1>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h1>

docs/tp.cli.html

@@ -108,6 +108,23 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this
 <div class="section" id="module-tp.cli.options">
 <span id="tp-cli-options-module"></span><h2>tp.cli.options module<a class="headerlink" href="#module-tp.cli.options" title="Permalink to this headline">¶</a></h2>
 <p>Provides groups of options to streamline the CLI</p>
+<dl class="py function">
+<dt id="tp.cli.options.adminsitrative_options">
+<code class="sig-prename descclassname">tp.cli.options.</code><code class="sig-name descname">adminsitrative_options</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">f</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/tp/cli/options.html#adminsitrative_options"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#tp.cli.options.adminsitrative_options" title="Permalink to this definition">¶</a></dt>
+<dd><p>Help and version options.</p>
+<p>Allows -h for help (click-nonstandard).</p>
+<blockquote>
+<div><dl class="option-list">
+<dt><kbd><span class="option">--help</span>, <span class="option">-h</span></kbd></dt>
+<dd><p>show help and exit</p>
+</dd>
+<dt><kbd><span class="option">--version</span></kbd></dt>
+<dd><p>show version and exit</p>
+</dd>
+</dl>
+</div></blockquote>
+</dd></dl>
+
 <dl class="py function">
 <dt id="tp.cli.options.axes_limit_function">
 <code class="sig-prename descclassname">tp.cli.options.</code><code class="sig-name descname">axes_limit_function</code><span class="sig-paren">(</span><em class="sig-param"><span class="n">multiple</span><span class="o">=</span><span class="default_value">False</span></em>, <em class="sig-param"><span class="n">c</span><span class="o">=</span><span class="default_value">False</span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/tp/cli/options.html#axes_limit_function"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#tp.cli.options.axes_limit_function" title="Permalink to this definition">¶</a></dt>

docs/tutorial-00.html

@@ -94,7 +94,7 @@ <h1>Tutorial-00: CLI Fundamentals<a class="headerlink" href="#tutorial-00-cli-fu
 available functions. Then type in all three parts to get a detailed
 description of how to use the function, e.g. <code class="docutils literal notranslate"><span class="pre">tp</span> <span class="pre">get</span> <span class="pre">zt</span></code>.
 If further arguments have been given, this can be accessed with
-<code class="docutils literal notranslate"><span class="pre">--help</span></code>, but note <code class="docutils literal notranslate"><span class="pre">-h</span></code> is <em>not</em> a substitute for <code class="docutils literal notranslate"><span class="pre">--help</span></code>.</p>
+<code class="docutils literal notranslate"><span class="pre">--help</span></code> or <code class="docutils literal notranslate"><span class="pre">-h</span></code>.</p>
 <p>Typically, you will need one or more data files, which are inputted
 directly after the command, e.g. <code class="docutils literal notranslate"><span class="pre">tp</span> <span class="pre">plot</span> <span class="pre">avg-rates</span> <span class="pre">mesh.h5</span></code>. The
 type of file is hinted at at the top of the <code class="docutils literal notranslate"><span class="pre">--help</span></code>, e.g.

examples/00-cli-fundamentals/README.rst

@@ -10,7 +10,7 @@ type the full thing in, e.g. ``tp get``, to get a similar list of the
 available functions. Then type in all three parts to get a detailed
 description of how to use the function, e.g. ``tp get zt``.
 If further arguments have been given, this can be accessed with
-``--help``, but note ``-h`` is *not* a substitute for ``--help``.
+``--help`` or ``-h``.
 
 Typically, you will need one or more data files, which are inputted
 directly after the command, e.g. ``tp plot avg-rates mesh.h5``. The

setup.py

@@ -3,10 +3,10 @@
 __name__ =       'ThermoParser'
 __author__ =     'Kieran B. Spooner'
 __copyright__ =  'Copyright Scanlon Materials Theory Group (2024)'
-__version__ =    '3.1.3'
+__version__ =    '3.1.4' # Remember to update the main README header too!
 __maintainer__ = 'Kieran B. Spooner'
 __email__ =      '[email protected]'
-__date__ =       'March 21st 2024'
+__date__ =       'April 1st 2024'
 
 import os
 import setuptools
@@ -63,6 +63,6 @@ def __init__(self, *args, **kwargs):
     install_requires=['click', 'h5py', 'matplotlib', 'numpy', 'pymatgen',
                       'pyyaml', 'scipy', 'setuptools', 'wheel'],
     extras_require={'docs':  ['sphinx', 'sphinx_rtd_theme']},
-    python_requires='>=3.6',
+    python_requires='>=3.8',
     cmdclass={'install': PostInstallMoveFile},
     entry_points={'console_scripts': ['tp = tp.cli.cli:tp_cli']})

tp/__init__.py

@@ -9,6 +9,8 @@
 #        default values and metadata
 #"""
 
+__version__ = '3.1.4'
+
 def docstring_replace(**kwargs):
     def d(f):
         f.__doc__ = f.__doc__.format(**kwargs)

tp/cli/README.rst

@@ -8,8 +8,8 @@ practical differences for the user:
 1. The modular structure: the overarching command is ``tp``, running
    this lists the sub commands, likewise with each of those (e.g. ``tp
    plot``). The full command currently has three parts, e.g. ``tp plot
-   waterfall``, after which you add the arguments. ``--help`` grants
-   information at every step.
+   waterfall``, after which you add the arguments. ``--help`` or ``-h``
+   grants information at every step.
 2. Multiple arguments must use the ``--thing`` every time, i.e. in
    ``argparse`` you may type ``-d a b c``, but in ``click`` you must
    type ``-d a -d b -d c``. The exception is in ``ztdiff``, where kappa

tp/cli/cli.py

@@ -64,18 +64,21 @@
 from tp.cli.options import *
 
 @click.group()
+@adminsitrative_options
 def tp_cli():
     """Command line tools for transport properties."""
     return
 
 
 @tp_cli.group()
+@adminsitrative_options
 def gen():
     """Tools for generating calculation inputs."""
     return
 
 
 @gen.command(no_args_is_help=True)
+@adminsitrative_options
 @kpoints_options
 def kpar(kpoints, mesh, poscar):
     """Suggests KPAR values for VASP.
@@ -99,6 +102,7 @@ def kpar(kpoints, mesh, poscar):
 
 
 @gen.command(no_args_is_help=True)
+@adminsitrative_options
 @kpoints_options
 @click.option('-z', '--zero-kpoints', '--zero-ibzkpt',
               help='IBZKPT file path. Overrides --zero-mesh.',
@@ -137,12 +141,14 @@ def kpoints(kpoints, mesh, poscar, zero_kpoints, zero_mesh, output):
 
 
 @tp_cli.group()
+@adminsitrative_options
 def get():
     """Tools for accessing data."""
     return
 
 
 @get.command('amset', no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('amset_file', nargs=1)
 @click.option('-q', '--quantity',
               help='Quantity to read.',
@@ -270,6 +276,7 @@ def get_amset(amset_file, quantity, dtype, doping, direction, temperature, spin,
     return
 
 @get.command('occupation')
+@adminsitrative_options
 @inputs_function('amset_mesh_file', nargs=1)
 @doping_type_option
 @doping_function()
@@ -340,6 +347,7 @@ def get_occupation(amset_mesh_file, dtype, doping, temperature, spin, poscar):
 
 
 @get.command('boltztrap')
+@adminsitrative_options
 @inputs_function('boltztrap_hdf5', nargs=1)
 @click.option('-q', '--quantity',
               help='Quantity to read.',
@@ -399,6 +407,7 @@ def get_boltztrap(boltztrap_hdf5, quantity, dtype, doping, direction, temperatur
 
 
 @get.command('phono3py', no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('kappa_hdf5', nargs=1)
 @click.option('-q', '--quantity',
               help='Quantity to read.',
@@ -492,6 +501,7 @@ def get_phono3py(kappa_hdf5, quantity, direction, temperature, band, qpoint,
 
 
 @get.command('zt', no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('transport_file', nargs=1)
 @click.option('-k', '--kappa',
               help='Phono3py kappa-mxxx.hdf5.',
@@ -559,12 +569,14 @@ def get_zt(transport_file, kappa, dtype, doping, direction, temperature, max):
 
 
 @tp_cli.group()
+@adminsitrative_options
 def run():
     """Tools for transport properties postprocessing."""
     return
 
 
 @run.command(no_args_is_help=True)
+@adminsitrative_options
 
 @click.option('--tmin',
               help='Set minimum temperature in K. Does not speed up '
@@ -651,12 +663,14 @@ def boltztrap(tmin, tmax, tstep, dmin, dmax, ndope, relaxation_time, lpfac,
 
 
 @tp_cli.group()
+@adminsitrative_options
 def save():
     """Tools for saving data."""
     return
 
 
 @save.command('cumkappa', no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('kappa_hdf5', nargs=1)
 @click.option('--mfp/--frequency',
               help='x-axis quantity.  [default: frequency]',
@@ -690,6 +704,7 @@ def save_cumkappa(kappa_hdf5, mfp, direction, temperature, output, extension):
 
 
 @save.command('kappa', no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('kappa_hdf5', nargs=1)
 @direction_function(multiple=True)
 @click.option('-o', '--output',
@@ -720,6 +735,7 @@ def save_kappa(kappa_hdf5, direction, output):
 
 
 @save.command('zt', no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('transport_file', nargs=1)
 @click.option('-k', '--kappa',
               help='Phono3py kappa-mxxx.hdf5.',
@@ -749,12 +765,14 @@ def save_zt(transport_file, kappa, dtype, direction, interpolate, kind, output):
 
 
 @tp_cli.group()
+@adminsitrative_options
 def plot():
     """Tools for plotting."""
     return
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('mesh_h5')
 @click.option('--mfp/--rate',
               help='Plot mfp instead of rate.  [default: rate]',
@@ -978,6 +996,7 @@ def avg_rates(mesh_h5, mfp, total, x, crt, exclude, doping, direction,
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('kappa_hdf5')
 @click.option('--mfp/--frequency',
               help='x-axis quantity.  [default: frequency]',
@@ -1098,6 +1117,7 @@ def cumkappa(kappa_hdf5, mfp, percent, xmarkers, ymarkers, direction,
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('dos_dat', nargs=1)
 @dos_function()
 @fill_options
@@ -1160,6 +1180,7 @@ def dos(dos_dat, poscar, atoms, sigma, projected, total, total_label,
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @click.option('-k', '--kfile',
               help='Thermal data filename(s). Required for a '
                    '--component of lattice or total.',
@@ -1413,6 +1434,7 @@ def kappa(kfile, efile, component, direction, tmin, tmax, dtype, doping,
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('transport_file', nargs=1)
 @click.option('-z', '--zt',
               help='Target ZT.',
@@ -1489,6 +1511,7 @@ def kappa_target(transport_file, zt, direction, interpolate, kind, colour,
 
 
 @plot.command('phonons', no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('band_yaml')
 @click.option('--bandmin',
               help='Minimum band index.',
@@ -1600,6 +1623,7 @@ def converge_phonons(band_yaml, bandmin, bandmax, colour, alpha, linestyle,
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('transport_file')
 @click.option('-k', '--kfile',
               help='Thermal data filename(s). Required for a --quantity '
@@ -1994,6 +2018,7 @@ def transport(transport_file, kfile, quantity, direction, tmin, tmax, dtype,
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('kappa_hdf5', nargs=1)
 @click.option('-y',
               help='y-axis quantity. Options include frequency, kappa, '
@@ -2149,6 +2174,7 @@ def waterfall(kappa_hdf5, y, x, projected, direction, temperature, colour, alpha
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('band_yaml', nargs=1)
 @inputs_function('kappa_hdf5', nargs=1)
 
@@ -2204,6 +2230,7 @@ def wideband(band_yaml, kappa_hdf5, temperature, poscar, colour, smoothing, styl
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('transport_file', nargs=1)
 @click.option('--pf/--zt',
               help='Power factor instead of ZT.  [default: zt]',
@@ -2280,6 +2307,7 @@ def ztmap(transport_file, pf, kappa, direction, dtype, interpolate, kind,
 
 
 @plot.command(no_args_is_help=True)
+@adminsitrative_options
 @inputs_function('transport_files', nargs=2)
 @click.option('--pf/--zt',
               help='Power factor instead of ZT.  [default: zt]',