Utilities

Credential Utilities

Module:

pydplus.credentials

Synopsis:

Secure parsing and handling for RSA ID Plus legacy key material

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

30 Mar 2026

pydplus.credentials.IDPlusKeyMaterial

alias of IDPlusLegacyKeyMaterial

class pydplus.credentials.IDPlusLegacyKeyMaterial(customer_name: str, access_id: str, access_key_pem: str, admin_rest_api_url: str, description: str | None = None)

Bases: object

Typed RSA ID Plus legacy credential material parsed from a .key JSON file.

Parameters:

• customer_name (str) – The RSA tenant customer name from the key file

• access_id (str) – The legacy API access identifier

• access_key_pem (str) – The RSA private key in PEM format

• admin_rest_api_url (str) – The Admin REST API base URL for the tenant

• description (str, None) – Optional free-form description from the key file

Raises:

pydplus.errors.exceptions.IDPlusCredentialError

property default_pem_filename: str

Return a sanitized default filename for persisted private key material.

classmethod from_file(path: str | Path) → IDPlusLegacyKeyMaterial

Parse key material from a .key file path and validate the result.

Parameters:

path – The path to the .key JSON file

Returns:

Parsed and validated key material

Raises:

TypeError, pydplus.errors.exceptions.IDPlusCredentialError

classmethod from_json_text(text: str) → IDPlusLegacyKeyMaterial

Parse key material from JSON text and validate the resulting object.

Parameters:

text (str) – JSON content for the RSA ID Plus .key file

Returns:

Parsed and validated key material

Raises:

TypeError, pydplus.errors.exceptions.IDPlusCredentialError

private_key_bytes() → bytes

Return the private key as UTF-8 encoded bytes.

property tenant_host: str

The host component parsed from admin_rest_api_url.

validate() → None

Validate the key material fields and URL/private-key requirements.

:raises pydplus.errors.exceptions.IDPlusCredentialError

write_private_key_pem(path: str | Path | None = None, overwrite: bool = False) → Path

Persist private key material to disk with strict file-system protections.

Note

Persistence is explicit-only and never occurs automatically during parsing.

Parameters:

• path – Optional destination path (Defaults to ~/.pydplus/certs/<safe_filename>.pem)

• overwrite – Whether to overwrite an existing destination file (False by default)

Returns:

The final path for the persisted PEM file

Raises:

FileExistsError, pydplus.errors.exceptions.IDPlusCredentialError

pydplus.credentials.from_file(path: str | Path) → IDPlusLegacyKeyMaterial

Parse and validate RSA ID Plus key material from file.

Parameters:

path – Path to a .key credential file

Returns:

Parsed and validated key material

pydplus.credentials.from_json_text(text: str) → IDPlusLegacyKeyMaterial

Parse and validate RSA ID Plus key material from JSON text.

Parameters:

text (str) – JSON content for a .key credential file

Returns:

Parsed and validated key material

Core Utilities

Module:

pydplus.utils.core_utils

Synopsis:

Collection of supporting utilities and functions to complement the primary modules

Usage:

from pydplus.utils import core_utils

Example:

encoded_string = core_utils.encode_url(decoded_string)

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

30 Mar 2026

pydplus.utils.core_utils.ensure_ending_slash(path: str, path_type: str = 'url') → str

Ensure that a URL ends with a forward slash (/) or backslash (\).

Parameters:

• path (str) – The path (URL or file path) to check and potentially add an ending slash

• path_type (str) – Indicates that the path is for a url (default) or a file

Returns:

The URL string with an ending forward slash

Raises:

pydplus.errors.exceptions.InvalidParameterError

pydplus.utils.core_utils.file_exists(file_path: str) → bool

Check to see if a file exists at a given file path.

Parameters:

file_path (str) – The full path to the file

Returns:

Boolean value indicating if the file exists

Raises:

TypeError

pydplus.utils.core_utils.get_base_url(url: str, include_scheme: bool = True) → str

Parse a URL to return only the base URL with or without the scheme.

Parameters:

• url (str) – A valid, fully qualified URL

• include_scheme (bool) – Determines if the scheme (e.g. https://) should be included (True by default)

Returns:

The base URL as a string

Raises:

TypeError, pydplus.errors.exceptions.InvalidURLError

pydplus.utils.core_utils.get_env_variable_name_by_environment(field: str, env: str | None = None) → str

Retrieve an environment variable name based on a given environment name.

Parameters:

• field (str) – The field mapped to an environment variable (e.g. connection_type, verify_ssl, etc.)

• env (str, None) – The environment associated with the environment variable (e.g. PROD, DEV, etc.)

Returns:

The environment variable name as a string (e.g. PYDPLUS_VERIFY_SSL)

Raises:

TypeError, RuntimeError

pydplus.utils.core_utils.get_file_type(file_path: str) → str

Attempt to identify if a given file path is for a YAML or JSON file.

Parameters:

file_path (str) – The full path to the file

Returns:

The file type in string format (e.g. yaml or json)

Raises:

TypeError, FileNotFoundError, pydplus.errors.exceptions.UnknownFileTypeError

pydplus.utils.core_utils.get_random_string(length: int = 32, prefix_string: str = '') → str

Return a random alphanumeric string.

Parameters:

• length (int) – The length of the string (32 by default)

• prefix_string (str) – A string to which the random string should be appended (optional)

Returns:

The randomized alphanumeric string

pydplus.utils.core_utils.normalize_oauth_scope(scope_value: Any, required: bool = False) → str | None

Normalize and validate OAuth scope values into canonical +-delimited format.

Parameters:

• scope_value – Scope value defined as a +-delimited or space-delimited string, or iterable of scope strings

• required (bool) – Indicates whether a scope value is mandatory (False by default)

Returns:

The normalized +-delimited scope string when defined

Raises:

TypeError, ValueError, pydplus.errors.exceptions.MissingRequiredDataError

pydplus.utils.core_utils.remove_ending_slash(path: str) → str

Remove a trailing slash at the end of a URL or endpoint when present.

Parameters:

path (str) – The URL or path

Returns:

The path string without a trailing slash

Raises:

TypeError

pydplus.utils.core_utils.split_file_path(full_path: str) → Tuple[str, str]

Split a full file path into separate variables for file path and file name.

Parameters:

full_path (str) – The full path to the file including the file name

Returns:

The file path and file name strings as separate variables

Raises:

TypeError

pydplus.utils.core_utils.url_decode(encoded_string: str) → str

Decode a url-encoded string.

Parameters:

encoded_string (str) – The url-encoded string

Returns:

The unencoded string

Raises:

TypeError

pydplus.utils.core_utils.url_encode(raw_string: str) → str

Encode a string for use in URLs.

Parameters:

raw_string (str) – The raw string to be encoded

Returns:

The encoded string

Raises:

TypeError

Helper Utilities

Module:

pydplus.utils.helper

Synopsis:

Module that allows the pydplus library to leverage a helper configuration file

Usage:

from pydplus.utils import helper

Example:

helper_settings = helper.get_settings('/tmp/helper.yml', 'yaml')

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

01 Apr 2026

pydplus.utils.helper.get_helper_settings(file_path: str, file_type: str = 'json', defined_settings: dict | None = None) → dict[str, str | bool | dict]

Return a dictionary of the defined helper settings.

Parameters:

• file_path (str) – The file path to the helper configuration file

• file_type (str) – Defines the helper configuration file as a json file (default) or a yaml/yml file

• defined_settings (dict, None) – Core object settings (if any) defined via the defined_settings parameter

Returns:

Dictionary of helper variables

Raises:

pydplus.errors.exceptions.InvalidHelperFileTypeError

pydplus.utils.helper.import_helper_file(file_path: str, file_type: str) → dict

Import a YAML (.yml, .yaml) or JSON (.json) helper config file.

Parameters:

• file_path (str) – The file path to the YAML file

• file_type (str) – Defines the file type as yaml, yml, or json

Returns:

The parsed configuration data

Raises:

FileNotFoundError, pydplus.errors.exceptions.InvalidHelperFileTypeError

Logging Utilities

Module:

pydplus.utils.log_utils

Synopsis:

Collection of logging utilities and functions

Usage:

from pydplus.utils import log_utils

Example:

logger = log_utils.initialize_logging(__name__)

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

30 Mar 2026

class pydplus.utils.log_utils.LessThanFilter(exclusive_maximum: int, name: str = '')

Bases: Filter

Allow 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: LogRecord) → bool

Return whether a message should be logged.

Note

A truthy return indicates that the message will be logged.

pydplus.utils.log_utils.initialize_logging(logger_name: str | None = None, log_level: str | int | None = None, formatter: str | Formatter | None = None, debug: bool | None = None, no_output: bool | None = None, file_output: bool | None = None, file_log_level: str | int | None = None, log_file: str | None = None, overwrite_log_files: bool | None = None, console_output: bool | None = None, console_log_level: str | int | None = None, syslog_output: bool | None = None, syslog_log_level: str | int | None = None, syslog_address: str | None = None, syslog_port: int | None = None) → Logger

Initialize and configure a logger instance.

Parameters:

• logger_name – The logger name used by logging.getLogger().

• log_level – The overall logger level.

• formatter – Optional formatter instance or format string.

• debug – If True, force all logger and handler levels to debug.

• no_output – If True, add a logging.NullHandler and skip all output handlers.

• file_output – If True, enable file-based logging output.

• file_log_level – Log level for the file handler.

• log_file – Log file name or path for file output.

• overwrite_log_files – If True, overwrite the log file instead of appending.

• console_output – If True, enable console logging output.

• console_log_level – Log level for console output.

• syslog_output – If True, enable syslog output.

• syslog_log_level – Log level for syslog output.

• syslog_address – Hostname or IP address for the syslog endpoint.

• syslog_port – Port for the syslog endpoint.

Returns:

A configured logging.Logger instance.

Version Utilities

Module:

pydplus.utils.version

Synopsis:

This module contains the package version information

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

30 Mar 2026

pydplus.utils.version.get_full_version() → str

Return the current full version of the pydplus package.

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

Returns:

The current package version as a string

pydplus.utils.version.get_major_minor_version(full_version: str | None = None) → str

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

Parameters:

full_version (str, None) – The full package version (e.g. X.Y.Z)

Returns:

The current package version (X.Y) as a string

pydplus.utils.version.get_version_from_pyproject(pyproject_path: str | None = None) → str

Retrieve the current version from the pyproject.toml file.

Parameters:

pyproject_path (str, None) – The path to the pyproject.toml file (optional)

Returns:

The current package version as a string