bookops_worldcat.authorize

Provides means to authenticate and authorize interactions with OCLC web services.

WorldcatAccessToken

WorldcatAccessToken(
    key: str,
    secret: str,
    scopes: str,
    agent: str = "",
    timeout: Union[
        int,
        float,
        Tuple[int, int],
        Tuple[float, float],
        None,
    ] = (5, 5),
)

Requests a WorldCat access token.

Authenticates and authorizes using Client Credentials Grant flow. A token with correctly bonded scopes can be passed into a session of an OCLC web service to authorize requests for resources.

Example

from bookops_worldcat import WorldcatAccessToken

token = WorldcatAccessToken(
    key="my_WSKey_client_id",
    secret="my_WSKey_secret",
    scopes="WorldCatMetadataAPI",
    agent="my_app/1.0.0")
print(token.token_str)
#>"tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW"
print(token.is_expired())
#>False
print(token.server_response.json())
{
    "token_token": "tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW",
    "token_type": "bearer",
    "expires_in": "1199",
    "principalID": "",
    "principalIDNS": "",
    "scopes": "WorldCatMetadataAPI",
    "contextInstitutionId": "00001",
    "expires_at": "2020-08-23 18:45:29Z"
}
print(token.server_response.request.headers)
{
    "User-Agent": "my_app/1.0.0",
    "Accept-Encoding": "gzip, deflate",
    "Accept": "application/json",
    "Connection": "keep-alive",
    "Content-Length": "67",
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic encoded_authorization_here="
}

Usage Documentation:

PARAMETER	DESCRIPTION
`key`	Your WSKey public client_id TYPE: `str`
`secret`	Your WSKey secret TYPE: `str`
`scopes`	Request scopes for the access token as a string. Multiple scopes should be separated with a space. Users with WSKeys set up to act on behalf of multiple institutions should provide scope and registryID in the format: `{scope} context:{registryID}` EXAMPLES: Single institution WSKey: `"WorldCatMetadataAPI"` Multi-institution WSKey: `"WorldCatMetadataAPI context:00001"` TYPE: `str`
`agent`	`User-agent` parameter to be passed in the request header. Usage is strongly encouraged. TYPE: `str` DEFAULT: `''`
`timeout`	How long to wait for server to send data before giving up. Accepts separate values for connect and read timeouts or a single value. TYPE: `Union[int, float, Tuple[int, int], Tuple[float, float], None]` DEFAULT: `(5, 5)`

RAISES	DESCRIPTION
`TypeError`	If `agent`, `key`, `secret`, or `scopes` args are passed anything other than a str.
`ValueError`	If an empty str is passed to `key`, `secret` or `scopes` arg.
`WorldcatAuthorizationError`	If request for token encounters any errors.

Source code in bookops_worldcat\authorize.py

def __init__(
    self,
    key: str,
    secret: str,
    scopes: str,
    agent: str = "",
    timeout: Union[int, float, Tuple[int, int], Tuple[float, float], None] = (
        5,
        5,
    ),
) -> None:
    """Initializes WorldcatAccessToken object.


    info: Usage Documentation:
        - [Basic Usage](../start.md#authentication-and-authorization)
        - [Advanced Usage](../advanced.md#WorldcatAccessToken)

    Args:
        key:
            Your WSKey public client_id
        secret:
            Your WSKey secret
        scopes:
            Request scopes for the access token as a string. Multiple scopes
            should be separated with a space. Users with WSKeys set up to act on
            behalf of multiple institutions should provide scope and registryID
            in the format:
            `{scope} context:{registryID}`

            **EXAMPLES:**

            - Single institution WSKey: `"WorldCatMetadataAPI"`
            - Multi-institution WSKey: `"WorldCatMetadataAPI context:00001"`

        agent:
            `User-agent` parameter to be passed in the request header. Usage is
            strongly encouraged.
        timeout:
            How long to wait for server to send data before giving up. Accepts
            separate values for connect and read timeouts or a single value.

    Raises:
        TypeError:
            If `agent`, `key`, `secret`, or `scopes` args are passed
            anything other than a str.
        ValueError:
            If an empty str is passed to `key`, `secret` or `scopes` arg.
        WorldcatAuthorizationError:
            If request for token encounters any errors.
    """

    self.agent = agent
    self.grant_type = "client_credentials"
    self.key = key
    self.oauth_server = "https://oauth.oclc.org"
    self.scopes = scopes
    self.secret = secret
    self.server_response: Optional[requests.Response] = None
    self.timeout = timeout
    self.token_expires_at: Optional[datetime.datetime] = None
    self.token_str = ""
    self.token_type = ""

    # default bookops-worldcat request header
    if isinstance(self.agent, str):
        if not self.agent.strip():
            self.agent = f"{__title__}/{__version__}"
    else:
        raise TypeError("Argument 'agent' must be a string.")

    # ensure passed arguments are valid
    if isinstance(self.key, str):
        if not self.key.strip():
            raise ValueError("Argument 'key' cannot be an empty string.")
    else:
        raise TypeError("Argument 'key' must be a string.")

    if isinstance(self.secret, str):
        if not self.secret.strip():
            raise ValueError("Argument 'secret' cannot be an empty string.")
    else:
        raise TypeError("Argument 'secret' must be a string.")

    # validate passed scopes
    if isinstance(self.scopes, str):
        if not self.scopes.strip():
            raise ValueError("Argument 'scopes' cannot be an empty string.")
    else:
        raise TypeError("Argument 'scopes' must a string.")
    self.scopes = self.scopes.strip()

    # initiate request
    self._request_token()

is_expired

is_expired() -> bool

Checks if the access token is expired.

RETURNS	DESCRIPTION
`bool`	Whether or not the token is expired. TYPE: `bool`

RAISES	DESCRIPTION
`TypeError`	If `WorldcatAccessToken.token_expires_at` is not a `datetime.datetime` object.

Example

token = WorldcatAccessToken(
    key="my_WSKey_client_id",
    secret="my_WSKey_secret",
    scopes="WorldCatMetadataAPI",
    agent="my_app/1.0.0")
print(token.is_expired())
#>False

Source code in bookops_worldcat\authorize.py

def is_expired(self) -> bool:
    """
    Checks if the access token is expired.

    Returns:
        bool: Whether or not the token is expired.

    Raises:
        TypeError:
            If `WorldcatAccessToken.token_expires_at` is not a
            `datetime.datetime` object.

    Example:
        ```py
        token = WorldcatAccessToken(
            key="my_WSKey_client_id",
            secret="my_WSKey_secret",
            scopes="WorldCatMetadataAPI",
            agent="my_app/1.0.0")
        print(token.is_expired())
        #>False
        ```
    """
    if isinstance(self.token_expires_at, datetime.datetime):
        if self.token_expires_at < datetime.datetime.now(datetime.timezone.utc):
            return True
        else:
            return False
    else:
        raise TypeError(
            "Attribute 'WorldcatAccessToken.token_expires_at' is of invalid type. "
            "Expected `datetime.datetime` object."
        )