[Python-ideas] Add citation() to site.py

[Steven D'Aprano]

The standard site.py module adds pseudo-builtins:

    copyright
    credits
    exit
    help
    license
    quit


I suggest one more: citation().

Python is being used heavily in scientific and academic fields, where it 
is often the convention to provide citations and references to the 
software used. The question of how to cite Python comes up from time to 
time, e.g.:

https://mail.python.org/pipermail/tutor/2016-March/108460.html

http://academia.stackexchange.com/questions/5482/how-do-i-reference-the-python-programming-language-in-a-thesis-or-a-paper

http://www.gossamer-threads.com/lists/python/python/105846

http://grokbase.com/t/python/python-list/04684fggwd/citing-python


I think that having a standard answer available for this question is 
good practice, and will help strength Python's position as a good 
scientific language.

SciPy, SymPy and iPython all document how they prefer to be cited:

https://scipy.org/citing.html

https://github.com/sympy/sympy#citation

http://ipython.org/citing.html


As do other languages such as Mathematica:

http://support.wolfram.com/kb/472


But I think it would be a good idea to emulate the R language, which 
provides a function that gives the prefered citation. At the R prompt:


> citation()

To cite R in publications use:

  R Core Team (2014). R: A language and environment for statistical
  computing. R Foundation for Statistical Computing, Vienna, Austria.
  URL http://www.R-project.org/.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {R: A Language and Environment for Statistical Computing},
    author = {{R Core Team}},
    organization = {R Foundation for Statistical Computing},
    address = {Vienna, Austria},
    year = {2014},
    url = {http://www.R-project.org/},
  }

We have invested a lot of time and effort in creating R, please cite it
when using it for data analysis. See also ‘citation("pkgname")’ for
citing R packages.


* * * 

If you provide a package name such as "splines", the R's output is 
the same except that the first line starts with:

"The ‘splines’ package is part of R."

(I don't have any third-party packages installed to test, but presumably 
they will offer customised output.)

My suggestion is that we follow R's lead and add a citation() function 
to site.py which gives a suggested, standard, citation string that 
people can copy. Obviously we cannot expect to match all standard 
formats, but we can provide one and folks can convert to the format 
their university of journal requires. (Converting between academic 
reference styles is out of scope of this proposal.)

The initial implementation might look something like this:


year = platform.python_build()[1].split()[2]
vers = platform.python_version()
_CITE = """\
To cite Python in publications, please use:

  Python Core Team ({}). Python {}: A dynamic, open 
  source programming language. Python Software Foundation.
  URL https://www.python.org/.

""".format(year, vers)

def citation():
    print(_CITE)


Or perhaps it should use the same implementation as copyright, credits 
and license.


Thoughts?


-- 
Steve