[](https://github.com/BookOps-CAT/bookops-worldcat/actions) [](https://coveralls.io/github/BookOps-CAT/bookops-worldcat?branch=main) [](https://badge.fury.io/py/bookops-worldcat)  [](https://github.com/psf/black) [](https://opensource.org/licenses/MIT)
# bookops-worldcat
BookOps-Worldcat provides a Python interface for the WorldCat Metadata API. This wrapper simplifies requests to OCLC web services making them more accessible to OCLC member libraries.
Bookops-Worldcat version 1.0 supports changes released in version 2.0 (May 2023) of the OCLC Metadata API.
## Installation
Use pip:
`$ pip install bookops-worldcat`
## Documentation
For full documentation please see https://bookops-cat.github.io/bookops-worldcat/
## Features
Bookops-Worldcat takes advantage of the functionality of the popular [Requests library](https://requests.readthedocs.io/) and interactions with OCLC's services are built around 'Requests' sessions. `MetadataSession` inherits all `requests.Session` properties. Server responses are `requests.Response` objects with [all of their properties and methods](https://requests.readthedocs.io/en/latest/user/quickstart/).
Authorizing a web service session simply requires passing an access token to `MetadataSession`. Opening a session allows the user to call specific methods to facilitate communication between the user's script/client and a particular endpoint of the Metadata API. Many of the hurdles related to making valid requests are hidden under the hood of this package, making it as simple as possible.
BookOps-Worldcat supports requests to all endpoints of the WorldCat Metadata API 2.0 and Authentication using the [Client Credential Grant](https://www.oclc.org/developer/api/keys/oauth/client-credentials-grant.en.html) flow:
+ [Authentication via Client Credential Grant](https://www.oclc.org/developer/api/keys/oauth/client-credentials-grant.en.html)
+ [Worldcat Metadata API](https://www.oclc.org/developer/api/oclc-apis/worldcat-metadata-api.en.html)
+ Manage Bibliographic Records
+ Manage Institution Holdings
+ Manage Local Bibliographic Data
+ Manage Local Holdings Records
+ Search Member Shared Print Holdings
+ Search Member General Holdings
+ Search Bibliographic Resources
+ Search Local Holdings Resources
+ Search Local Bibliographic Resources
### Basic usage:
Authorizing a MetadataSession
```python
from bookops_worldcat import WorldcatAccessToken
token = WorldcatAccessToken(
key="my_WSKey",
secret="my_secret",
scopes="WorldCatMetadataAPI",
)
print(token)
#>"access_token: 'tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW', expires_at: '2024-01-01 12:00:00Z'"
print(token.is_expired())
#>False
```
Search for brief bibliographic resources
```python
with MetadataSession(authorization=token) as session:
response = session.brief_bibs_search(q="ti:The Power Broker AND au: Caro, Robert")
print(response.json())
```
```json
{
"numberOfRecords": 89,
"briefRecords": [
{
"oclcNumber": "1631862",
"title": "The power broker : Robert Moses and the fall of New York",
"creator": "Robert A. Caro",
"date": "1975",
"machineReadableDate": "1975",
"language": "eng",
"generalFormat": "Book",
"specificFormat": "PrintBook",
"edition": "Vintage Books edition",
"publisher": "Vintage Books",
"catalogingInfo": {
"catalogingAgency": "DLC",
"catalogingLanguage": "eng",
"levelOfCataloging": " ",
"transcribingAgency": "DLC"
}
}
]
}
```
MetadataSession as Context Manager:
```python
with MetadataSession(authorization=token) as session:
result = session.bib_get("1631862")
print(result.text)
```
```xml
<?xml version='1.0' encoding='UTF-8'?>
<record xmlns="http://www.loc.gov/MARC21/slim">
<leader>00000cam a2200000 i 4500</leader>
<controlfield tag="001">ocm01631862</controlfield>
<controlfield tag="003">OCoLC</controlfield>
<controlfield tag="005">20240201163642.4</controlfield>
<controlfield tag="008">750320t19751974nyuabf b 001 0beng </controlfield>
<datafield tag="010" ind1=" " ind2=" ">
<subfield code="a"> 75009557 </subfield>
</datafield>
<!--...-->
<datafield tag="020" ind1=" " ind2=" ">
<subfield code="a">9780394720241</subfield>
<subfield code="q">(paperback)</subfield>
<!--...-->
<datafield tag="100" ind1="1" ind2=" ">
<subfield code="a">Caro, Robert A.,</subfield>
<subfield code="e">author.</subfield>
</datafield>
<datafield tag="245" ind1="1" ind2="4">
<subfield code="a">The power broker :</subfield>
<subfield code="b">Robert Moses and the fall of New York /</subfield>
<subfield code="c">by Robert A. Caro.</subfield>
</datafield>
<datafield tag="246" ind1="3" ind2="0">
<subfield code="a">Robert Moses and the fall of New York</subfield>
</datafield>
<datafield tag="250" ind1=" " ind2=" ">
<subfield code="a">Vintage Books edition.</subfield>
</datafield>
<datafield tag="264" ind1=" " ind2="1">
<subfield code="a">New York :</subfield>
<subfield code="b">Vintage Books,</subfield>
<subfield code="c">1975.</subfield>
</datafield>
<!--...-->
</record>
```
## Changes in Version 1.0
New functionality available in version 1.0:
+ Send requests to all endpoints of WorldCat Metadata API
+ Match bib records and retrieve bib classification
+ Create, update, and validate bib records
+ Create, retrieve, update, and delete local bib and holdings records
+ Add automatic retries to failed requests
+ Authenticate and authorize for multiple institutions within `MetadataSession`
+ Support for Python 3.11 and 3.12
+ Dropped support for Python 3.7
### Migration Information
Bookops-Worldcat 1.0 introduces many breaking changes for users of previous versions. Due to a complete refactor of the Metadata API, the methods from Bookops-Worldcat 0.5.0 have been rewritten. Most of the functionality from previous versions of the Metadata API is still available in Version 2.0. For a comparison of the functionality available in Versions 1.0, 1.1, and 2.0 of the Metadata API, see [OCLC's documentation](https://www.oclc.org/developer/api/oclc-apis/worldcat-metadata-api.en.html) and their [functionality comparison table](https://www.oclc.org/content/dam/developer-network/worldcat-metadata-api/worldcat-metadata-api-functionality-comparison.pdf).
Versions 1.0 and 1.1 of the Metadata API will be sunset after April 30, 2024 at which point tools that rely on Bookops-Worldcat 0.5 will no longer be able to query the Metadata API.
For more information on changes made in Version 1.0, see [Features in Version 1.0](https://bookops-cat.github.io/bookops-worldcat/latest/#features-in-version-1.0) in the docs.
## Changelog
Consult the [Changelog page](https://bookops-cat.github.io/bookops-worldcat/latest/changelog/) for a full list of fixes and enhancements for each version.
## Bugs/Requests
Please use the [Github issue tracker](https://github.com/BookOps-CAT/bookops-worldcat/issues) to submit bugs or request features.
## Contributing
See [Contribution Guidelines](https://bookops-cat.github.io/bookops-worldcat/latest/contributing) for information on how to contribute to bookops-worldcat.
Raw data
{
"_id": null,
"home_page": "https://bookops-cat.github.io/bookops-worldcat/",
"name": "bookops-worldcat",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "api, api-wrapper, oclc, worldcat, cataloging, bibliographic records, marcxml, holdings, library metadata, marc21",
"author": "Tomasz Kalata",
"author_email": "klingaroo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d1/5d/6b552dc43146e6d78e3082e64aa3f69c0e7cb263b9ec2c73880947323614/bookops_worldcat-1.1.0.tar.gz",
"platform": null,
"description": "[](https://github.com/BookOps-CAT/bookops-worldcat/actions) [](https://coveralls.io/github/BookOps-CAT/bookops-worldcat?branch=main) [](https://badge.fury.io/py/bookops-worldcat)  [](https://github.com/psf/black) [](https://opensource.org/licenses/MIT)\n\n# bookops-worldcat\n\nBookOps-Worldcat provides a Python interface for the WorldCat Metadata API. This wrapper simplifies requests to OCLC web services making them more accessible to OCLC member libraries.\n\nBookops-Worldcat version 1.0 supports changes released in version 2.0 (May 2023) of the OCLC Metadata API. \n\n## Installation\n\nUse pip:\n\n`$ pip install bookops-worldcat`\n\n## Documentation\n\nFor full documentation please see https://bookops-cat.github.io/bookops-worldcat/\n\n## Features\n\nBookops-Worldcat takes advantage of the functionality of the popular [Requests library](https://requests.readthedocs.io/) and interactions with OCLC's services are built around 'Requests' sessions. `MetadataSession` inherits all `requests.Session` properties. Server responses are `requests.Response` objects with [all of their properties and methods](https://requests.readthedocs.io/en/latest/user/quickstart/).\n\nAuthorizing a web service session simply requires passing an access token to `MetadataSession`. Opening a session allows the user to call specific methods to facilitate communication between the user's script/client and a particular endpoint of the Metadata API. Many of the hurdles related to making valid requests are hidden under the hood of this package, making it as simple as possible.\n\nBookOps-Worldcat supports requests to all endpoints of the WorldCat Metadata API 2.0 and Authentication using the [Client Credential Grant](https://www.oclc.org/developer/api/keys/oauth/client-credentials-grant.en.html) flow:\n\n+ [Authentication via Client Credential Grant](https://www.oclc.org/developer/api/keys/oauth/client-credentials-grant.en.html)\n+ [Worldcat Metadata API](https://www.oclc.org/developer/api/oclc-apis/worldcat-metadata-api.en.html)\n + Manage Bibliographic Records\n + Manage Institution Holdings\n + Manage Local Bibliographic Data\n + Manage Local Holdings Records\n + Search Member Shared Print Holdings\n + Search Member General Holdings\n + Search Bibliographic Resources\n + Search Local Holdings Resources\n + Search Local Bibliographic Resources\n\n### Basic usage:\n\nAuthorizing a MetadataSession\n```python\nfrom bookops_worldcat import WorldcatAccessToken\ntoken = WorldcatAccessToken(\n key=\"my_WSKey\",\n secret=\"my_secret\",\n scopes=\"WorldCatMetadataAPI\",\n)\nprint(token)\n#>\"access_token: 'tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW', expires_at: '2024-01-01 12:00:00Z'\"\nprint(token.is_expired())\n#>False\n```\n\nSearch for brief bibliographic resources\n```python\nwith MetadataSession(authorization=token) as session:\n response = session.brief_bibs_search(q=\"ti:The Power Broker AND au: Caro, Robert\")\n print(response.json())\n```\n```json\n{\n \"numberOfRecords\": 89,\n \"briefRecords\": [\n {\n \"oclcNumber\": \"1631862\",\n \"title\": \"The power broker : Robert Moses and the fall of New York\",\n \"creator\": \"Robert A. Caro\",\n \"date\": \"1975\",\n \"machineReadableDate\": \"1975\",\n \"language\": \"eng\",\n \"generalFormat\": \"Book\",\n \"specificFormat\": \"PrintBook\",\n \"edition\": \"Vintage Books edition\",\n \"publisher\": \"Vintage Books\",\n \"catalogingInfo\": {\n \"catalogingAgency\": \"DLC\",\n \"catalogingLanguage\": \"eng\",\n \"levelOfCataloging\": \" \",\n \"transcribingAgency\": \"DLC\"\n }\n }\n ]\n}\n```\nMetadataSession as Context Manager:\n```python\nwith MetadataSession(authorization=token) as session:\n result = session.bib_get(\"1631862\")\n print(result.text) \n```\n```xml\n<?xml version='1.0' encoding='UTF-8'?>\n <record xmlns=\"http://www.loc.gov/MARC21/slim\">\n <leader>00000cam a2200000 i 4500</leader>\n <controlfield tag=\"001\">ocm01631862</controlfield>\n <controlfield tag=\"003\">OCoLC</controlfield>\n <controlfield tag=\"005\">20240201163642.4</controlfield>\n <controlfield tag=\"008\">750320t19751974nyuabf b 001 0beng </controlfield>\n <datafield tag=\"010\" ind1=\" \" ind2=\" \">\n <subfield code=\"a\"> 75009557 </subfield>\n </datafield>\n<!--...-->\n <datafield tag=\"020\" ind1=\" \" ind2=\" \">\n <subfield code=\"a\">9780394720241</subfield>\n <subfield code=\"q\">(paperback)</subfield>\n<!--...-->\n <datafield tag=\"100\" ind1=\"1\" ind2=\" \">\n <subfield code=\"a\">Caro, Robert A.,</subfield>\n <subfield code=\"e\">author.</subfield>\n </datafield>\n <datafield tag=\"245\" ind1=\"1\" ind2=\"4\">\n <subfield code=\"a\">The power broker :</subfield>\n <subfield code=\"b\">Robert Moses and the fall of New York /</subfield>\n <subfield code=\"c\">by Robert A. Caro.</subfield>\n </datafield>\n <datafield tag=\"246\" ind1=\"3\" ind2=\"0\">\n <subfield code=\"a\">Robert Moses and the fall of New York</subfield>\n </datafield>\n <datafield tag=\"250\" ind1=\" \" ind2=\" \">\n <subfield code=\"a\">Vintage Books edition.</subfield>\n </datafield>\n <datafield tag=\"264\" ind1=\" \" ind2=\"1\">\n <subfield code=\"a\">New York :</subfield>\n <subfield code=\"b\">Vintage Books,</subfield>\n <subfield code=\"c\">1975.</subfield>\n </datafield>\n<!--...-->\n</record>\n```\n\n## Changes in Version 1.0\n\nNew functionality available in version 1.0:\n\n+ Send requests to all endpoints of WorldCat Metadata API\n + Match bib records and retrieve bib classification\n + Create, update, and validate bib records\n + Create, retrieve, update, and delete local bib and holdings records\n+ Add automatic retries to failed requests\n+ Authenticate and authorize for multiple institutions within `MetadataSession`\n+ Support for Python 3.11 and 3.12\n+ Dropped support for Python 3.7 \n\n### Migration Information\nBookops-Worldcat 1.0 introduces many breaking changes for users of previous versions. Due to a complete refactor of the Metadata API, the methods from Bookops-Worldcat 0.5.0 have been rewritten. Most of the functionality from previous versions of the Metadata API is still available in Version 2.0. For a comparison of the functionality available in Versions 1.0, 1.1, and 2.0 of the Metadata API, see [OCLC's documentation](https://www.oclc.org/developer/api/oclc-apis/worldcat-metadata-api.en.html) and their [functionality comparison table](https://www.oclc.org/content/dam/developer-network/worldcat-metadata-api/worldcat-metadata-api-functionality-comparison.pdf). \n\nVersions 1.0 and 1.1 of the Metadata API will be sunset after April 30, 2024 at which point tools that rely on Bookops-Worldcat 0.5 will no longer be able to query the Metadata API. \n\nFor more information on changes made in Version 1.0, see [Features in Version 1.0](https://bookops-cat.github.io/bookops-worldcat/latest/#features-in-version-1.0) in the docs.\n\n## Changelog\n\nConsult the [Changelog page](https://bookops-cat.github.io/bookops-worldcat/latest/changelog/) for a full list of fixes and enhancements for each version.\n\n## Bugs/Requests\n\nPlease use the [Github issue tracker](https://github.com/BookOps-CAT/bookops-worldcat/issues) to submit bugs or request features.\n\n## Contributing\n\nSee [Contribution Guidelines](https://bookops-cat.github.io/bookops-worldcat/latest/contributing) for information on how to contribute to bookops-worldcat.",
"bugtrack_url": null,
"license": "MIT",
"summary": "OCLC WorldCat Metadata APIs wrapper",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/BookOps-CAT/bookops-worldcat/issues",
"Homepage": "https://bookops-cat.github.io/bookops-worldcat/",
"Repository": "https://github.com/BookOps-CAT/bookops-worldcat"
},
"split_keywords": [
"api",
" api-wrapper",
" oclc",
" worldcat",
" cataloging",
" bibliographic records",
" marcxml",
" holdings",
" library metadata",
" marc21"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3a5d40da9776d87c0d60ad603a1c2199b554a187ca7eca30907aed38b6f2f84",
"md5": "92aaa806840b28cdcbada0eb510a4e4e",
"sha256": "16b4a51998d69b7988386164b06b3c43ae9034a79c4660094c40845e99cf7010"
},
"downloads": -1,
"filename": "bookops_worldcat-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "92aaa806840b28cdcbada0eb510a4e4e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 21877,
"upload_time": "2024-12-06T14:57:26",
"upload_time_iso_8601": "2024-12-06T14:57:26.573186Z",
"url": "https://files.pythonhosted.org/packages/b3/a5/d40da9776d87c0d60ad603a1c2199b554a187ca7eca30907aed38b6f2f84/bookops_worldcat-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d15d6b552dc43146e6d78e3082e64aa3f69c0e7cb263b9ec2c73880947323614",
"md5": "17cd7c3b392099ddc40d07a96e5bb341",
"sha256": "cf9bd78a12fd94350557141676a0d6e7109dd7746f6388612f95ef3aef33a13a"
},
"downloads": -1,
"filename": "bookops_worldcat-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "17cd7c3b392099ddc40d07a96e5bb341",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 19228,
"upload_time": "2024-12-06T14:57:28",
"upload_time_iso_8601": "2024-12-06T14:57:28.353681Z",
"url": "https://files.pythonhosted.org/packages/d1/5d/6b552dc43146e6d78e3082e64aa3f69c0e7cb263b9ec2c73880947323614/bookops_worldcat-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 14:57:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BookOps-CAT",
"github_project": "bookops-worldcat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "bookops-worldcat"
}
JSON
