pyGNparser

This is a Python wrapper on the GNparser API. Code follow the spirit/approach of the pygbif package, and indeed much of the wrapping utility is copied 1:1 from that repo, thanks @sckott and other contributors.

Installation

Add this line to your application's requirements.txt:

pygnparser

And then execute:

$ pip install -r requirements.txt

Or install it yourself as:

$ pip install pygnparser

Usage

Import the library:

from pygnparser import gnparser

If you have a local installation of gnparser, set the GNPARSER_BASE_URL to the host and port that the service is running on, for example if running locally on port 8787:

GNPARSER_BASE_URL = "http://localhost:8787/"

Without the GNPARSER_BASE_URL environment variable set, the wrapper will default to using the remote API which will perform slower: https://parser.globalnames.org/

---

Parse a scientific name

Parse a scientific name:

>>> result = gnparser('Ursus arctos Linnaeus, 1758') #  => Dictionary

Check if parsed:

>>> result.parsed() #  => Boolean
True

Get parsed quality:

>>> result.quality() #  => Integer
1

Get the genus name:

>>> result.genus() #  => String
'Ursus'

Get the species name:

>>> result.species() #  => String
'arctos'

Get the year:

>>> result.year() #  => String
'1758'

Get the authorship:

>>> result.authorship() #  => String
'(Linnaeus, 1758)'

Get the scientific name without the Latin gender stem:

>>> result.canonical_stemmed() #  => String
'Ursus arct'

Get the parsed name components for a hybrid formula:

>>> result = gnparser('Isoetes lacustris × stricta Gay') #  => Dictionary
>>> result.is_hybrid() #  => Boolean
True
>>> result.hybrid() #  => String
'HYBRID_FORMULA'
>>> result.normalized() #  => String
'Isoetes lacustris × Isoetes stricta Gay'
>>> result.hybrid_formula_ranks() #  => Array
['species', 'species']
>>> res.hybrid_formula_genera() #  => Array
['Isoetes', 'Isoetes']
>>> res.hybrid_formula_species() #  => Array
['lacustris', 'stricta']
>>> res.hybrid_formula_authorship() #  => Array
['', 'Gay']

Parse a scientific name under a specified nomenclatural code:

>>> result = gnparser('Malus domestica \'Fuji\'', code='cultivar')
>>> result.is_cultivar() #  => Boolean
True
>>> result.genus() #  => String
'Malus'
>>> result.species() #  => String
'domestica'
>>> result.cultivar() #  => String
'‘Fuji’'
>>> result.nomenclatural_code() #  => String
'ICNCP'

---

Parse multiple scientific names

Parse multiple scientific names by separating them with \r\n:

results = gnparser('Ursus arctos Linnaeus, 1758\r\nAlces alces (Linnaeus, 1758)\r\nRangifer tarandus (Linnaeus, 1758)\r\nUrsus maritimus (Phipps, 1774') #  => Array

Get the genus of the 1st parsed name in the list:

results[0].genus() #  => String
'Ursus'

---

Deviations

Some extra helpers are included that extend the functionality of GNparser.

1. The page() method gets the page number out of the unparsed tail:

>>> result = gnparser('Ursus arctos Linnaeus, 1758: 81')
result.page()  # => String
'81'

2. The authorship() method returns a formatted authorship string depending on the number of authors. If it is one author with a year, it will return as Smith, 1970. For two authors and a year it will return as Smith & Johnson, 1970. For three authors it will return as Smith, Johnson & Jones, 1970. Any additional authors beyond 3 will be comma separated with the last author included with an ampersand.

>>> result = gnparser('Aus bus cus Smith, Johnson, & Jones, 1970')
result.authorship()  # => String
'Smith, Johnson & Jones, 1970'

3. The infraspecies() method will return the infraspecies name. Currently there is no special methods for ranks lower than trinomials but you can access them with the infraspecies_details() method. Please open an issue if you need it added.

>>> result = gnparser('Aus bus cus')
result.infraspecies()  # => String
'cus'

4. If you wish to abbreviate author strings with over a certain threshold of authors as et al. beyond a certain cutoff you can use the parameter et_al_cutoff=3 on the authorship methods, which would re-format Smith, Jones & Anderson, 1999 into Smith et al., 1999. By default et al. formatting is disabled.

>>> result = gnparser('Aus bus cus (Smith, Anderson, Jones, O\'Brian & Peters in Richards, Shultz, Anderson & Smith, 1999) Ryan in Anderson, Smith, & Jones, 2000')
>>> result.authorship(et_al_cutoff=3) # => String
'(Smith et al. in Richards et al., 1999) Ryan in Anderson et al., 2000'
>>> res.original_authorship(et_al_cutoff=3) # => String
'Smith et al. in Richards et al., 1999'
>>> res.combination_authorship(et_al_cutoff=3) # => String
'Ryan in Anderson et al., 2000'

---

Other GNparser Libraries

• Node.js: node-gnparser
• R: rgnparser
• Ruby Gem: biodiversity

---

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/gnames/pygnparser. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

---

Development

After checking out the repo, change into the package directory cd pygnparser, run pip install . to install the package, and pip install -r requirements.txt to install the dependencies. Then, run pytest to run the tests. You can also run bin/console for an interactive Python prompt that will allow you to experiment with the above example commands.

---

License

The package is available as open source under the terms of the MIT license. You can learn more about the MIT license on Wikipedia and compare it with other open source licenses at the Open Source Initiative.

---

Code of Conduct

Everyone interacting in the pyGNparser project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.