Introduction

A Python module with a collection of useful tools for Brazilians (and anyone else who wants to use it). Take a look at CHANGELOG.md for the changes.

Brief History

I started studying Python recently and wanted to do something that would be useful. Enjoy toolkitbrazil.

Overview

Here's a quick overview of what the library has at the moment:

• Random generation of CPF and CNPJ numbers
• CPF and CNPJ validation
• Checks which state a DDD belongs to
• Checks if a year is a leap year
• Calculates the date of Easter Sunday or Carnival Tuesday for a given year
• Check if a specific date is Easter Sunday or Carnival Tuesday
• Returns the capital of a state
• Returns city and state os a zip code
• String cleaner

How to install

pip install toolkitbrazil

Usage

import toolkitbrazil as tkb
from datetime import date

# Remove diacritics, non alpha chars, multiple spaces and convert string to upper case
print(tkb.strClean('A héalt#hy  dìet is    esse&ntiãl  for    go(od heàlth and    nutrition  '))
# Return: 'A HEALTHY DIET IS ESSENTIAL FOR GOOD HEALTH AND NUTRITION'

# Generate a random CPF
print(tkb.rngCPF())
# Sample return: 75269169703

# Generate a random CPF of specific UF
print(tkb.rngCPF('SP'))
# Sample return: 27039729890

# Validate a CPF
print(tkb.valCPF(75269169703))
# Return: True

# Generate a random CNPJ of the headquarters (branch 0001)
print(tkb.rngCNPJ())
# Sample return: 86978319000101

# Generate a random CNPJ of a branch (any branch)
print(tkb.rngCNPJfiliais())
# Sample return: 94318840326682

# Generate a random CNPJ of a desired branch (1 to 9999)
print(tkb.rngCNPJfiliais(187))
# Sample return: 50138939018728

# Validate a CNPJ
print(tkb.valCNPJ(86978319000101))
# Return: True

# Check the UF of the CPF
print(tkb.ufCPF(75269169703))
# Return: ['ES', 'RJ']

# Check the UF of the DDD or phone number (using first two digits of any number)
print(tkb.ufDDD(61))
# Return: ['DF', 'GO']
print(tkb.ufDDD(11987654321))
# Return: ['SP']

# Check the capital of a UF
print(tkb.ufCapital('SP'))
# Return ['SAO PAULO', 'SP']

# Validate a CPF and check its UF
print(tkb.valCPFuf(75269169703, 'SP'))
# Return False (it's a valid CPF but from another UF)

# Check if it is a leap year
print(tkb.valBissexto(2024))
# Return: True

# Calculates the date of Easter Sunday for a given year
print(tkb.dtPascoa(2025))
# Return 2025-04-20

# Check if a specific date is Easter Sunday
print(tkb.valPascoa(date(2025, 4, 20)))
# Return: True

# Calculates the date of Carnival Tuesday for a given year
print(tkb.dtCarnaval(2025))
# Return 2025-03-04

# Check if a specific date is Carnival Tuesday
print(tkb.valCarnaval(date(2025, 3, 4)))
# Return: True

# Generate a random car's license plate (with hyphen or not)
print(tkb.rngPlaca())
# Sample return: IDY1G29
print(tkb.rngPlaca(h=True))
# Sample return: DTQ-2D21

# Validate an e-mail
print(tkb.valEmail('test@me.com'))
# Return: True

# Check a zip code and return a list containing city and state [cidade, uf]
print(tkb.ufCep('01001-000'))
# Return ['SAO PAULO', 'SP']
print(tkb.ufCep(80020000))
# Return ['CURITIBA', 'PR']

Authors

Ricardo Colombani - @coloric

License

MIT