Supporting Modules

This section provides details around the supporting modules used in the freshpy package, which are listed below.


Classes & Exceptions

This section includes modules that contain the classes and exceptions used throughout the package.


Errors Module (freshpy.errors)

This module contains all of the exception classes and error handling functions leveraged throughout the library.

Package:

freshpy.errors

Synopsis:

This module includes custom exceptions

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

28 Dec 2021

Return to Top


Exceptions Module (freshpy.errors.exceptions)

This sub-module contains all of the exception classes leveraged in functions throughout the library.

Module:

freshpy.errors.exceptions

Synopsis:

Collection of exception classes relating to the freshpy library

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

02 Jan 2026

exception freshpy.errors.exceptions.APIConnectionError(*args, **kwargs)[source]

This exception is used when the API query could not be completed due to connection aborts and/or timeouts.

Added in version 1.0.0.

exception freshpy.errors.exceptions.APIRequestError(*args, **kwargs)[source]

This exception is used for generic API request errors when there isn’t a more specific exception.

Added in version 1.0.0.

exception freshpy.errors.exceptions.CurrentlyUnsupportedError(*args, **kwargs)[source]

This exception is used when a feature or functionality being used is currently unsupported.

Added in version 1.0.0.

exception freshpy.errors.exceptions.DELETERequestError(*args, **kwargs)[source]

This exception is used for generic DELETE request errors when there isn’t a more specific exception.

Added in version 1.0.0.

exception freshpy.errors.exceptions.DataMismatchError(*args, **kwargs)[source]

This exception is used when there is a mismatch between two data sources.

Added in version 1.0.0.

exception freshpy.errors.exceptions.FeatureNotConfiguredError(*args, **kwargs)[source]

This exception is used when an API request fails because a feature is not configured.

Added in version 1.0.0.

exception freshpy.errors.exceptions.FreshPyError[source]

This is the base class for FreshPy exceptions.

Added in version 1.0.0.

exception freshpy.errors.exceptions.GETRequestError(*args, **kwargs)[source]

This exception is used for generic GET request errors when there is not a more specific exception.

Added in version 1.0.0.

exception freshpy.errors.exceptions.InvalidDataTypeError(*args, **kwargs)[source]
exception freshpy.errors.exceptions.InvalidFieldError(*args, **kwargs)[source]

This exception is used when an invalid field is provided.

Added in version 1.0.0.

exception freshpy.errors.exceptions.InvalidFilterError(*args, **kwargs)[source]

This exception is used when an invalid filter for an API call is provided.

Added in version 2.0.0.

exception freshpy.errors.exceptions.InvalidFilterLogicError(*args, **kwargs)[source]

This exception is used when an invalid filter logic operator is supplied.

Added in version 1.0.0.

exception freshpy.errors.exceptions.InvalidPayloadValueError(*args, **kwargs)[source]

This exception is used when an invalid value is provided for a payload field.

Added in version 1.0.0.

exception freshpy.errors.exceptions.InvalidPredefinedFilterError(*args, **kwargs)[source]

This exception is used when the API query could not be completed due to connection aborts and/or timeouts.

Added in version 1.0.0.

exception freshpy.errors.exceptions.InvalidRequestTypeError(*args, **kwargs)[source]

This exception is used when an invalid API request type is provided.

Added in version 1.0.0.

exception freshpy.errors.exceptions.InvalidURLError(*args, **kwargs)[source]

This exception is used when a provided URL is invalid.

Added in version 1.0.0.

exception freshpy.errors.exceptions.LookupMismatchError(*args, **kwargs)[source]

This exception is used when a lookup value does not match the supplied lookup type.

Added in version 1.0.0.

exception freshpy.errors.exceptions.MissingAuthDataError(*args, **kwargs)[source]

This exception is used when authentication data is not supplied and therefore a connection cannot occur.

Added in version 1.0.0.

exception freshpy.errors.exceptions.MissingRequiredDataError(*args, **kwargs)[source]

This exception is used when a function or method is missing one or more required arguments.

Changed in version 3.0.0: It is now possible to specify the missing argument for the init message.

Added in version 1.0.0.

exception freshpy.errors.exceptions.NotFoundResponseError(*args, **kwargs)[source]

This exception is used when an API query returns a 404 response and there isn’t a more specific class.

Added in version 1.0.0.

exception freshpy.errors.exceptions.PATCHRequestError(*args, **kwargs)[source]

This exception is used for generic PATCH request errors when there isn’t a more specific exception.

Added in version 3.0.0.

exception freshpy.errors.exceptions.POSTRequestError(*args, **kwargs)[source]

This exception is used for generic POST request errors when there isn’t a more specific exception.

Added in version 1.0.0.

exception freshpy.errors.exceptions.PUTRequestError(*args, **kwargs)[source]

This exception is used for generic PUT request errors when there isn’t a more specific exception.

Added in version 1.0.0.

Return to Top


Handlers Module (freshpy.errors.handlers)

This sub-module contains various error handling functions that are leveraged throughout the library.

Module:

freshpy.errors.handlers

Synopsis:

Functions that handle various error situations within the namespace

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

02 Jan 2026

freshpy.errors.handlers.eprint(*args, **kwargs)[source]

This function behaves the same as the print() function but is leveraged to print errors to sys.stderr.

freshpy.errors.handlers.get_exception_type(exc)[source]

This function returns the exception type (e.g. RuntimeError, TypeError, etc.) for a given exception.

Added in version 3.0.0.

Returns:

The exception type as a string

Return to Top


Tools & Utilities

This section includes modules that contain tools and utilities leveraged by other scripts.


Core Utilities Module (freshpy.utils.core_utils)

This module includes various utilities to assist in converting dictionaries to JSON, formatting timestamps, etc.

Module:

freshpy.utils.core_utils

Synopsis:

Collection of supporting utilities and functions to complement the primary modules

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

04 Jan 2026

freshpy.utils.core_utils.construct_query_string(existing_query=None, appendage=None)[source]

This function assists in constructing query strings for URIs to ensure they follow the appropriate format.

Added in version 1.0.0.

Parameters:

  • existing_query (str, None) – The existing query string (if any)

  • appendage (str, None) – The new addition to the query string to be appended (if any)

Returns:

The constructed query string

freshpy.utils.core_utils.is_data_type(value, data_type)[source]

This function validates that a given value has an expected data type.

Added in version 3.0.0.

Parameters:

  • value – The value to be evaluated

  • data_type – A data type (e.g. str, int, etc.) or an iterable containing multiple data types

Returns:

Boolean indicating whether the value matches the data type(s)

freshpy.utils.core_utils.is_iterable(value, exclude_str=True)[source]

This function checks whether a value is an iterable, optionally excluding str and bytes

Added in version 3.0.0.

Parameters:

  • value – The value to be evaluated

  • exclude_str (bool) – Exclude str and bytes data types from being considered iterables

Returns:

Boolean indicating whether the value is an iterable

freshpy.utils.core_utils.url_decode(encoded_string)[source]

This function decodes a url-encoded string.

Added in version 1.0.0.

Parameters:

encoded_string (str) – The url-encoded string

Returns:

The unencoded string

freshpy.utils.core_utils.url_encode(raw_string)[source]

This function encodes a string for use in URLs.

Added in version 1.0.0.

Parameters:

raw_string (str) – The raw string to be encoded

Returns:

The encoded string

freshpy.utils.core_utils.validate_data_type(value, data_type, value_id=None, raise_exception=True, custom_msg=None)[source]

This function validates whether a value matches given data type(s) and raises an exception and/or logs an error.

Added in version 3.0.0.

Parameters:

  • value – The value to be evaluated

  • data_type – A data type (e.g. str, int, etc.) or an iterable containing multiple data types

  • value_id (str, None) – The name of the variable or field (e.g. agent_id)

  • raise_exception (bool) – Raise an exception if the data types do not match (True by default)

  • custom_msg (str, None) – An optional custom message to append to the error/exception message

Returns:

None

Raises:

freshpy.errors.exceptions.InvalidDataTypeError

freshpy.utils.core_utils.validate_numeric_value(value, param_name=None)[source]

This function checks a parameter value to ensure that it is an integer or a numeric string.

Added in version 3.0.0.

Parameters:

  • value – The parameter value to be validated

  • param_name (str, None) – The name of the parameter being validated (optional)

Returns:

None

Raises:

freshpy.errors.exceptions.InvalidDataTypeError

Return to Top


Logging Utilities Module (freshpy.utils.log_utils)

This module includes various utilities to assist with logging.

Module:

freshpy.utils.log_utils

Synopsis:

Collection of logging utilities and functions

Usage:

from freshpy.utils import log_utils

Example:

logger = log_utils.initialize_logging(__name__)

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

31 Dec 2025

class freshpy.utils.log_utils.LessThanFilter(exclusive_maximum, name='')[source]

This class allows filters to be set to limit log levels to only less than a specified level.

See also

Zoey Greer is the original author of this class which was provided on Stack Overflow.

filter(record)[source]

This method returns a Boolean integer value indicating whether a message should be logged.

Note

A non-zero return indicates that the message will be logged.

freshpy.utils.log_utils.initialize_logging(logger_name=None, log_level=None, formatter=None, debug=None, no_output=None, file_output=None, file_log_level=None, log_file=None, overwrite_log_files=None, console_output=None, console_log_level=None, syslog_output=None, syslog_log_level=None, syslog_address=None, syslog_port=None)[source]

This function initializes logging for the freshpy library.

Return to Top


Version Module (freshpy.utils.version)

This module is the primary source of the current version of the freshpy package.

Module:

freshpy.utils.version

Synopsis:

This simple script retrieves and defines the package version

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

31 Dec 2025

freshpy.utils.version.get_full_version() → str[source]

This function returns the current full version of the freshpy package.

Changed in version 1.4.0: The function now retrieves the version from the package metadata, rather than from the __version__ special variable.

Retrieves the package version from the installed package metadata, which is populated from the version field in pyproject.toml.

freshpy.utils.version.get_major_minor_version() → str[source]

Return the current major.minor (i.e., X.Y) version of the package.

Changed in version 1.4.0: The function utilizes the freshpy.utils.version.get_full_version() function to get the package version rather than using __version__.

Return to Top