cpf-dv 1.0.0

Utility resources to calculate check digits on CPF (Brazilian personal ID)

Utility class to calculate check digits on CPF (Brazilian individual taxpayer ID).

Python Support

Passing ✔	Passing ✔	Passing ✔	Passing ✔	Passing ✔

Installation

$ pip install cpf-dv

Import

from cpf_dv import CpfCheckDigits

Usage

Basic Usage

# Calculate check digits from a 9-digit CPF base
check_digits = CpfCheckDigits("054496519")

print(check_digits.first_digit)    # returns 1
print(check_digits.second_digit)   # returns 0
print(check_digits.to_string())    # returns '05449651910'
print(check_digits.to_list())      # returns [0, 5, 4, 4, 9, 6, 5, 1, 9, 1, 0]

Input Formats

The CpfCheckDigits class accepts multiple input formats:

String Input

# Plain string (non-numeric characters are automatically stripped)
check_digits = CpfCheckDigits("054496519")
check_digits = CpfCheckDigits("054.496.519-10")  # formatting is ignored
check_digits = CpfCheckDigits("054496519")        # 9 digits
check_digits = CpfCheckDigits("05449651910")     # 11 digits (only first 9 are used)

List of Strings

# List of single-character strings
check_digits = CpfCheckDigits(["0", "5", "4", "4", "9", "6", "5", "1", "9"])

# List with multi-digit strings (automatically flattened)
check_digits = CpfCheckDigits(["054496519"])      # flattens to individual digits
check_digits = CpfCheckDigits(["054", "496", "519"])  # also flattens

List of Integers

# List of single-digit integers
check_digits = CpfCheckDigits([1, 2, 3, 4, 5, 6, 7, 8, 9])

# List with multi-digit integers (automatically flattened)
check_digits = CpfCheckDigits([123456789])         # flattens to individual digits
check_digits = CpfCheckDigits([123, 456, 789])     # also flattens

### Properties

#### `first_digit: int`

Returns the first check digit (10th digit of the CPF).

```python
check_digits = CpfCheckDigits("054496519")
print(check_digits.first_digit)  # returns 1

second_digit: int

Returns the second check digit (11th digit of the CPF).

check_digits = CpfCheckDigits("054496519")
print(check_digits.second_digit)  # returns 0

Methods

to_list() -> list[int]

Returns the complete CPF as a list of integers (9 base digits + 2 check digits).

check_digits = CpfCheckDigits("054496519")
print(check_digits.to_list())  # returns [0, 5, 4, 4, 9, 6, 5, 1, 9, 1, 0]

to_string() -> str

Returns the complete CPF as a string (9 base digits + 2 check digits).

check_digits = CpfCheckDigits("054496519")
print(check_digits.to_string())  # returns '05449651910'

Examples

from cpf_dv import CpfCheckDigits

# Calculate check digits for a CPF base
base = "054496519"
check_digits = CpfCheckDigits(base)

# Get individual check digits
first = check_digits.first_digit    # 1
second = check_digits.second_digit   # 0

# Get complete CPF
complete = check_digits.to_string()  # '05449651910'

# Work with formatted input
formatted = CpfCheckDigits("054.496.519-10")
print(formatted.to_string())  # '05449651910'

# Work with list input
list_input = CpfCheckDigits([0, 5, 4, 4, 9, 6, 5, 1, 9])
print(list_input.to_string())  # '05449651910'

Error Handling

The package raises specific exceptions for different error scenarios:

CpfCheckDigitsInputTypeError

Raised when the input type is not supported (must be str, list[str], or list[int]).

from cpf_dv import CpfCheckDigits, CpfCheckDigitsInputTypeError

try:
    CpfCheckDigits(12345678901)  # int not allowed
except CpfCheckDigitsInputTypeError as e:
    print(e)  # CPF input must be of type str, list[str] or list[int]. Got int.

CpfCheckDigitsInputLengthError

Raised when the input does not contain 9 to 11 digits.

from cpf_dv import CpfCheckDigits, CpfCheckDigitsInputLengthError

try:
    CpfCheckDigits("12345678")  # only 8 digits
except CpfCheckDigitsInputLengthError as e:
    print(e)  # CPF input "12345678" does not contain 9 to 11 digits. Got 8 in "12345678".

CpfCheckDigitsInputNotValidError

Raised when the input is forbidden for some restriction, like repeated digits like 111.111.111, 222.222.222, 333.333.333 and so on.

from cpf_dv import CpfCheckDigits, CpfCheckDigitsInputNotValidError

try:
    CpfCheckDigits(["999", "999", "999"])
except CpfCheckDigitsInputNotValidError as e:
    print(e)  # CPF input ['999', '999', '999'] is invalid. Repeated digits are not considered valid.

Catch any error from the package

All errors extend from a common error instance CpfCheckDigitsError, so you can use this type to handle any error thrown by the module.

from cpf_dv import CpfCheckDigitsError

try:
  # some risky code run
except CpfCheckDigitsError as e:
  # do something

Features

• ✅ Multiple Input Formats: Accepts strings, lists of strings, or lists of integers
• ✅ Format Agnostic: Automatically strips non-numeric characters from string input
• ✅ Auto-Expansion: Automatically expands multi-digit numbers in lists to individual digits
• ✅ Lazy Evaluation: Check digits are calculated only when accessed (via properties)
• ✅ Type Safety: Built with Python 3.10+ type hints
• ✅ Zero Dependencies: No external dependencies required
• ✅ Comprehensive Error Handling: Specific exceptions for different error scenarios

API Reference

CpfCheckDigits Class

Constructor

CpfCheckDigits(cpf_digits: str | list[str] | list[int]) -> CpfCheckDigits

Creates a new CpfCheckDigits instance from the provided CPF base digits.

Parameters:

• cpf_digits (str | list[str] | list[int]): The CPF base digits (9-11 digits). Can be:
  • A string with 9-11 digits (formatting characters are ignored)
  • A list of strings (each string can be a single digit or multi-digit number)
  • A list of integers (each integer can be a single digit or multi-digit number)

Raises:

• CpfCheckDigitsInputTypeError: If the input type is not supported
• CpfCheckDigitsInputLengthError: If the input does not contain 9-11 digits

Returns:

• CpfCheckDigits: A new instance ready to calculate check digits

Properties

first_digit: int

The first check digit (10th digit of the CPF). Calculated lazily on first access.

second_digit: int

The second check digit (11th digit of the CPF). Calculated lazily on first access.

Methods

to_list() -> list[int]

Returns the complete CPF as a list of 11 integers (9 base digits + 2 check digits).

to_string() -> str

Returns the complete CPF as a string of 11 digits (9 base digits + 2 check digits).

Calculation Algorithm

The package calculates CPF check digits using the official Brazilian algorithm:

1. First Check Digit (10th position):

   • Uses digits 1-9 of the CPF base
   • Applies weights: 10, 9, 8, 7, 6, 5, 4, 3, 2 (from left to right)
   • Calculates: sum(digit × weight) % 11
   • Result: 0 if remainder > 9, otherwise 11 - remainder

2. Second Check Digit (11th position):

   • Uses digits 1-9 + first check digit
   • Applies weights: 11, 10, 9, 8, 7, 6, 5, 4, 3, 2 (from left to right)
   • Calculates: sum(digit × weight) % 11
   • Result: 0 if remainder > 9, otherwise 11 - remainder

Dependencies

• Python: >= 3.10

No external dependencies required.

Contribution & Support

We welcome contributions! Please see our Contributing Guidelines for details. But if you find this project helpful, please consider:

• ⭐ Starring the repository
• 🤝 Contributing to the codebase
• 💡 Suggesting new features
• 🐛 Reporting bugs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG for a list of changes and version history.

---

Made with ❤️ by Lacus Solutions