Utilities

json_dumps(data)

Serialize data to a JSON formatted bytes object.

Utility function used to allow users to pass an already serialized JSON.

Parameters:

Name	Type	Description	Default
data	str | bytes | bytearray | Any	Data to be serialized.	required

Returns:

Type	Description
bytes	JSON formatted bytes object.

Source code in src/aiosalesforce/utils.py

def json_dumps(data: str | bytes | bytearray | Any) -> bytes:
    """
    Serialize data to a JSON formatted bytes object.

    Utility function used to allow users to pass an already serialized JSON.

    Parameters
    ----------
    data : str | bytes | bytearray | Any
        Data to be serialized.

    Returns
    -------
    bytes
        JSON formatted bytes object.

    """
    if isinstance(data, str):
        return data.encode("utf-8")
    if isinstance(data, bytearray):
        return bytes(data)
    if isinstance(data, bytes):
        return data
    return orjson.dumps(data, option=orjson.OPT_OMIT_MICROSECONDS | orjson.OPT_UTC_Z)

json_loads(data)

Deserialize JSON formatted data.

Parameters:

Name	Type	Description	Default
data	str | bytes | bytearray	JSON formatted data.	required

Returns:

Type	Description
Any	Deserialized data.

Source code in src/aiosalesforce/utils.py

def json_loads(data: str | bytes | bytearray) -> Any:
    """
    Deserialize JSON formatted data.

    Parameters
    ----------
    data : str | bytes | bytearray
        JSON formatted data.

    Returns
    -------
    Any
        Deserialized data.

    """
    return orjson.loads(data)

format_soql(query, *args, **kwargs)

Format SOQL query template with dynamic parameters.

While SOQL queries are safe by design (cannot create/update/delete records), it is still possible to expose sensitive information via SOQL injection. It is always recommended to use this function instead of string formatting.

You should never surround your parameters with single quotes in the query template - this is done automatically by this function when necessary. E.g., "SELECT Id FROM Object WHERE Value = {value}"

The only exception to this rule is when you use the 'like' format spec. The 'like' format spec is used to escape special characters in a LIKE pattern when a portion of it is dynamic. E.g., "SELECT Id FROM Object WHERE Value LIKE '%{value:like}'"

If you don't use the 'like' format spec when formatting LIKE statements, you will get unnecessary quotes and special query characters (% and _) will not be escaped. This would make you vulnerable to SOQL injection.

Examples:

>>> format_soql("SELECT Id FROM Account WHERE Name = {}", "John Doe")
"SELECT Id FROM Account WHERE Name = 'John Doe'"
>>> format_soql("SELECT Id FROM Account WHERE Name = {name}", name="John Doe")
"SELECT Id FROM Account WHERE Name = 'John Doe'"
>>> format_soql("SELECT Id FROM Account WHERE Name LIKE {value}", value="John%")
"SELECT Id FROM Account WHERE Name LIKE 'John%'"
>>> format_soql(
>>>     "SELECT Id FROM Record WHERE Description LIKE '% fails {pattern:like}'",
>>>     pattern="50% of the time",
>>> )
"SELECT Id FROM Record WHERE Description LIKE '% fails 50\% of the time'"

Parameters:

Name	Type	Description	Default
query	LiteralString	SOQL query template.	required

Returns:

Type	Description
str	Formatted SOQL query.

Source code in src/aiosalesforce/utils.py

def format_soql(query: LiteralString, *args, **kwargs) -> str:
    """
    Format SOQL query template with dynamic parameters.

    While SOQL queries are safe by design (cannot create/update/delete records),
    it is still possible to expose sensitive information via SOQL injection.
    It is always recommended to use this function instead of string formatting.

    You should never surround your parameters with single quotes in the query
    template - this is done automatically by this function when necessary.
    E.g., "SELECT Id FROM Object WHERE Value = {value}"

    The only exception to this rule is when you use the 'like' format spec.
    The 'like' format spec is used to escape special characters in a LIKE pattern
    when a portion of it is dynamic.
    E.g., "SELECT Id FROM Object WHERE Value LIKE '%{value:like}'"

    If you don't use the 'like' format spec when formatting LIKE statements,
    you will get unnecessary quotes and special query characters
    (% and _) will not be escaped. This would make you vulnerable to SOQL injection.

    Examples
    --------
    >>> format_soql("SELECT Id FROM Account WHERE Name = {}", "John Doe")
    "SELECT Id FROM Account WHERE Name = 'John Doe'"
    >>> format_soql("SELECT Id FROM Account WHERE Name = {name}", name="John Doe")
    "SELECT Id FROM Account WHERE Name = 'John Doe'"
    >>> format_soql("SELECT Id FROM Account WHERE Name LIKE {value}", value="John%")
    "SELECT Id FROM Account WHERE Name LIKE 'John%'"
    >>> format_soql(
    >>>     "SELECT Id FROM Record WHERE Description LIKE '% fails {pattern:like}'",
    >>>     pattern="50% of the time",
    >>> )
    "SELECT Id FROM Record WHERE Description LIKE '% fails 50\\% of the time'"

    Parameters
    ----------
    query : LiteralString
        SOQL query template.

    Returns
    -------
    str
        Formatted SOQL query.

    """
    # Use vformat to avoid unnecessary args/kwargs unpacking
    return SoqlFormatter().vformat(query, args, kwargs)