# Pokapi<img width="11%" align="right" src="https://github.com/caltechlibrary/pokapi/raw/main/.graphics/pokapi-icon.png">
Pokapi (_Python Okapi Interface_) is a Python package for getting basic data from a [FOLIO](https://www.folio.org) LSP server using the [Okapi API](https://github.com/folio-org/okapi/blob/master/doc/guide.md).
[](https://choosealicense.com/licenses/bsd-3-clause)
[](https://github.com/caltechlibrary/pokapi/releases)
[](http://shields.io)
[](https://pypi.org/project/pokapi/)
## Table of contents
* [Introduction](#introduction)
* [Installation](#installation)
* [Usage](#usage)
* [Known issues and limitations](#known-issues-and-limitations)
* [Getting help](#getting-help)
* [Contributing](#contributing)
* [License](#license)
* [Authors and history](#authors-and-history)
* [Acknowledgments](#authors-and-acknowledgments)
## Introduction
The [FOLIO](https://www.folio.org) platform is a [library services platform](https://www.niso.org/sites/default/files/stories/2017-09/FE_Grant_Future_Library_Systems_%20isqv24no4.pdf). The Caltech Library uses a hosted solution by [EBSCO](https://www.ebsco.com) for its [library catalog](https://www.library.caltech.edu/libsearch). To make writing interfaces and automation scripts in Python easier, the Caltech Library [Digital Library Development team](https://www.library.caltech.edu/staff?&field_directory_department%5B0%5D=754) are developing Pokapi (_Python Okapi Interface_), a Python package that provides an object-oriented interface to accessing FOLIO data via the [Okapi API](https://github.com/folio-org/okapi/blob/master/doc/guide.md). It currently provides a simple object structure based mostly on FOLIO _instance_ records.
Incidentally, [okapi](https://en.wikipedia.org/wiki/Okapi) (properly known as _Okapia johnstoni_) are real animals related to the giraffe. They are an [endangered species](https://www.iucnredlist.org/species/15188/51140517) whose population continues to decrease due to human activity and [hunting by humans](https://www.nationalgeographic.com/animals/mammals/facts/okapi).
## Installation
The instructions below assume you have a Python interpreter installed on your computer; if that's not the case, please first [install Python version 3](INSTALL-Python3.md) and familiarize yourself with running Python programs on your system.
On **Linux**, **macOS**, and **Windows** operating systems, you should be able to install `pokapi` with [`pip`](https://pip.pypa.io/en/stable/installing/). To install `pokapi` from the [Python package repository (PyPI)](https://pypi.org), run the following command:
```sh
python3 -m pip install pokapi
```
As an alternative to getting it from [PyPI](https://pypi.org), you can use `pip` to install `pokapi` directly from GitHub, like this:
```sh
python3 -m pip install git+https://github.com/caltechlibrary/pokapi.git
```
## Usage
The use of Pokapi is straightfoward. First, callers must create one instance of a `Folio` object that defines various aspects of how to communicate with their FOLIO/Okapi system. Then, callers can use the `record(...)` method on that `Folio` object to get objects that represent records in their FOLIO system. The method only requires an identifier, which can be a FOLIO instance identifier, an item barcode, or an EDS accession number. More details about all of this are provided below.
### The `Folio` interface object
To use Pokapi, first create a `Folio` object with parameters that define certain things Pokapi can't get on its own. These are: the the Okapi URL for your instance, an Okapi API token, a tenant id, and the prefix that appears in front of your accession numbers. Assuming that these values are stored in separate variables, the following code illustrates how to create a `Folio` object:
```python
from pokapi import Folio
folio = Folio(okapi_url = the_okapi_url,
okapi_token = the_okapi_token,
tenant_id = the_tenant_id,
an_prefix = the_accession_number_prefix)
```
As an example of a prefix for accession numbers, for Caltech the prefix is the `clc` part of an accession number such as `clc.025d49d5.735a.4d79.8889.c5895ac65fd2`.
### The `record(...)` method
The `Folio` class has only one method on it currently: `record(...)`. This method contacts the FOLIO server to obtain data and returns a `FolioRecord` object with the data stored in fields. The following fields are implemented at this time:
| Field | Type | Meaning |
|------------------|--------|---------|
| `id` | string | FOLIO instance record identifier |
| `accession_number` | string | The accession number for the record |
| `title` | string | Title of the work |
| `author` | string | Author; multiple authors are separated by "and" |
| `publisher` | string | Publisher |
| `year` | string | Year of publication |
| `edition` | string | the edition of the work (if any) |
| `isbn_issn` | string | ISBN or ISSN |
The method `Folio.record(...)` can take any one of the following mutually-exclusive keyword arguments to identify the record to be retrieved:
* `barcode`: retrieve the record corresponding to the given item barcode
* `instance_id`: retrieve the record having the given FOLIO instance identifier
* `accession_number`: retrieve the record corresponding to the accession number
Here is an example of using the method:
```python
r = folio.record(barcode = "35047019531631")
assert r.id == "1fedf5f3-b631-4d34-8d40-e022f70ab232"
assert r.title == "The bad doctor"
assert r.year == "2015"
assert r.author == "Williams, Ian"
assert r.isbn_issn == "9780271067544"
assert r.publisher == "The Pennsylvania State University Press"
```
## Known issues and limitations
The following are known limitations at this time:
* If a record has multiple publishers, only the first publisher name is retrieved.
* The title is extracted from the instance record's `title` field, but because (at least in our catalog) the title contains both a title and author info, Pokapi has to use heuristics to extract out just the title from the string. The heuristics might fail in some cases, especially if your installation of FOLIO uses different conventions for formatting the `title` field.
## Getting help
If you find an issue, please submit it in [the GitHub issue tracker](https://github.com/caltechlibrary/pokapi/issues) for this repository.
## Contributing
We would be happy to receive your help and participation with enhancing Pokapi! Please visit the [guidelines for contributing](CONTRIBUTING.md) for some tips on getting started.
## License
Software produced by the Caltech Library is Copyright © 2021–2023 California Institute of Technology. This software is freely distributed under a BSD/MIT type license. Please see the [LICENSE](LICENSE) file for more information.
## Acknowledgments
This work was funded by the California Institute of Technology Library.
The [vector artwork](https://thenounproject.com/term/okapi-face/1546683/) of the face of an [okapi](https://en.wikipedia.org/wiki/Okapi), used as the icon for this project, was created by [Icons Producer](https://thenounproject.com/iconsproducer/) from the Noun Project. It is licensed under the Creative Commons [CC-BY 3.0](https://creativecommons.org/licenses/by/3.0/) license.
Pokapi makes use of numerous open-source packages, without which Pokapi could not have been developed. I want to acknowledge this debt. In alphabetical order, the packages are:
* [CommonPy](https://github.com/caltechlibrary/commonpy) – a collection of commonly-useful Python functions
* [ipdb](https://github.com/gotcha/ipdb) – the IPython debugger
* [lxml](https://lxml.de) – an XML parsing library for Python
* [Python Decouple](https://github.com/henriquebastos/python-decouple/) – a high-level configuration file interface
* [setuptools](https://github.com/pypa/setuptools) – library for `setup.py`
* [Sidetrack](https://github.com/caltechlibrary/sidetrack) – simple debug logging/tracing package
* [uritemplate](https://github.com/python-hyper/uritemplate) – URI template parsing per RFC 6570
* [validators](https://github.com/kvesteri/validators) – Python data validation for Humans
<div align="center">
<br>
<a href="https://www.caltech.edu">
<img width="100" height="100" src="https://raw.githubusercontent.com/caltechlibrary/pokapi/main/.graphics/caltech-round.png">
</a>
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/caltechlibrary/pokapi",
"name": "pokapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Python,utilities",
"author": "Michael Hucka",
"author_email": "mhucka@caltech.edu",
"download_url": "https://files.pythonhosted.org/packages/fb/ff/8da95f2085178fac9dd8c4162b84866888d521492cab05eb25671417cf14/pokapi-0.4.0.tar.gz",
"platform": null,
"description": "# Pokapi<img width=\"11%\" align=\"right\" src=\"https://github.com/caltechlibrary/pokapi/raw/main/.graphics/pokapi-icon.png\">\n\nPokapi (_Python Okapi Interface_) is a Python package for getting basic data from a [FOLIO](https://www.folio.org) LSP server using the [Okapi API](https://github.com/folio-org/okapi/blob/master/doc/guide.md).\n\n[](https://choosealicense.com/licenses/bsd-3-clause)\n[](https://github.com/caltechlibrary/pokapi/releases)\n[](http://shields.io)\n[](https://pypi.org/project/pokapi/)\n\n\n## Table of contents\n\n* [Introduction](#introduction)\n* [Installation](#installation)\n* [Usage](#usage)\n* [Known issues and limitations](#known-issues-and-limitations)\n* [Getting help](#getting-help)\n* [Contributing](#contributing)\n* [License](#license)\n* [Authors and history](#authors-and-history)\n* [Acknowledgments](#authors-and-acknowledgments)\n\n\n## Introduction\n\nThe [FOLIO](https://www.folio.org) platform is a [library services platform](https://www.niso.org/sites/default/files/stories/2017-09/FE_Grant_Future_Library_Systems_%20isqv24no4.pdf). The Caltech Library uses a hosted solution by [EBSCO](https://www.ebsco.com) for its [library catalog](https://www.library.caltech.edu/libsearch). To make writing interfaces and automation scripts in Python easier, the Caltech Library [Digital Library Development team](https://www.library.caltech.edu/staff?&field_directory_department%5B0%5D=754) are developing Pokapi (_Python Okapi Interface_), a Python package that provides an object-oriented interface to accessing FOLIO data via the [Okapi API](https://github.com/folio-org/okapi/blob/master/doc/guide.md). It currently provides a simple object structure based mostly on FOLIO _instance_ records.\n\nIncidentally, [okapi](https://en.wikipedia.org/wiki/Okapi) (properly known as _Okapia johnstoni_) are real animals related to the giraffe. They are an [endangered species](https://www.iucnredlist.org/species/15188/51140517) whose population continues to decrease due to human activity and [hunting by humans](https://www.nationalgeographic.com/animals/mammals/facts/okapi).\n\n\n## Installation\n\nThe instructions below assume you have a Python interpreter installed on your computer; if that's not the case, please first [install Python version 3](INSTALL-Python3.md) and familiarize yourself with running Python programs on your system.\n\nOn **Linux**, **macOS**, and **Windows** operating systems, you should be able to install `pokapi` with [`pip`](https://pip.pypa.io/en/stable/installing/). To install `pokapi` from the [Python package repository (PyPI)](https://pypi.org), run the following command:\n```sh\npython3 -m pip install pokapi\n```\n\nAs an alternative to getting it from [PyPI](https://pypi.org), you can use `pip` to install `pokapi` directly from GitHub, like this:\n```sh\npython3 -m pip install git+https://github.com/caltechlibrary/pokapi.git\n```\n\n\n## Usage\n\nThe use of Pokapi is straightfoward. First, callers must create one instance of a `Folio` object that defines various aspects of how to communicate with their FOLIO/Okapi system. Then, callers can use the `record(...)` method on that `Folio` object to get objects that represent records in their FOLIO system. The method only requires an identifier, which can be a FOLIO instance identifier, an item barcode, or an EDS accession number. More details about all of this are provided below.\n\n\n### The `Folio` interface object\n\nTo use Pokapi, first create a `Folio` object with parameters that define certain things Pokapi can't get on its own. These are: the the Okapi URL for your instance, an Okapi API token, a tenant id, and the prefix that appears in front of your accession numbers. Assuming that these values are stored in separate variables, the following code illustrates how to create a `Folio` object:\n```python\nfrom pokapi import Folio\n\nfolio = Folio(okapi_url = the_okapi_url,\n okapi_token = the_okapi_token,\n tenant_id = the_tenant_id,\n an_prefix = the_accession_number_prefix)\n```\n\nAs an example of a prefix for accession numbers, for Caltech the prefix is the `clc` part of an accession number such as `clc.025d49d5.735a.4d79.8889.c5895ac65fd2`. \n\n\n### The `record(...)` method\n\nThe `Folio` class has only one method on it currently: `record(...)`. This method contacts the FOLIO server to obtain data and returns a `FolioRecord` object with the data stored in fields. The following fields are implemented at this time:\n\n| Field | Type | Meaning |\n|------------------|--------|---------|\n| `id` | string | FOLIO instance record identifier |\n| `accession_number` | string | The accession number for the record |\n| `title` | string | Title of the work |\n| `author` | string | Author; multiple authors are separated by \"and\" |\n| `publisher` | string | Publisher |\n| `year` | string | Year of publication |\n| `edition` | string | the edition of the work (if any) |\n| `isbn_issn` | string | ISBN or ISSN |\n\nThe method `Folio.record(...)` can take any one of the following mutually-exclusive keyword arguments to identify the record to be retrieved:\n\n* `barcode`: retrieve the record corresponding to the given item barcode\n* `instance_id`: retrieve the record having the given FOLIO instance identifier\n* `accession_number`: retrieve the record corresponding to the accession number\n\nHere is an example of using the method:\n\n```python\nr = folio.record(barcode = \"35047019531631\")\nassert r.id == \"1fedf5f3-b631-4d34-8d40-e022f70ab232\"\nassert r.title == \"The bad doctor\"\nassert r.year == \"2015\"\nassert r.author == \"Williams, Ian\"\nassert r.isbn_issn == \"9780271067544\"\nassert r.publisher == \"The Pennsylvania State University Press\"\n```\n\n\n## Known issues and limitations\n\nThe following are known limitations at this time:\n\n* If a record has multiple publishers, only the first publisher name is retrieved.\n* The title is extracted from the instance record's `title` field, but because (at least in our catalog) the title contains both a title and author info, Pokapi has to use heuristics to extract out just the title from the string. The heuristics might fail in some cases, especially if your installation of FOLIO uses different conventions for formatting the `title` field.\n\n\n## Getting help\n\nIf you find an issue, please submit it in [the GitHub issue tracker](https://github.com/caltechlibrary/pokapi/issues) for this repository.\n\n\n## Contributing\n\nWe would be happy to receive your help and participation with enhancing Pokapi! Please visit the [guidelines for contributing](CONTRIBUTING.md) for some tips on getting started.\n\n\n## License\n\nSoftware produced by the Caltech Library is Copyright \u00a9 2021–2023 California Institute of Technology. This software is freely distributed under a BSD/MIT type license. Please see the [LICENSE](LICENSE) file for more information.\n\n\n## Acknowledgments\n\nThis work was funded by the California Institute of Technology Library.\n\nThe [vector artwork](https://thenounproject.com/term/okapi-face/1546683/) of the face of an [okapi](https://en.wikipedia.org/wiki/Okapi), used as the icon for this project, was created by [Icons Producer](https://thenounproject.com/iconsproducer/) from the Noun Project. It is licensed under the Creative Commons [CC-BY 3.0](https://creativecommons.org/licenses/by/3.0/) license.\n\nPokapi makes use of numerous open-source packages, without which Pokapi could not have been developed. I want to acknowledge this debt. In alphabetical order, the packages are:\n\n* [CommonPy](https://github.com/caltechlibrary/commonpy) – a collection of commonly-useful Python functions\n* [ipdb](https://github.com/gotcha/ipdb) – the IPython debugger\n* [lxml](https://lxml.de) – an XML parsing library for Python\n* [Python Decouple](https://github.com/henriquebastos/python-decouple/) – a high-level configuration file interface\n* [setuptools](https://github.com/pypa/setuptools) – library for `setup.py`\n* [Sidetrack](https://github.com/caltechlibrary/sidetrack) – simple debug logging/tracing package\n* [uritemplate](https://github.com/python-hyper/uritemplate) – URI template parsing per RFC 6570\n* [validators](https://github.com/kvesteri/validators) – Python data validation for Humans\n\n<div align=\"center\">\n <br>\n <a href=\"https://www.caltech.edu\">\n <img width=\"100\" height=\"100\" src=\"https://raw.githubusercontent.com/caltechlibrary/pokapi/main/.graphics/caltech-round.png\">\n </a>\n</div>\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-clause",
"summary": "Python package for getting basic data from a FOLIO LSP server",
"version": "0.4.0",
"split_keywords": [
"python",
"utilities"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e5c0d9ca505b70ae8d85e5e2dac4d51b2162a21e0ff73e2caa170e466176fb1a",
"md5": "50a4a4a03e17d0feb7fe260502c458f1",
"sha256": "a5e14e35adc0f4318397eb6dd76aeb73f767e36416d8c8280bbe2a3a2775489f"
},
"downloads": -1,
"filename": "pokapi-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50a4a4a03e17d0feb7fe260502c458f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12942,
"upload_time": "2023-01-18T23:40:47",
"upload_time_iso_8601": "2023-01-18T23:40:47.598843Z",
"url": "https://files.pythonhosted.org/packages/e5/c0/d9ca505b70ae8d85e5e2dac4d51b2162a21e0ff73e2caa170e466176fb1a/pokapi-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fbff8da95f2085178fac9dd8c4162b84866888d521492cab05eb25671417cf14",
"md5": "cc2826988b579c5d58f2ad2867fdd13f",
"sha256": "bf972f047ee542e395a690943cd2a72a8074f872f10fccad91326176f2557147"
},
"downloads": -1,
"filename": "pokapi-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "cc2826988b579c5d58f2ad2867fdd13f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15638,
"upload_time": "2023-01-18T23:40:49",
"upload_time_iso_8601": "2023-01-18T23:40:49.478874Z",
"url": "https://files.pythonhosted.org/packages/fb/ff/8da95f2085178fac9dd8c4162b84866888d521492cab05eb25671417cf14/pokapi-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-18 23:40:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "caltechlibrary",
"github_project": "pokapi",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pokapi"
}
JSON
