reference-handler 0.9.1__tar.gz → 0.9.2__tar.gz

reference_handler-0.9.2/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: reference_handler
+Version: 0.9.2
+Author: MolSSI
+Author-email: meliseo@vt.edu
+License: BSD-3-Clause
+Keywords: reference_handler
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bibtexparser<2
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+
+reference_handler
+==============================
+[//]: # (Badges)
+[![Travis Build Status](https://travis-ci.org/molssi/reference_handler.png)](https://travis-ci.org/molssi/reference_handler)
+[![AppVeyor Build status](https://ci.appveyor.com/api/projects/status/REPLACE_WITH_APPVEYOR_LINK/branch/master?svg=true)](https://ci.appveyor.com/project/molssi/reference_handler/branch/master)
+[![codecov](https://codecov.io/gh/molssi/reference_handler/branch/master/graph/badge.svg)](https://codecov.io/gh/molssi/reference_handler/branch/master)
+[![Documentation Status](https://readthedocs.org/projects/reference-handler/badge/?version=latest)](https://reference-handler.readthedocs.io/en/latest/?badge=latest)
+
+A python package for scientific software citation.
+
+## Motivation & goal
+
+An appropriate recognition of the value of the scientific software on an equal footing with 
+scholarly manuscripts and datasets is dependent upon the realization and promotion of
+community guidelines and best practices for software citation. Such practices can improve 
+reproducibility and validation of the scientific discoveries, encourage software reuse and 
+boost collaborative efforts.
+
+## Package overview
+
+The *reference handler* is comprised of two core parts:
+
+**1. Central SQLite3 database** which contains two tables:
+(i) the *citation* table which hosts all essential data pertinent to each unique citation,
+such as the raw citation text and its ID number, and (ii) the *context* table which contains
+information about the context in which a given citation was used. For instance, the function
+where the citation was used or the number of times the citation was "mentioned"
+by any function of your Python package. Since each citation can have many contexts, a
+one-to-many relationship exist between the *citation* and the *context* tables, respectively.
+
+**2. Functions to ease the interaction with central database.** Examples are a function
+to cite a desired reference or a function to dump the contents of the database into a
+`.bib` file for subsequent compilation using BibTeX.
+
+## Audience
+
+* 1. Method and scientific software developers.
+* 2. Computational molecular science practitioners
+
+## Main features
+
+* Automatic and seamless runtime citation to all adopted software modules in the executed program
+* Managing citations within complex workflows and interoperable environments conveniently with simple syntax and APIs
+* Providing context and number of counts for all modules used in the executed application
+* Prioritization of all cited modules at different levels
+* Recommended citation style according to the community guidelines and best practices
+* Exporting references as databases and formatted documents in BibTeX and RIS
+
+## Installation
+
+* **Step 1**: Clone this repository on a host machine:
+
+```bash
+$ git clone git@github.com:MolSSI/reference_handler.git
+```
+
+* **Step 2**: Change the current directory to *reference_handler's* root directory:
+
+```bash
+$ cd <path-to-reference-handler-root-directory>/reference_handler
+```
+
+* **Step 3**: Create a Conda environment with *python 3.9* and *pip*:
+
+```bash
+$ conda create -n <env-name> python=3.9 pip
+```
+
+replace the `<env-name>` with the desired name of your environment.
+
+* **Step 4**: Activate your conda environment:
+
+```bash
+$ conda activate <env-name>
+```
+
+* **Step 5**: Run the following command to install *bibtexparser 1.2.0* using pip
+within your conda environment
+
+```bash
+$ pip install bibtexparser==1.2.0 
+```
+
+* **Step 6**: Finally, run the following command to install *reference_handler* in
+your conda environment
+
+```bash
+$ make install 
+```
+
+* **Step 7 (optional)**: Make sure all tests run without errors
+
+```bash
+$ pytest -v
+```
+
+## Minimal example
+
+```python
+import reference_handler
+
+lj_citation = """
+@article{lj1924,
+author = {J. E. Jones  and Sydney Chapman },
+title = {On the determination of molecular fields. \&\#x2014;II. From the equation of state of a gas},
+journal = {Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character},
+volume = {106},
+number = {738},
+pages = {463-477},
+year = {1924},
+doi = {10.1098/rspa.1924.0082},
+}
+"""
+
+def lennard_jones(sigma, epsilon, rij):
+    rf.cite(raw=lj_citation, alias='lj_citation', module='lennard_jones',
+        level=1, note='The first version of the Lennard-Jones potential')
+    sig_by_r6 = (sigma / rij ** 6)
+    sig_by_r12 = (sig_by_r6 ** 2)
+    return 4.0 * epsilon * (sig_by_r12 - sig_by_r6)
+
+rf = reference_handler.Reference_Handler('database.db')
+
+sigma = 3.54
+epsilon = 98.0
+rij = 20.0
+
+lj_energy = lennard_jones(sigma, epsilon, rij)
+
+rf.dump(outfile='bibliography.bib')
+```
+
+## Documentation
+
+The documentation is under development. Please check back later.
+
+## References
+
+* [Katz, D. S., Chue Hong, N. P., Clark T., Muench, A., Stall, S., Bouquin, D., Cannon, M., Edmunds, S., Faez, T., Farmer, R., \
+Feeney, P., Fenner, M., Friedman, M., Grenier, G., Harrison, M., Heber, J., Leary, A., MacCallum, C., Murray, H., ... Yeston, J. \
+(2020) Recognizing the value of software: a software citation guide. F1000 Research. https://doi.org/10.12688/f1000research.26932.2](https://doi.org/10.12688/f1000research.26932.2)
+
+* [Smith A. M., Katz D. S., Niemeyer K. E., FORCE11 Software Citation Working Group.2016. \
+Software citation principles. PeerJ Computer Science 2:e86 https://doi.org/10.7717/peerj-cs.86](https://doi.org/10.7717/peerj-cs.86)
+
+## Copyright
+
+Copyright (c) 2019-2022, MolSSI
+
+## Acknowledgements
+ 
+Project based on the
+[Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.0.

reference_handler-0.9.2/README.md

@@ -0,0 +1,153 @@
+reference_handler
+==============================
+[//]: # (Badges)
+[![Travis Build Status](https://travis-ci.org/molssi/reference_handler.png)](https://travis-ci.org/molssi/reference_handler)
+[![AppVeyor Build status](https://ci.appveyor.com/api/projects/status/REPLACE_WITH_APPVEYOR_LINK/branch/master?svg=true)](https://ci.appveyor.com/project/molssi/reference_handler/branch/master)
+[![codecov](https://codecov.io/gh/molssi/reference_handler/branch/master/graph/badge.svg)](https://codecov.io/gh/molssi/reference_handler/branch/master)
+[![Documentation Status](https://readthedocs.org/projects/reference-handler/badge/?version=latest)](https://reference-handler.readthedocs.io/en/latest/?badge=latest)
+
+A python package for scientific software citation.
+
+## Motivation & goal
+
+An appropriate recognition of the value of the scientific software on an equal footing with 
+scholarly manuscripts and datasets is dependent upon the realization and promotion of
+community guidelines and best practices for software citation. Such practices can improve 
+reproducibility and validation of the scientific discoveries, encourage software reuse and 
+boost collaborative efforts.
+
+## Package overview
+
+The *reference handler* is comprised of two core parts:
+
+**1. Central SQLite3 database** which contains two tables:
+(i) the *citation* table which hosts all essential data pertinent to each unique citation,
+such as the raw citation text and its ID number, and (ii) the *context* table which contains
+information about the context in which a given citation was used. For instance, the function
+where the citation was used or the number of times the citation was "mentioned"
+by any function of your Python package. Since each citation can have many contexts, a
+one-to-many relationship exist between the *citation* and the *context* tables, respectively.
+
+**2. Functions to ease the interaction with central database.** Examples are a function
+to cite a desired reference or a function to dump the contents of the database into a
+`.bib` file for subsequent compilation using BibTeX.
+
+## Audience
+
+* 1. Method and scientific software developers.
+* 2. Computational molecular science practitioners
+
+## Main features
+
+* Automatic and seamless runtime citation to all adopted software modules in the executed program
+* Managing citations within complex workflows and interoperable environments conveniently with simple syntax and APIs
+* Providing context and number of counts for all modules used in the executed application
+* Prioritization of all cited modules at different levels
+* Recommended citation style according to the community guidelines and best practices
+* Exporting references as databases and formatted documents in BibTeX and RIS
+
+## Installation
+
+* **Step 1**: Clone this repository on a host machine:
+
+```bash
+$ git clone git@github.com:MolSSI/reference_handler.git
+```
+
+* **Step 2**: Change the current directory to *reference_handler's* root directory:
+
+```bash
+$ cd <path-to-reference-handler-root-directory>/reference_handler
+```
+
+* **Step 3**: Create a Conda environment with *python 3.9* and *pip*:
+
+```bash
+$ conda create -n <env-name> python=3.9 pip
+```
+
+replace the `<env-name>` with the desired name of your environment.
+
+* **Step 4**: Activate your conda environment:
+
+```bash
+$ conda activate <env-name>
+```
+
+* **Step 5**: Run the following command to install *bibtexparser 1.2.0* using pip
+within your conda environment
+
+```bash
+$ pip install bibtexparser==1.2.0 
+```
+
+* **Step 6**: Finally, run the following command to install *reference_handler* in
+your conda environment
+
+```bash
+$ make install 
+```
+
+* **Step 7 (optional)**: Make sure all tests run without errors
+
+```bash
+$ pytest -v
+```
+
+## Minimal example
+
+```python
+import reference_handler
+
+lj_citation = """
+@article{lj1924,
+author = {J. E. Jones  and Sydney Chapman },
+title = {On the determination of molecular fields. \&\#x2014;II. From the equation of state of a gas},
+journal = {Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character},
+volume = {106},
+number = {738},
+pages = {463-477},
+year = {1924},
+doi = {10.1098/rspa.1924.0082},
+}
+"""
+
+def lennard_jones(sigma, epsilon, rij):
+    rf.cite(raw=lj_citation, alias='lj_citation', module='lennard_jones',
+        level=1, note='The first version of the Lennard-Jones potential')
+    sig_by_r6 = (sigma / rij ** 6)
+    sig_by_r12 = (sig_by_r6 ** 2)
+    return 4.0 * epsilon * (sig_by_r12 - sig_by_r6)
+
+rf = reference_handler.Reference_Handler('database.db')
+
+sigma = 3.54
+epsilon = 98.0
+rij = 20.0
+
+lj_energy = lennard_jones(sigma, epsilon, rij)
+
+rf.dump(outfile='bibliography.bib')
+```
+
+## Documentation
+
+The documentation is under development. Please check back later.
+
+## References
+
+* [Katz, D. S., Chue Hong, N. P., Clark T., Muench, A., Stall, S., Bouquin, D., Cannon, M., Edmunds, S., Faez, T., Farmer, R., \
+Feeney, P., Fenner, M., Friedman, M., Grenier, G., Harrison, M., Heber, J., Leary, A., MacCallum, C., Murray, H., ... Yeston, J. \
+(2020) Recognizing the value of software: a software citation guide. F1000 Research. https://doi.org/10.12688/f1000research.26932.2](https://doi.org/10.12688/f1000research.26932.2)
+
+* [Smith A. M., Katz D. S., Niemeyer K. E., FORCE11 Software Citation Working Group.2016. \
+Software citation principles. PeerJ Computer Science 2:e86 https://doi.org/10.7717/peerj-cs.86](https://doi.org/10.7717/peerj-cs.86)
+
+## Copyright
+
+Copyright (c) 2019-2022, MolSSI
+
+## Acknowledgements
+ 
+Project based on the
+[Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.0.

{reference_handler-0.9.1 → reference_handler-0.9.2}/reference_handler/__init__.py

@@ -12,6 +12,6 @@ from .latex_utf8 import encode_latex  # noqa: F401
 from ._version import get_versions
 
 versions = get_versions()
-__version__ = versions['version']
-__git_revision__ = versions['full-revisionid']
+__version__ = versions["version"]
+__git_revision__ = versions["full-revisionid"]
 del get_versions, versions

{reference_handler-0.9.1 → reference_handler-0.9.2}/reference_handler/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2021-05-05T14:18:44-0400",
+ "date": "2026-09-20T19:28:51-0400",
  "dirty": false,
  "error": null,
- "full-revisionid": "2c570bee48e7419570bf15fd999fa83a68c0453a",
- "version": "0.9.1"
+ "full-revisionid": "e2f9c6eab9da1597c472cc0168e1e3dc580a35fc",
+ "version": "0.9.2"
 }
 '''  # END VERSION_JSON
 

{reference_handler-0.9.1 → reference_handler-0.9.2}/reference_handler/latex_utf8.py

@@ -70,54 +70,53 @@ import re
 import typing
 import unicodedata
 
-alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
 
 # LaTeX characters in accent macros of form \<char>{<letter>}, i.e. \"{u}
 accent = {
-    '"': '\N{Combining Diaeresis}',
-    "'": '\N{Combining Acute Accent}',
-    '.': '\N{Combining Dot Above}',
-    '=': '\N{Combining Macron}',
-    '^': '\N{Combining Circumflex Accent}',
-    '`': '\N{Combining Grave Accent}',
-    '|': '\N{Combining Vertical Line Above}',
-    '~': '\N{Combining Tilde}',
-    'b': '\N{Combining Macron Below}',
-    'c': '\N{Combining Cedilla}',
-    'C': '\N{Combining Double Grave Accent}',
-    'd': '\N{Combining Dot Below}',
-    'f': '\N{Combining Inverted Breve}',
-    'h': '\N{Combining Hook Above}',
-    'H': '\N{Combining Double Acute Accent}',
-    'k': '\N{Combining Ogonek}',
-    'r': '\N{Combining Ring Above}',
-    't': '\N{Combining Double Inverted Breve}',
-    'u': '\N{Combining Breve}',
-    'U': '\N{Combining Double Vertical Line Above}',
-    'v': '\N{Combining Caron}'
+    '"': "\N{COMBINING DIAERESIS}",
+    "'": "\N{COMBINING ACUTE ACCENT}",
+    ".": "\N{COMBINING DOT ABOVE}",
+    "=": "\N{COMBINING MACRON}",
+    "^": "\N{COMBINING CIRCUMFLEX ACCENT}",
+    "`": "\N{COMBINING GRAVE ACCENT}",
+    "|": "\N{COMBINING VERTICAL LINE ABOVE}",
+    "~": "\N{COMBINING TILDE}",
+    "b": "\N{COMBINING MACRON BELOW}",
+    "c": "\N{COMBINING CEDILLA}",
+    "C": "\N{COMBINING DOUBLE GRAVE ACCENT}",
+    "d": "\N{COMBINING DOT BELOW}",
+    "f": "\N{COMBINING INVERTED BREVE}",
+    "h": "\N{COMBINING HOOK ABOVE}",
+    "H": "\N{COMBINING DOUBLE ACUTE ACCENT}",
+    "k": "\N{COMBINING OGONEK}",
+    "r": "\N{COMBINING RING ABOVE}",
+    "t": "\N{COMBINING DOUBLE INVERTED BREVE}",
+    "u": "\N{COMBINING BREVE}",
+    "U": "\N{COMBINING DOUBLE VERTICAL LINE ABOVE}",
+    "v": "\N{COMBINING CARON}",
 }
 
 # The regexp to detect the LaTeX accent commands. The two added characters
 # are the dotless i and j.
-accent_re = re.compile(
-    r'\\([' + ''.join(accent.keys()) + r']){([a-zA-Z\u0131\u0237])}'
-)
+accent_re = re.compile(r"\\([" + "".join(accent.keys()) + r"]){([a-zA-Z\u0131\u0237])}")
 
 # Invert the accent dictionary for each letter in the alphabet to make
 # a dictionary of LaTeX encodings.
 encoding = {}
 for key, val in accent.items():
     for char in list(alphabet):
-        encoding[char + val] = '\\' + key + '{' + char + '}'
+        encoding[char + val] = "\\" + key + "{" + char + "}"
         # handle any precombined versions of the character
-        string = unicodedata.normalize('NFC', char + val)
+        string = unicodedata.normalize("NFC", char + val)
         if len(string) == 1:
             encoding[string] = encoding[char + val]
     for char in [
-        '\N{Latin Small Letter Dotless I}', '\N{Latin Small Letter Dotless J}'
+        "\N{LATIN SMALL LETTER DOTLESS I}",
+        "\N{LATIN SMALL LETTER DOTLESS J}",
     ]:
-        encoding[char + val] = r'\%s{%s}' % (key, char)
-        string = unicodedata.normalize('NFC', char + val)
+        encoding[char + val] = r"\%s{%s}" % (key, char)
+        string = unicodedata.normalize("NFC", char + val)
         # These characters have no precombined versions, but check anyway
         if len(string) == 1:
             encoding[string] = encoding[char + val]
@@ -137,20 +136,20 @@ def _decode_latex_accent(match: typing.Match) -> str:
 
 # LaTeX single character symbols
 symbol = {
-    'i': '\N{Latin Small Letter Dotless I}',
-    'j': '\N{Latin Small Letter Dotless J}',
-    'l': '\N{Latin Small Letter L With Stroke}',
-    'L': '\N{Latin Capital Letter L With Stroke}',
-    'o': '\N{Latin Small Letter O With Stroke}',
-    'O': '\N{Latin Capital Letter O With Stroke}'
+    "i": "\N{LATIN SMALL LETTER DOTLESS I}",
+    "j": "\N{LATIN SMALL LETTER DOTLESS J}",
+    "l": "\N{LATIN SMALL LETTER L WITH STROKE}",
+    "L": "\N{LATIN CAPITAL LETTER L WITH STROKE}",
+    "o": "\N{LATIN SMALL LETTER O WITH STROKE}",
+    "O": "\N{LATIN CAPITAL LETTER O WITH STROKE}",
 }
 
 # The regexp to detect the LaTeX commands for special characters
-symbol_re = re.compile(r'\\([' + ''.join(symbol.keys()) + '])')
+symbol_re = re.compile(r"\\([" + "".join(symbol.keys()) + "])")
 
 # Invert the symbol dictionary to make a dictionary of LaTeX encodings.
 for key, val in symbol.items():
-    encoding[val] = '\\' + key
+    encoding[val] = "\\" + key
 
 
 def _decode_latex_symbol(match: typing.Match) -> str:
@@ -166,10 +165,10 @@ def _decode_latex_symbol(match: typing.Match) -> str:
 
 
 # LaTeX dashes
-dash = {'--': '\N{EN Dash}', '---': '\N{EM Dash}'}
+dash = {"--": "\N{EN DASH}", "---": "\N{EM DASH}"}
 
 # The regexp to detect the LaTeX commands for dashes
-dash_re = re.compile(r'([^-]?)(-{2,3})([^-]?)')
+dash_re = re.compile(r"([^-]?)(-{2,3})([^-]?)")
 
 # Invert the dictionary tomake a dictionary of LaTeX encodings.
 for key, val in dash.items():
@@ -205,13 +204,11 @@ def decode_latex(text: str) -> str:
     """
 
     return brace_re.sub(
-        r'\1',
+        r"\1",
         accent_re.sub(
             _decode_latex_accent,
-            symbol_re.sub(
-                _decode_latex_symbol, dash_re.sub(_decode_latex_dash, text)
-            )
-        )
+            symbol_re.sub(_decode_latex_symbol, dash_re.sub(_decode_latex_dash, text)),
+        ),
     )
 
 
@@ -228,7 +225,7 @@ def encode_latex(text: str) -> str:
     """
 
     # Map the double character representations
-    text2 = ''
+    text2 = ""
     char1 = text[0]
     i = 1
     len_text = len(text)
@@ -250,7 +247,7 @@ def encode_latex(text: str) -> str:
         text2 += char1
 
     # Map the single characters representations
-    result = ''
+    result = ""
     for char in list(text2):
         if char in encoding:
             result += encoding[char]
@@ -260,7 +257,7 @@ def encode_latex(text: str) -> str:
     return result
 
 
-if __name__ == '__main__':  # pragma: no cover
+if __name__ == "__main__":  # pragma: no cover
     text = r"""
 (Vorlova_2015) Barbora Vorlov{\'{a}} and Dana Nachtigallov{\'{a}} and Jana
 Jir{\'{a}}skov{\'{a}}-Van{\'{\i}}{\v{c}}kov{\'{a}} and Haresh Ajani and Petr