Changelog

Changelog#

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

v1.0.0#

Added#

  • Comprehensive Sphinx documentation

  • Full async/await support for all FOLIO HTTP operations

  • Intelligent pagination with ID-based optimization

  • Experimental orjson support for improved JSON performance

  • Type hints throughout the codebase

  • Context manager support for automatic cleanup

  • Better handling of cached properties in an ECS context #74

  • Custom exceptions for FolioClient

Changed#

  • Refactored core logic to eliminate code duplication

  • Improved error handling and custom exceptions

  • Enhanced authentication flow with automatic token refresh and cookie-based authentication

  • Switched from a custom auth flow handler to use an httpx.Auth subclass for authentication and token management

  • Consolidated folio_get_all and folio_get_all_by_id_offset based on query

Deprecated#

  • http_timeout property - Returns httpx.Timeout object instead of original parameter value

  • okapi_url property - Use gateway_url instead

  • okapi_headers property - Use folio_headers instead

  • okapi_token property - Use access_token instead

  • folio_token_expires property - Use access_token_expires instead

  • ssl_verify parameter - Will be removed in future release

Fixed#

  • Authentication token management across sync/async operations

  • Pagination edge cases with large datasets

Security#

  • Improved credential handling and token security

⚠️ Backwards-Incompatible Changes and Deprecations (v1.0.0)#

FolioClient v1.0.0 introduces several breaking changes to modernize the library and improve reliability. Please review this section carefully before upgrading.

Python Version Requirements#

  • Minimum Python version raised to 3.10

  • Dropped support for Python 3.8 and 3.9

  • Rationale: Enables modern type hints, async improvements, and pattern matching

FOLIO version support#

  • Dropped support for pre-Quesnelia releases of FOLIO (FolioClient no longer supports /authn/login endpoint for authentication)

Timeout Parameter Behavior#

  • Breaking change in timeout parameter handling

  • Old behavior: timeout=None and no timeout parameter were treated identically

  • New behavior:

    • No timeout parameter: Uses environment variable configuration (HTTPX_TIMEOUT, TIMEOUT_CONFIG)

    • timeout=None: Explicitly disables all timeouts, ignoring environment variables

    • timeout=value: Uses provided value with environment variable fallbacks for unspecified components

  • Migration:

    • If you want no timeout: explicitly pass timeout=None or don’t set environment variables

    • If you want environment defaults: omit the timeout parameter entirely

    • If you want custom timeout: pass your timeout configuration as before, or pass a dictionary of timeout keyword arguments or an httpx.Timeout instance

Property Return Type Changes#

http_timeout Property (DEPRECATED)#

  • Breaking change: Now returns httpx.Timeout object instead of original parameter value

  • Old behavior: Returned the original timeout parameter (float, dict, or None)

  • New behavior: Returns processed httpx.Timeout object or None

  • Impact: Code using this property with non-httpx libraries may break

  • Migration:

    • Deprecated: This property will be removed in a future release

    • For cross-library compatibility, store the original timeout value separately

    • Use FolioClient’s built-in HTTP methods instead of external libraries when possible

Deprecated Property Names#

Multiple properties have been renamed for clarity and consistency:

Deprecated Property

New Property

Breaking Change

okapi_url

gateway_url

No - backward compatible

okapi_headers

folio_headers

No - backward compatible

okapi_token

access_token

No - backward compatible

okapi_token_expires

access_token_expires

No - backward compatible

Migration: Update code to use new property names. Old names still work but emit deprecation warnings.

Removed Methods#

  • get_random_objects method - This method has been removed

  • Rationale: Method was not widely used and did not align with modern API design principles

  • Migration: Replace with appropriate folio_get or folio_get_all calls with specific queries

Authentication Flow Changes#

  • Enhanced token lifecycle management Tokens now renew at one minute before expiry and this offset is no longer configurable via environment variable

  • Cookie-based authentication for better session handling #73

  • Impact: Custom authentication code may need updates

  • Migration: While this change is largely transparent to the end-user of FolioClient, the one notable change is that you no longer need to pass the headers=okapi_headers to any httpx.Client or httpx.AsyncClient objects created using the FolioClient.get_folio_http_client and FolioClient.get_folio_http_client_async methods. They are instantiated with built-in authentication.

Exception Hierarchy#

  • New FOLIO-specific exception types:

    • FolioAuthenticationError (401 errors)

    • FolioPermissionError (403 errors)

    • FolioResourceNotFoundError (404 errors)

    • FolioValidationError (422 errors)

    • FolioInternalServerError (500 errors)

    • And more…

  • Migration: Update exception handling to catch specific FOLIO exception types, but existing httpx.HTTPStatusError and httpx.ConnectError handling should continue to function normally, though message bodies may change

Environment Variable Changes#

  • New timeout configuration variables:

    • FOLIOCLIENT_CONNECT_TIMEOUT - Connection timeout in seconds

    • FOLIOCLIENT_READ_TIMEOUT - Read timeout in seconds

    • FOLIOCLIENT_WRITE_TIMEOUT - Write timeout in seconds

    • FOLIOCLIENT_POOL_TIMEOUT - Connection pool timeout in seconds

    • Existing FOLIOCLIENT_HTTP_TIMEOUT still supported for backward compatibility

  • Migration: Existing FOLIOCLIENT_HTTP_TIMEOUT configurations continue to work

Type Safety Improvements#

  • Enhanced type hints throughout the codebase

  • Stricter type checking for parameters and return values

  • Impact: MyPy and other type checkers may report new issues

  • Migration: Update type annotations in your code to match new signatures

Async Operation Changes#

  • All FOLIO HTTP operations now have async counterparts

  • Context manager support for both sync and async operations

  • Migration:

    • Sync operations: No changes required

    • New async operations: Use async with and await as appropriate

Migration Checklist#

  1. Update Python version to 3.10 or higher

  2. Update timeout handling:

    • Replace timeout=None with explicit timeout=None if you want no timeout

    • Remove timeout parameter if you want environment defaults

  3. Update property names:

    • okapi_url → gateway_url

    • okapi_headers → folio_headers

    • okapi_token → access_token

    • okapi_token_expires → access_token_expires

  4. Remove usage of http_timeout property if used with non-httpx libraries

  5. Replace removed methods:

    • get_random_objects → Use folio_get or folio_get_all with specific queries

    • folio_get_all_by_id_offset has been consolidated with folio_get_all and behavior is invoked whenever query= contains sortBy id

  6. Update exception handling to catch specific FOLIO exception types

  7. Test thoroughly in your environment before deploying

For questions about migration, please open an issue on GitHub or join us at #fse_folio_migration_tools on the OLF Slack.

[Older Releases]

v0.60.0 (07/11/2023)#

What’s Changed#

  • Fix GitHub testing configuration by @bltravis in https://github.com/FOLIO-FSE/FolioClient/pull/26

  • Fixes Better Support fetching YAML Schemas for OpenAPI modules #30 by @bltravis in https://github.com/FOLIO-FSE/FolioClient/pull/31

  • Updated FolioClient to use dynamic properties for api token values by @bltravis in https://github.com/FOLIO-FSE/FolioClient/pull/28

  • Fixes #32 by @bltravis in https://github.com/FOLIO-FSE/FolioClient/pull/33

Full Changelog: https://github.com/FOLIO-FSE/FolioClient/compare/v_0501…v_0600

v_0501 (13/08/2023)#

What’s Changed#

  • Add optional parameter to pass ssl verification parameters to httpx. Fixes #20 by @bltravis in https://github.com/FOLIO-FSE/FolioClient/pull/21

  • Refactor how query parameters are handled for FolioClient.folio_get_all and FolioClient.folio_get by @bltravis in https://github.com/FOLIO-FSE/FolioClient/pull/22

  • Bumped version to 0.50.1 and added author. by @bltravis in https://github.com/FOLIO-FSE/FolioClient/pull/24

Full Changelog: https://github.com/FOLIO-FSE/FolioClient/compare/v_050…v_0501

v_050 (16/05/2023)#

  • [closed] Remove poetry.lock from repo #17

  • [closed] Swap out requests for an async-compatible library #16

v_043 (16/02/2023)#

No changelog for this release.

Forty two! (28/09/2022)#

Added missing Github authentication

Fortyone! (31/05/2022)#

bad tag.

Thirty nine! (23/03/2022)#

  • Support YAML files to be fetched via “get latest from github”

Thirty eight! (10/02/2022)#

Thirty seven! (04/02/2022)#

Same as 36..

Thirty six! (04/02/2022)#

Added optional page size to folio_get_all #

Thirty five! (09/11/2021)#

Thirty four! (09/11/2021)#

Thirty tree! (08/11/2021)#

Thirty two! (08/11/2021)#

Thirty one! (08/11/2021)#

Minor adjustments to validate everything works after transfer

Thirtieth! (22/02/2021)#

twentyninth (21/10/2020)#

Twentyeight! (21/09/2020)#

This change might brake code, since it move from returning lists to yielding .

twentyseventh! (24/06/2020)#

Twentysixth (24/06/2020)#

twentyfifth (05/06/2020)#

Twentyfourth (31/05/2020)#

Twentythird! (07/05/2020)#

twentysecond! (07/05/2020)#

twentyfirst (05/05/2020)#

Twentieth (05/05/2020)#

nineteenth (15/04/2020)#

eighteenth (07/04/2020)#

seventeenth! (21/02/2020)#

Sixteenth! (21/02/2020)#

Contents