Support for new Metadata API 2.0 release

BookOps-Worldcat version 1.1.0 supports changes made in the September 2024 release of the OCLC WorldCat Metadata API (version 2.0).

New functionality in 1.1

• retrieve full MARC records in JSON format
• remove associated Local Holdings Records (LHRs) and Local Bibliographic Data records (LBDs) when unsetting holdings on a WorldCat record

Changelog

Added

• Support for new Metadata API functionality:
  • bib_search method within MetadataSession class allows users to retrieve full MARC records in JSON format with the new /worldcat/search/bibs/{oclcNumber}
  • cascadeDelete arg added to holdings_unset and holdings_unset_with_bib methods. LHR and LBD records will be deleted when unsetting holdings on a record in WorldCat. This default functionality can be changed by setting cascadeDelete to False
• Monthly live tests running via GitHub Actions
  • Tests will check whether changes have been made to the Metadata API
• Python 3.13 added to unit tests
• Type annotations added to fixtures in conftest.py
• scope added as a return value in WorldcatAccessToken tests and documentation
  • OCLC's Authorization Server now accepts and returns scope as a parameter but it appears to be interchangeable with scopes. It is listed in the tests and documentation for WorldcatAccessToken but is not included as an attribute for the class.
• Dev dependencies:
  • types-pyyaml (6.0.12)

Changed

• Moved live tests to separate files within tests/webtests directory
• Moved fixtures for live tests to tests/webtests/conftest.py
• Minor edits to tests due to changes in responses from Metadata API
• Updated dependencies:
  • certifi (2024.8.30)
  • charset-normalizer (3.4.0)
  • idna (3.10)
  • requests (2.32.3)
  • urllib3 (2.2.3)
• Updated dev dependencies:
  • babel (2.16.0)
  • black (24.8.0)
  • coverage (7.6.1)
  • exceptiongroup (1.2.2)
  • griffe (1.4.0)
  • importlib-metadata (8.5.0)
  • importlib-resources (6.4.5)
  • jinja2 (3.1.4)
  • markdown (3.7)
  • mike (2.1.3)
  • mkdocs-autorefs (1.2.0)
  • mkdocs-get-deps (0.2.0)
  • mkdocs-material (9.5.46)
  • mkdocs (1.6.1)
  • mkdocstrings-python (1.11.1)
  • mkdocstrings (0.26.1)
  • mypy (1.13.0)
  • packaging (24.2)
  • paginate (0.5.7)
  • platformdirs (4.3.6)
  • pluggy (1.5.0)
  • pygments (2.18.0)
  • pymdown-extensions (10.12)
  • pyparsing (3.1.4)
  • pytest-mock (3.14.0)
  • python-dateutil (2.9.0.post0)
  • pytz (2024.2)
  • pyyaml (6.0.2)
  • regex (2024.11.6)
  • tomli (2.1.0)
  • types-requests (2.32.0.20241016)
  • typing-extensions (4.12.2)
  • urllib3 (2.2.3)
  • watchdog (4.0.2)
  • wheel (0.45.1)
  • zipp (3.20.2)

Fixed

• Return type for all MetadataSession methods is now requests.Response not Optional[requests.Response]
• Typos and incorrect import statements

Removed

• Redundant/unused fixtures for mock 400 and 409 responses from conftest.py
• Changed stub_marc21 fixture to return bytes and removed test.mrc file

Bug fixes

Fixed

• Inconsistent default values for timeout arg for MetadataSession, WorldcatAccessToken and Query objects

Changed

• Updated dev dependencies:
  • black (24.3.0)
• Updated dependencies:
  • idna (3.7)
• Reformatted docstrings for better readability on https://bookops-cat.github.io/bookops-worldcat/
• Fixed typos
• prep_oclc_number_str now parses OCLC Numbers with "(OCoLC)" prefix. Parsing rules match OCLC documentation

Added

• Tutorials to tutorials.md

Bookops-Worldcat 1.0.0

Bookops-Worldcat version 1.0 supports changes released in version 2.0 (May 2023) of the OCLC Metadata API and has expanded coverage to all endpoints of the Metadata API. This version introduces many breaking changes due to the complete refactor of the Metadata API.

New functionality in 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

Changelog

Added

• Support for OCLC Metadata API Version 2.0
  • MetadataSession methods to support new functionality released in Metadata API 2.0
    • bib_match
    • bib_get_classification
    • holdings_set_with_bib and holdings_unset_with_bib
  • New MetadataSession methods to support existing Metadata API functionality
    • Bib Record Management and Validation
      • bib_create
      • bib_replace
      • bib_validate
    • Local Holdings Records
      • lhr_create
      • lhr_delete
      • lhr_get
      • lhr_replace
    • Local Bibliographic Data
      • lbd_create
      • lbd_delete
      • lbd_get
      • lbd_replace
    • Holdings Management
      • holdings_get_codes
• Support for automatic retries of failed requests
• Support for multi-institution WSKeys
• Support for Python 3.11 and 3.12
• New dev dependencies:
  • types-requests (2.31.0.20240125)
  • mkdocs-material (9.5.13)

Changed

• MetadataSession methods that have been renamed and updated (replacing existing functionality in Bookops-Worldcat):
  • get_brief_bib is now brief_bibs_get
  • get_full_bib is now bib_get
  • holding_get_status is now holdings_get_current
  • holding_set is now holdings_set
  • holding_unset is now holdings_unset
  • search_brief_bib_other_editions is now brief_bibs_get_other_editions
  • search_brief_bibs is now brief_bibs_search
  • search_current_control_numbers is now bib_get_current_oclc_number
  • search_general_holdings is now summary_holdings_search
  • search_shared_print_holdings is now shared_print_holdings_search
• WorldcatAccessToken
  • scopes arg now only accepts strings. A TypeError is raised if scopes arg is passed a list
  • token_expires_at attribute is now an aware datetime object (change made due to datetime.utcnow() deprecation)
• Error handling:
  • TypeError and ValueError replace WorldcatAuthorizationError when WorldcatAccessToken is passed an invalid arg.
  • MetadataSession now raises InvalidOclcNumber exception when invalid OCLC identifiers are given
• pytest configuration moved from pytest.ini to pyproject.toml
• Updated and clarified type annotations for MetadataSession methods
• Updated dependencies:
  • requests: (2.31)
• Updated dev dependencies:
  • black (23.3.0)
  • mike (2.0.0)
  • mypy (1.0.14)
• Documentation on https://bookops-cat.github.io/bookops-worldcat/ has been rewritten and reorganized

Fixed

• AttributeError changed to TypeError if arg passed to Query.prepared_request is not a PreparedRequest
• All args for methods within MetadataSession have been changed to camel case to be consisted with Metadata API documentation

Removed

• principalID and principalIDNS as args for WorldcatAccessToken
• Automatic handling of large sets of oclcNumbers
  • _split_into_legal_volume removed from MetadataSession; a ValueError is now raised if a method is passed too many oclcNumbers

Deprecated

• Support for Python 3.7
• 409 error handling for holdings set/unset requests
• WorldcatSessionError
  • Replaced with TypeError or ValueError in WorldcatSession

Holdings for Mulitiple Institutions

Adds:

• methods to set and unset OCLC holdings for multiple institutions (for consortia): /ih/institutionlist endpoint
• __repr__ method to WorldcatAccessToken class
• fuller response when WorldcatRequestError is raised that provides details returned by the service

Fixes:

• authentication server response when request to obtain an access token fails

Changed:

• test fixtures refactoring

Fixes handling of 206 HTTP code when searching

• Fixes handling of unexpected 206 HTTP code that is occasionally returned by the MetadataAPI /brief-bibs endpoint
• Refactors metadata_api and moves requests into a new query.Query class

API endpoints changes update

• Changes to MetadataSession.search_brief_bibs method due to /brief-bibs endpoint changes:
  • removed deprecated argument heldBy
  • added groupVariantRecord and preferredLanuage argument
  • modified groupRelatedEditions to allow boolean arguments
• Changes to MetadataSession.search_general_holdings method due to API changes:
  • added following arguements: holdingsAllVariantRecords, preferredLanguage
  • removed deprecated heldBy argument
• Changes to MetadataSession.search_brief_bib_other_editions:
  • added deweyNumber, datePublished, heldByGroup, heldBySymbol,
    heldByInstitutionId, inLanguage, inCatalogLanguage, materialType,
    catalogSource, itemType, itemSubType, retentionCommitments,
    spProgram, topic, subtopic, audience, content, openAccess,
    peerReviewed, facets, groupVariantRecords, preferredLanguage,
    and orderBy.

urllib3 bump to 1.26.5

urllib3 dependency upgraded from 1.26.4 to 1.26.5 following vulnerability report

certifi, chardet, requests, urllib3 dependencies update

Dependencies update

• certifi to 2020.12.5
• chardet to 4.0.0
• requests to 2.25.1
• urllib3 to 1.26.4

MetadataSession timeout fix

Fixes an inactive timeout parameter in the MetadataSession. Every request sent within the session follows session's timeout setting.

MetadataSession auto token refresh fix

New:

• dependencies bump
• python 3.9 testing

Bug fixes:

• proper auto refreshing of stale access tokens
• error message testing fixed