sc4py.masks module

exception sc4py.masks.DVException[source]

Bases: MaskException

Exceção para erro de dígito verificador (DV) inválido.

exception sc4py.masks.EmptyMaskException[source]

Bases: MaskException

Exceção para máscara vazia ou nula.

exception sc4py.masks.MaskException[source]

Bases: Exception

Exceção base para erros relacionados a máscaras.

exception sc4py.masks.MaskNotStringException[source]

Bases: MaskException

Exceção para máscara que não é string.

exception sc4py.masks.MaskWithoutDigitsException[source]

Bases: MaskException

Exceção para máscara sem dígitos ou placeholders de dígitos.

exception sc4py.masks.MaskWithoutSpecialCharsException[source]

Bases: MaskException

Exceção para máscara sem caracteres especiais (apenas dígitos/placeholders).

exception sc4py.masks.TooManyDigitsException[source]

Bases: MaskException

Exceção para quantidade de dígitos acima do permitido.

sc4py.masks.apply_mask(value, mask)[source]

Aplica uma máscara a um valor, inserindo caracteres especiais conforme o padrão.

Parameters:

value (str) – Valor a ser mascarado.
mask (str) – Máscara no formato com dígitos (9, # ou 0) e separadores.

Returns:

Valor mascarado conforme a máscara.

Return type:

str

Raises:

MaskException – Se o número de dígitos não corresponder ao esperado.

Examples

>>> apply_mask('12345678901', '###.###.###-##')
'123.456.789-01'
>>> apply_mask('1', '##-##')
'00-01'

sc4py.masks.validate_dv_by_mask(value, mask, force=True, validate_dv=<function validate_mod11>)[source]

Valida um valor mascarado e seus dígitos verificadores conforme a máscara.

Parameters:

value (str) – Valor a ser validado.
mask (str) – Máscara com zeros (‘0’) indicando posições de DV.
force (bool, opcional) – Se True, aplica a máscara antes de validar. Padrão: True.
validate_dv (callable, opcional) – Função de validação de DV. Padrão: validate_mod11.

Returns:

Valor validado e mascarado.

Return type:

str

Raises:

ValueError – Se value não for string ou for vazio.
MaskException – Se a máscara for inválida.
DVException – Se o DV for inválido.

Examples

>>> validate_dv_by_mask('12345678909', '#########00')
'12345678909'
>>> validate_dv_by_mask('12345678908', '#########00')
DVException

sc4py.masks.validate_mask(mask)[source]

Valida se a máscara é válida, contendo dígitos/placeholders e caracteres especiais.

Parameters:

mask (str) – Máscara a ser validada.

Returns:

None

Raises:

MaskNotStringException – Se a máscara não for string.
EmptyMaskException – Se a máscara for vazia.
MaskWithoutDigitsException – Se não houver dígitos/placeholders.
MaskWithoutSpecialCharsException – Se não houver caracteres especiais.

Examples

>>> validate_mask('###.###-##')
>>> validate_mask('999-9999')

sc4py.masks.validate_masked_value(value, mask, force=True)[source]

Valida se um valor está de acordo com a máscara informada.

Parameters:

value (str) – Valor a ser validado.
mask (str) – Máscara de validação.
force (bool, opcional) – Se True, aplica a máscara antes de validar. Padrão: True.

Returns:

Valor mascarado validado.

Return type:

str

Raises:

MaskException – Se o valor não corresponder à máscara.

Examples

>>> validate_masked_value('12345678901', '###.###.###-##')
'123.456.789-01'
>>> validate_masked_value('123.456.789-01', '###.###.###-##', force=False)
'123.456.789-01'

sc4py.masks.validate_mod11(unmasked_value, num_len, dvs_len)[source]

Valida dígitos verificadores (DV) usando o algoritmo módulo 11.

Parameters:

unmasked_value (str) – Valor numérico sem máscara.
num_len (int) – Quantidade total de dígitos.
dvs_len (int) – Quantidade de dígitos verificadores (DV) no final.

Returns:

None

Raises:

TooManyDigitsException – Se num_len > 11.
DVException – Se o DV calculado não corresponder ao informado.

Examples

>>> validate_mod11('12345678909', 11, 2)  # CPF válido
>>> validate_mod11('12345678901', 11, 2)  # DVException