# Bananompy
This is a Python wrapper on the [Bionomia](https://bionomia.net) API. Code follow the spirit/approach of the [pygbif](https://github.com/gbif/pygbif/graphs/contributors) package, and indeed much of the wrapping utility is copied 1:1 from that repo, thanks [@sckott](https://github.com/sckott) and other [contributors](https://github.com/gbif/pygbif/graphs/contributors).
## Installation
Add this line to your application's requirements.txt:
```python
bananompy
```
And then execute:
$ pip install -r requirements.txt
Or install it yourself as:
$ pip install bananompy
## Usage
Import the library:
```
import bananompy
```
---
### Suggest Collector Names
Get collector name suggestions with a limit of 5:
```python
bananompy.suggest('Smith, Ja', limit=5) # => MultiJson object
```
Filter suggestions to only public profiles
```python
bananompy.suggest('Smith, Ja', is_public=True) # => MultiJson object
```
Filter suggestions to only people that have occurrences associated with them:
```python
bananompy.suggest('Smith, Ja', has_occurrences=True) # => MultiJson object
```
---
### Search Collectors
Search for a collector by name:
```python
bananompy.person.search('Mary Agnes Chase') # => MultiJson object
```
Filter the people search by taxonomic families_collected or taxonomic families_identified. If strict is set to true, then matches must include the taxonomic families.
```python
bananompy.person.search('Mary Agnes Chase', families_collected='Poaceae', strict=True) # => MultiJson object
```
```python
bananompy.person.search('Mary Agnes Chase', families_identified='Poaceae', strict=True) # => MultiJson object
```
Filter the search by whether the person was living on the specimen collection/identification date. If strict is set to true, it requires that they were alive on the date.
```python
bananompy.person.search('Smith', date='1580-01-02', strict=True) # => MultiJson object
```
Setting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.
```python
bananompy.person.search('Smith', callback='myFunction') # => JSON-P object
```
Use the page parameter for pagination of the search results:
```python
bananompy.person.search('Smith', page=2) # => MultiJson object
```
---
### Search Occurrences
Search for occurrences by [GBIF](https://gbif.org) [datasetID](https://www.gbif.org/dataset/f86a681d-7db8-483b-819a-248def18b70a) and [occurrenceID](https://www.gbif.org/occurrence/1804069383):
```python
bananompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0') # => MultiJson object
```
Setting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.
```python
bananompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0', callback='myFunction') # => JSON-P object
```
---
### Collectors
Get a person's profile by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers:
```python
bananompy.person.get('0000-0001-7618-5230') # => JSON-LD object
```
---
### Specimens
Get a person's specimens by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers. Use the page parameter for pagination.
```python
bananompy.person.get('0000-0001-7618-5230', specimens=True) # => JSON-LD object
```
```python
bananompy.person.get('0000-0001-7618-5230', specimens=True, csv=True) # => comma-separated values
```
---
### Occurrences
Get an occurrence with a [GBIF](https://www.gbif.org/occurrence/search) occurrenceID:
```python
bananompy.occurrence.get('477976412') # => JSON-LD object
```
---
### Parsing human names
**Note:** [Bionomia](https://bionomia.net) provides a RESTful API for the human name parsing [dwc_agent](https://rubygems.org/gems/dwc_agent) gem which uses the [namae](https://rubygems.org/gems/namae) gem, and you likely will get better performance using those gems directly if parsing a large number of human names. A similar library in Python to the namae Ruby gem is [nameparser](https://github.com/derek73/python-nameparser).
Parse authorships with names separated by `;` and each authorship set separated by `\r\n`:
```python
bananompy.parse(names='Henry Robert Nicollon des Abbayes; Groom Q\r\nMrs. John Errol Chandos Aberdeen') # => MultiJson object
```
---
### Agent Strings
Agent strings are people names from occurrence labels that have not been associated with a person's identifier yet.
**Note:** There is no restful API for agent strings, so these methods use beautifulsoup4 and the lxml parser to scrape the values from the Bionomia website.
Get a random list of agent strings:
```python
bananompy.agent.search()
```
Search for an agent string with the query, q:
```python
bananompy.agent.search(q='Mary Agnes')
```
Get an agent string's occurrences by ID (***Warning:*** The agent string identifiers are temporary and change every 2 weeks when new agent strings are imported into Bionomia and the website also goes down with a 503 error during agent string updates.)
```python
bananompy.agent.get('4746282')
```
---
## Development
After checking out the repo, change into the package directory `cd bananompy`, 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.
## Other Bionomia Libraries
* Ruby Gem: [bananomia](https://github.com/SpeciesFileGroup/bananomia)
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/SpeciesFileGroup/bananompy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/SpeciesFileGroup/bananompy/blob/main/CODE_OF_CONDUCT.md).
## License
The package is available as open source under the terms of the [NCSA/Illinois](https://github.com/SpeciesFileGroup/bananompy/blob/main/LICENSE.txt) license. You can learn more about the NCSA license on [Wikipedia](https://en.wikipedia.org/wiki/University_of_Illinois/NCSA_Open_Source_License) and compare it with other open source licenses at the [Open Source Initiative](https://opensource.org/license/uoi-ncsa-php/).
## Code of Conduct
Everyone interacting in the Bananompy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/SpeciesFileGroup/bananompy/blob/main/CODE_OF_CONDUCT.md).
## [Unreleased]
## [0.1.0] - 2023-10-27
- Initial release
Raw data
{
"_id": null,
"home_page": "http://github.com/speciesfilegroup/bananompy",
"name": "bananompy",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "bionomia,biodiversity,collectors,specimens,API,web-services,species,natural history,taxonomists,biologists",
"author": "Geoff Ower",
"author_email": "gdower@illinois.edu",
"download_url": "https://files.pythonhosted.org/packages/c8/0e/09b0aabe981fb409a37e0b91636705c9e7da98236feca593c8ad3f6ded49/bananompy-0.0.1.tar.gz",
"platform": null,
"description": "# Bananompy\n\n\n\nThis is a Python wrapper on the [Bionomia](https://bionomia.net) API. Code follow the spirit/approach of the [pygbif](https://github.com/gbif/pygbif/graphs/contributors) package, and indeed much of the wrapping utility is copied 1:1 from that repo, thanks [@sckott](https://github.com/sckott) and other [contributors](https://github.com/gbif/pygbif/graphs/contributors).\n\n## Installation\n\nAdd this line to your application's requirements.txt:\n\n```python\nbananompy\n```\n\nAnd then execute:\n\n $ pip install -r requirements.txt\n\nOr install it yourself as:\n\n $ pip install bananompy\n\n## Usage\n\n\nImport the library:\n```\nimport bananompy\n```\n\n---\n### Suggest Collector Names\nGet collector name suggestions with a limit of 5:\n```python\nbananompy.suggest('Smith, Ja', limit=5) # => MultiJson object\n```\nFilter suggestions to only public profiles\n```python\nbananompy.suggest('Smith, Ja', is_public=True) # => MultiJson object\n```\nFilter suggestions to only people that have occurrences associated with them:\n```python\nbananompy.suggest('Smith, Ja', has_occurrences=True) # => MultiJson object\n```\n\n---\n### Search Collectors\nSearch for a collector by name:\n```python\nbananompy.person.search('Mary Agnes Chase') # => MultiJson object\n```\n\nFilter the people search by taxonomic families_collected or taxonomic families_identified. If strict is set to true, then matches must include the taxonomic families.\n```python\nbananompy.person.search('Mary Agnes Chase', families_collected='Poaceae', strict=True) # => MultiJson object\n```\n```python\nbananompy.person.search('Mary Agnes Chase', families_identified='Poaceae', strict=True) # => MultiJson object\n```\n\nFilter the search by whether the person was living on the specimen collection/identification date. If strict is set to true, it requires that they were alive on the date.\n```python\nbananompy.person.search('Smith', date='1580-01-02', strict=True) # => MultiJson object\n```\n\nSetting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.\n```python\nbananompy.person.search('Smith', callback='myFunction') # => JSON-P object\n```\n\nUse the page parameter for pagination of the search results:\n```python\nbananompy.person.search('Smith', page=2) # => MultiJson object\n```\n\n---\n### Search Occurrences\nSearch for occurrences by [GBIF](https://gbif.org) [datasetID](https://www.gbif.org/dataset/f86a681d-7db8-483b-819a-248def18b70a) and [occurrenceID](https://www.gbif.org/occurrence/1804069383):\n```python\nbananompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0') # => MultiJson object\n```\nSetting the callback parameter returns [JSON-P](https://en.wikipedia.org/wiki/JSONP) wrapped in the provided callback string.\n```python\nbananompy.occurrence.search('f86a681d-7db8-483b-819a-248def18b70a', '7a1daa39-8d7c-d7c4-968f-799d58b3c7b0', callback='myFunction') # => JSON-P object\n```\n\n---\n### Collectors\nGet a person's profile by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers:\n```python\nbananompy.person.get('0000-0001-7618-5230') # => JSON-LD object\n```\n---\n### Specimens\nGet a person's specimens by their [ORCID](https://orcid.org/) or [WikiData](https://wikidata.org) identifiers. Use the page parameter for pagination.\n```python\nbananompy.person.get('0000-0001-7618-5230', specimens=True) # => JSON-LD object\n```\n\n```python\nbananompy.person.get('0000-0001-7618-5230', specimens=True, csv=True) # => comma-separated values\n```\n---\n### Occurrences\nGet an occurrence with a [GBIF](https://www.gbif.org/occurrence/search) occurrenceID:\n```python\nbananompy.occurrence.get('477976412') # => JSON-LD object\n```\n---\n### Parsing human names\n**Note:** [Bionomia](https://bionomia.net) provides a RESTful API for the human name parsing [dwc_agent](https://rubygems.org/gems/dwc_agent) gem which uses the [namae](https://rubygems.org/gems/namae) gem, and you likely will get better performance using those gems directly if parsing a large number of human names. A similar library in Python to the namae Ruby gem is [nameparser](https://github.com/derek73/python-nameparser).\n\nParse authorships with names separated by `;` and each authorship set separated by `\\r\\n`:\n```python\nbananompy.parse(names='Henry Robert Nicollon des Abbayes; Groom Q\\r\\nMrs. John Errol Chandos Aberdeen') # => MultiJson object\n```\n\n---\n### Agent Strings\nAgent strings are people names from occurrence labels that have not been associated with a person's identifier yet.\n\n**Note:** There is no restful API for agent strings, so these methods use beautifulsoup4 and the lxml parser to scrape the values from the Bionomia website.\n\nGet a random list of agent strings:\n```python\nbananompy.agent.search()\n```\n\nSearch for an agent string with the query, q:\n```python\nbananompy.agent.search(q='Mary Agnes')\n```\n\nGet an agent string's occurrences by ID (***Warning:*** The agent string identifiers are temporary and change every 2 weeks when new agent strings are imported into Bionomia and the website also goes down with a 503 error during agent string updates.)\n```python\nbananompy.agent.get('4746282')\n```\n\n---\n\n## Development\n\nAfter checking out the repo, change into the package directory `cd bananompy`, 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.\n\n## Other Bionomia Libraries\n\n* Ruby Gem: [bananomia](https://github.com/SpeciesFileGroup/bananomia)\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/SpeciesFileGroup/bananompy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/SpeciesFileGroup/bananompy/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe package is available as open source under the terms of the [NCSA/Illinois](https://github.com/SpeciesFileGroup/bananompy/blob/main/LICENSE.txt) license. You can learn more about the NCSA license on [Wikipedia](https://en.wikipedia.org/wiki/University_of_Illinois/NCSA_Open_Source_License) and compare it with other open source licenses at the [Open Source Initiative](https://opensource.org/license/uoi-ncsa-php/).\n\n## Code of Conduct\n\nEveryone interacting in the Bananompy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/SpeciesFileGroup/bananompy/blob/main/CODE_OF_CONDUCT.md).\n\n\n## [Unreleased]\n\n## [0.1.0] - 2023-10-27\n\n- Initial release\n",
"bugtrack_url": null,
"license": "NCSA",
"summary": "Python client for Bionomia",
"version": "0.0.1",
"project_urls": {
"Download": "https://github.com/speciesfilegroup/bananompy/archive/refs/tags/v0.0.1.tar.gz",
"Homepage": "http://github.com/speciesfilegroup/bananompy"
},
"split_keywords": [
"bionomia",
"biodiversity",
"collectors",
"specimens",
"api",
"web-services",
"species",
"natural history",
"taxonomists",
"biologists"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7b87c723c8fce5d58969be758e501634db6af074263bd8686cca6d2cabada82c",
"md5": "862adc98fc9e677318ae9e3a71d8ecd5",
"sha256": "4b97b3c0bf0eab7796b076471fbbbf2fddb2d080253868b5c8672094c0c34195"
},
"downloads": -1,
"filename": "bananompy-0.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "862adc98fc9e677318ae9e3a71d8ecd5",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 14379,
"upload_time": "2023-10-27T21:29:01",
"upload_time_iso_8601": "2023-10-27T21:29:01.087391Z",
"url": "https://files.pythonhosted.org/packages/7b/87/c723c8fce5d58969be758e501634db6af074263bd8686cca6d2cabada82c/bananompy-0.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c80e09b0aabe981fb409a37e0b91636705c9e7da98236feca593c8ad3f6ded49",
"md5": "95d467cb762d4ef64148adad750cd14b",
"sha256": "4a4248e2e3253993364b45b1a119853581b0b2c40d14b8e39117f5b8940c09a1"
},
"downloads": -1,
"filename": "bananompy-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "95d467cb762d4ef64148adad750cd14b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13024,
"upload_time": "2023-10-27T21:29:03",
"upload_time_iso_8601": "2023-10-27T21:29:03.137540Z",
"url": "https://files.pythonhosted.org/packages/c8/0e/09b0aabe981fb409a37e0b91636705c9e7da98236feca593c8ad3f6ded49/bananompy-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-27 21:29:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "speciesfilegroup",
"github_project": "bananompy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "beautifulsoup4",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "bs4",
"specs": [
[
"==",
"0.0.1"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2023.7.22"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.2.0"
]
]
},
{
"name": "codecov",
"specs": [
[
"==",
"2.1.13"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"7.3.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.4"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "lxml",
"specs": [
[
"==",
"4.9.3"
]
]
},
{
"name": "multidict",
"specs": [
[
"==",
"6.0.4"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"23.1"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.4.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"4.1.0"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "soupsieve",
"specs": [
[
"==",
"2.4.1"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.0.4"
]
]
},
{
"name": "vcrpy",
"specs": [
[
"==",
"5.1.0"
]
]
},
{
"name": "wrapt",
"specs": [
[
"==",
"1.15.0"
]
]
},
{
"name": "yarl",
"specs": [
[
"==",
"1.9.2"
]
]
}
],
"tox": true,
"lcname": "bananompy"
}
JSON
