feat: Add utility to get software citation and CLI interface (#1210)

* Add citation utility to pyhf
* Add CLI functionality to print out pyhf citation

Author: kratsg

.bumpversion.cfg

@@ -9,7 +9,7 @@ tag = True
 
 [bumpversion:file:README.rst]
 
-[bumpversion:file:docs/bib/preferred.bib]
+[bumpversion:file:src/pyhf/data/citation.bib]
 
 [bumpversion:file:.zenodo.json]
 

docs/bib/preferred.bib

@@ -0,0 +1 @@
+../../src/pyhf/data/citation.bib

docs/bib/preferred.bib

@@ -6,13 +6,31 @@
 from ..version import __version__
 from . import rootio, spec, infer, patchset, complete
 from ..contrib import cli as contrib
+from .. import utils
 
 logging.basicConfig()
 log = logging.getLogger(__name__)
 
 
+def _print_citation(ctx, param, value):
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(utils.citation())
+    ctx.exit()
+
+
 @click.group(context_settings=dict(help_option_names=['-h', '--help']))
 @click.version_option(version=__version__)
+@click.option(
+    "--cite",
+    "--citation",
+    help="Print the bibtex citation for this software",
+    default=False,
+    is_flag=True,
+    callback=_print_citation,
+    expose_value=False,
+    is_eager=True,
+)
 def pyhf():
     """Top-level CLI entrypoint."""
 

src/pyhf/cli/cli.py

@@ -0,0 +1,7 @@
+@software{pyhf,
+  author = "{Heinrich, Lukas and Feickert, Matthew and Stark, Giordon}",
+  title = "{pyhf: v0.5.3}",
+  version = {0.5.3},
+  doi = {10.5281/zenodo.1169739},
+  url = {https://github.com/scikit-hep/pyhf},
+}

src/pyhf/data/citation.bib

@@ -132,3 +132,33 @@ def remove_prefix(text, prefix):
     if text.startswith(prefix):
         return text[len(prefix) :]
     return text
+
+
+def citation(oneline=False):
+    """
+    Get the bibtex citation for pyhf
+
+    Example:
+
+        >>> import pyhf
+        >>> pyhf.utils.citation(True)
+        '@software{pyhf,  author = "{Heinrich, Lukas and Feickert, Matthew and Stark, Giordon}",  title = "{pyhf: v0.5.3}",  version = {0.5.3},  doi = {10.5281/zenodo.1169739},  url = {https://github.com/scikit-hep/pyhf},}'
+
+    Keyword Args:
+        oneline (:obj:`bool`): Whether to provide citation with new lines (default) or as a one-liner.
+
+    Returns:
+        citation (:obj:`str`): The citation for this software
+    """
+    path = Path(
+        pkg_resources.resource_filename(
+            __name__, str(Path('data').joinpath('citation.bib'))
+        )
+    )
+    with path.open() as fp:
+        # remove end-of-file newline if there is one
+        data = fp.read().strip()
+
+    if oneline:
+        data = ''.join(data.splitlines())
+    return data

src/pyhf/utils.py

@@ -24,6 +24,21 @@ def test_version(script_runner):
     assert elapsed < 1.0
 
 
+@pytest.mark.parametrize("flag", ["--cite", "--citation"])
+def test_citation(script_runner, flag):
+    command = f'pyhf {flag}'
+    start = time.time()
+    ret = script_runner.run(*shlex.split(command))
+    end = time.time()
+    elapsed = end - start
+    assert ret.success
+    assert ret.stdout.startswith('@software{pyhf,')
+    # ensure there's not \n\n at the end
+    assert ret.stdout.endswith('}\n')
+    # make sure it took less than a second
+    assert elapsed < 1.0
+
+
 # see test_import.py for the same (detailed) test
 def test_import_prepHistFactory(tmpdir, script_runner):
     temp = tmpdir.join("parsed_output.json")

tests/test_scripts.py

@@ -64,3 +64,11 @@ def test_remove_prefix():
     assert pyhf.utils.remove_prefix('abcDEF123', 'abc') == 'DEF123'
     assert pyhf.utils.remove_prefix('abcDEF123', 'Abc') == 'abcDEF123'
     assert pyhf.utils.remove_prefix('abcDEF123', '123') == 'abcDEF123'
+
+
+@pytest.mark.parametrize('oneline', [False, True])
+def test_citation(oneline):
+    citation = pyhf.utils.citation(oneline)
+    assert citation
+    if oneline:
+        assert '\n' not in citation