Miscellaneous Functions¶

General-purpose functions for value retrieval, formatting, and conditional logic, plus utility functions for validating and formatting Brazilian tax identifiers (CNPJ) and international securities identifiers (ISIN). Functions marked vectorized operate element-wise on NumPy arrays.

from everysk.sdk.engines import Expression
expression_engine = Expression()

Value Retrieval¶

port_attribute¶

port_attribute(arr, default=0.0)

Returns the single unique element in arr. Raises an exception if more than one distinct value is found. Returns default when the array is empty.

This function is typically used to extract portfolio-level attributes — such as NLV or reference date — that appear identically on every row of a data store.

import numpy as np

expression_engine.solve('port_attribute(arr)', {'arr': np.array([1000.0, 1000.0, 1000.0])})
# 1000.0

expression_engine.solve('port_attribute(arr)', {'arr': np.array(['USD', 'USD', 'USD'])})
# 'USD'

expression_engine.solve('port_attribute(arr)', {'arr': np.array([])})
# 0.0

single_value¶

single_value(arr, default=None)

Returns the unique value in arr, or default if the array contains more than one distinct value or is empty.

import numpy as np

expression_engine.solve('single_value(arr)', {'arr': np.array([5, 5, 5])})
# 5

expression_engine.solve('single_value(arr)', {'arr': np.array([1, 2, 3])})
# None

expression_engine.solve('single_value(arr, "mixed")', {'arr': np.array([1, 2, 3])})
# 'mixed'

single_number¶

single_number(arr)

Specialization of single_value that first casts the array to float. Returns 0.0 if the array has more than one distinct value or is empty.

import numpy as np

expression_engine.solve('single_number(arr)', {'arr': np.array([42, 42, 42])})
# 42.0

expression_engine.solve('single_number(arr)', {'arr': np.array([1, 2, 3])})
# 0.0

single_text¶

single_text(arr)

Specialization of single_value that first casts the array to str. Returns '-' if the array has more than one distinct value or is empty.

import numpy as np

expression_engine.solve('single_text(arr)', {'arr': np.array(['BRL', 'BRL', 'BRL'])})
# 'BRL'

expression_engine.solve('single_text(arr)', {'arr': np.array(['BRL', 'USD'])})
# '-'

multiple_text¶

multiple_text(arr, delimiter=',')

Joins the unique elements of arr into a single string, separated by delimiter. Duplicate values are deduplicated and None values are dropped. Returns '-' if no valid values remain.

import numpy as np

expression_engine.solve('multiple_text(arr)', {'arr': np.array(['Equity', 'Bond', 'Equity'])})
# 'Equity, Bond'

expression_engine.solve('multiple_text(arr, " |")', {'arr': np.array(['a', 'b', 'c'])})
# 'a | b | c'

Formatting¶

to_format¶

to_format(value, format)

Vectorized. Formats value into a display string using a format specifier. Returns None if value is None.

The format string combines a type code with an optional decimal precision:

Format	Description	Example input	Example output
`N`	Number	`1.2345` with `N2`	`'1.23'`
`%`	Percentage	`0.2345` with `%2`	`'23.45%'`
`$`	Currency	`123.456` with `$2`	`'$123.46'`
`$S`	Short currency	`123456.789` with `$S2`	`'$123 456.79'`
`$LN`	Currency with notation	`123456.789` with `$LN2`	`'$123.46K'`
`LN`	Long notation	`123456.789` with `LN2`	`'123.46K'`
`S`	Space-separated	`123456.789` with `S0`	`'123 457'`
`D`	Date

expression_engine.solve('to_format(1.2345, "N2")')
# '1.23'

expression_engine.solve('to_format(0.234567, "%2")')
# '23.46%'

expression_engine.solve('to_format(123456.789, "$LN0")')
# '$123K'

import numpy as np
expression_engine.solve('to_format(values, "N2")', {
    'values': np.array([1.2345, 0.234567, 123.456])
})
# ['1.23', '0.23', '123.46']

Array Cleaning¶

drop_none¶

drop_none(arr)

Removes all None values from arr.

import numpy as np

expression_engine.solve('drop_none(arr)', {'arr': np.array([1, None, 2, None, 3])})
# [1, 2, 3]

expression_engine.solve('drop_none(arr)', {'arr': np.array(['a', None, 'b'])})
# ['a', 'b']

Conditional Logic¶

conditional¶

conditional(cond_1, value_if_cond_1, …, cond_n, value_if_cond_n, default)

Evaluates conditions left to right and returns the value paired with the first condition that is True. Returns default when no condition matches.

This is equivalent to a chain of if / elif / else statements. Arguments alternate between conditions and values, ending with a single default.

expression_engine.solve('conditional(False, "a", False, "b", "c")')
# 'c'

expression_engine.solve('conditional(True, "a", False, "b", "c")')
# 'a'

expression_engine.solve('conditional(False, "a", True, "b", "c")')
# 'b'

CNPJ¶

Brazilian companies are identified by a 14-digit CNPJ number. The functions below work with both the raw numeric string ('17210185000161') and the formatted mask ('17.210.185/0001-61').

is_valid_cnpj¶

is_valid_cnpj(value, check_dv=False)

Vectorized. Returns True if value is a structurally valid CNPJ. When check_dv=True, also validates the two check digits.

expression_engine.solve('is_valid_cnpj("17210185000161")', {})
# True

expression_engine.solve('is_valid_cnpj("00000000000000")', {})
# True  # structurally valid, even if not officially issued

expression_engine.solve('is_valid_cnpj("INVALID")', {})
# False

import numpy as np
expression_engine.solve('is_valid_cnpj(values)', {
    'values': np.array(['17210185000161', '12345678000195', 'INVALID', None])
})
# [True, True, False, False]

sanitize_cnpj¶

sanitize_cnpj(value, zfill=True)

Vectorized. Strips all non-numeric characters from value and returns the raw 14-digit string. When zfill=True (default), left-pads the result with zeros to ensure 14 digits.

expression_engine.solve('sanitize_cnpj("17.210.185/0001-61")')
# '17210185000161'

expression_engine.solve('sanitize_cnpj(17210185000161)')
# '17210185000161'

normalize_cnpj¶

normalize_cnpj(value, zfill=False, errors='raise')

Vectorized. Normalizes value to a canonical 14-digit CNPJ string. Unlike sanitize_cnpj, this function validates the result and raises or returns None on invalid input, depending on errors.

`errors`	Behavior on invalid input
`'raise'`	Raises an exception
`'coerce'`	Returns `None`

expression_engine.solve('normalize_cnpj("17.210.185/0001-61")')
# '17210185000161'

expression_engine.solve('normalize_cnpj("invalid", "coerce")')
# None

format_cnpj¶

format_cnpj(value, errors='raise')

Vectorized. Formats value as XX.XXX.XXX/XXXX-XX. On invalid input, raises or returns None depending on errors.

expression_engine.solve('format_cnpj("17210185000161")')
# '17.210.185/0001-61'

expression_engine.solve('format_cnpj("invalid", "coerce")')
# None

import numpy as np
expression_engine.solve('format_cnpj(values, "coerce")', {
    'values': np.array(['17210185000161', 'invalid'])
})
# ['17.210.185/0001-61', None]

cnpj_random¶

cnpj_random(valid_dv=False)

Generates a random 14-digit CNPJ string for testing. When valid_dv=True, the generated CNPJ will have correct check digits.

expression_engine.solve('cnpj_random()')
# '48291037000158'  (example — output varies)

expression_engine.solve('cnpj_random(True)')
# a 14-digit string that passes is_valid_cnpj with check_dv=True

ISIN¶

An ISIN (International Securities Identification Number) is a 12-character code: 2-letter country prefix, 9-character national identifier, and 1 check digit.

is_valid_isin¶

is_valid_isin(value, check_digit=True)

Vectorized. Returns True if value is a valid ISIN. When check_digit=True (default), also validates the check digit using the Luhn algorithm.

expression_engine.solve('is_valid_isin("US0378331005")')
# True  (Apple Inc.)

expression_engine.solve('is_valid_isin("BRPETRACNPR6")')
# True  (Petrobras PN)

expression_engine.solve('is_valid_isin("INVALID")')
# False

expression_engine.solve('is_valid_isin("US0378331004")')
# False  (wrong check digit)

expression_engine.solve('is_valid_isin("US0378331004", False)')
# True  (valid format, check digit skipped)

import numpy as np
expression_engine.solve('is_valid_isin(values)', {
    'values': np.array(['US0378331005', 'BRPETRACNPR6', 'INVALID', None])
})
# [True, True, False, False]