Versão 1.2.0

O Framework CollectionPy é uma ferramenta poderosa projetada para simplificar e aprimorar suas tarefas relacionadas à manipulação de datas, formatação de números em texto e criação rápida de gráficos. Este framework foi desenvolvido com o objetivo de oferecer uma solução eficiente e intuitiva para lidar com operações comuns no desenvolvimento de aplicativos, proporcionando uma experiência de programação mais eficaz e produtiva.

Instalação

pip install collectionpy

Chart

Date

Math

Text

Chart (collectionpy.chart)

A coleção Chart, tem como objetivo facilitar a criação de gráficos web, podendo ser utilizada em qualquer framework web python (django, flask, ...)

ApexCharts (collectionpy.chart.apexcharts)

Chart(x:[], y:[], y_label=[], plot_type='bar', chartId='CollectionPyChart', foreColor='343E59', background= 'fff', fontFamily= "Crimson Text", fontSize = 12, width = None, height = None, dropShadowTop = -7, dropShadowLeft = 7, dropShadowBlur = -10, borderRadius = 5, borderColor = '6e7eaa', borderRight = 25, borserLeft = 15, palette = 2 )

Esse módulo foi criado baseado no framework JS ApexCharts, sendo o objetivo principal desse módulo é facilitar a criação de gráficos WEB, caso deseje saber mais sobre o framework ApexCharts clique aqui para acessar a documentação oficial

Exemplo de uso

Python (Django)

HTML

Resultado

Parâmetros

x (default = []) => Valores do Eixo X, deve ser uma lista de Strings (os dados do Eixo Y serão preenchidos até o limite do eixo X)
Exemplo: ['Piracicaba', 'Americana', 'São Paulo']

y (default = [[]]) => Valores do Eixo Y, deve ser uma lista de listas numérica, caso não tenha valor suficiente no eixo X os valores serão desconsiderados
Exemplo: [
[8, 2, 15, 24],
[12, 5, 2]
]
*** O valor 24 da primeira lista numérica será desconsiderado, pois no eixo X possui apenas 3 posições

y_label (default = []) => Valores do Label do Eixo X, deve ser uma lista de Strings devende ter a mesma quantidade de lista numérica do eixo Y (Caso a Lista seja maior, será desconsiderados as posições maiores do eixo Y, caso seja menor, será atribuido o número do indice no nome)
Exemplo: ['Orçado', 'Realizado']

plot_type (default = 'bar') => Define o tipo de Gráfico, sendo as opções: bar ou line
Obs: Para mais tipos deve ser utilizado a biblioteca JS

chartId (default = 'CollectionPyChart') => Define o id do Gráfico

foreColor (default = '343E59') => Define a cor de Texto do Gráfico

background (default = 'fff') => Define a cor de Fundo do Gráfico

fontFamily (default = 'Crimson Text') => Define a Fonte dos textos do Gráfico

fontSize (default = 12) => Define o tamanho do Texto do Gráfico

width (default = None) => Define a largura do Gráfico (None define como automático)

height (default = None) => Define a altura do Gráfico (None define como automático)

dropShadowTop (default = -7) => Posição TOP da Sombra do Gráfico

dropShadowLeft (default = 7) => Posição LEFT da Sombra do Gráfico

dropShadowBlur (default = -10) => Tamanho do BLUR da Sombra do Gráfico

borderRadius (default = 5) => Tamanho do Radius borda do Gráfico

borderColor (default = '6e7eaa') => Cor da borda do Gráfico

borderRight (default = 25) => Tamanho da borda Direita do Gráfico

borderLeft (default = 15) => Tamanho da borda Esquerda borda do Gráfico

palette (default = 2) => Palleta de Cor do Gráfico (1 à 5)

Date (collectionpy.date)

A coleção Date, tem como objetivo facilitar a manipulação de datas, sejam para realizar cálculos com datas como recuperar informações de datas relativas

dtget (collectionpy.date.dtget)

lastDay(dt:datetime)
Retorna o último dia do mês (em número) | Ex: lastDay(datetime(2024,1,5)) => 31
lastDate(dt:datetime)
Retorna o último dia do mês (em datetime) | Ex: lastDay(datetime(2024,1,5)) => datetime(2024,1,31)

getUtilDay(dt:datetime, util_day:int, disregard:list, last_day:boolean)
Retorna a data de um dia útil desejado (Considera apenas dias de semana como dia útil)

dt (Obrigatório) => Deve ser uma data no formato datetime => irá considerar o mês e o Ano da data informada
util_day (Obrigatório) => Deve seu um número inteiro => Qual o dia útil que quer recuperar

disregard (Opcional) => Deve ser uma lista de números => Será desconsiderados como dia útil os números informados (Ex: 7, irá desconsiderar o dia 7 como dia útil), como a função não reconhece feriados automaticamente, esse parâmetro serve para informar manualmente os dias para desconsiderar

Exemplo:

from collectionpy.date.dtget import getUtilDay
from datetime import datetime

agora = datetime(2024, 1, 5)
decimo_dia_util = getUtilDay(agora, 10, [1])

print(decimo_dia_util)

2024-01-15 00:00:00

Essa função irá percorrer todos os dias e retornar o dia útil dentro do mês, vamos ver o detalhe abaixo:
2024-01-01	Desconsiderado na lista disregard
2024-01-02		1º Dia Útil
2024-01-03		2º Dia Útil
2024-01-04		3º Dia Útil
2024-01-05		4º Dia Útil
2024-01-06	Sábado
2024-01-07	Domingo
2024-01-08		5º Dia Útil
2024-01-09		6º Dia Útil
2024-01-10		7º Dia Útil
2024-01-11		8º Dia Útil
2024-01-12		9º Dia Útil
2024-01-13	Sábado
2024-01-14	Domingo
2024-01-15		10º Dia Útil

dtmath (collectionpy.date.dtmath)

add(dt, year:int, month:int, day:int, hour:int, minute:int, second:int)
Retorna uma data adicionando o tempo de acordo com o informado nos parâmetros
Exemplo:

from collectionpy.date.dtmath import add
from datetime import datetime

atual = datetime(2024, 1, 5)
proximo_dia = add(atual, day=1)
dia_anterior = add(atual, day=-1)
proximo_mes = add(atual, month=1)
mes_anterior = add(atual, month=-1)
proximo_ano = add(atual, year=1)
ano_anterior = add(atual, year=1)

print(atual)
print(proximo_dia)
print(dia_anterior)
print(proximo_mes)
print(mes_anterior)
print(proximo_ano)
print(ano_anterior)

2024-01-05 00:00:00
2024-01-06 00:00:00
2024-01-04 00:00:00
2024-02-05 00:00:00
2023-12-05 00:00:00
2025-01-05 00:00:00
2025-01-05 00:00:00
dateDiff(first_dt:datetime, second_dt:datetime, on='month')
Retorna a diferença entre duas datas de acordo com o parâmetro on
- first_dt (datetime) => Data inicial
- second_dt (datetime) => Data Final
- on (string) ['day', 'month', 'year'] => Tipo de retorno
Exemplo:

from collectionpy.date.dtmath import dateDiff
from datetime import datetime

data_inicial = datetime(2022, 1, 5)
data_final = datetime(2024, 1, 5)
dif_dias = dateDiff(data_inicial, data_final, 'day')
dif_mes = dateDiff(data_inicial, data_final, 'month')
dif_ano = dateDiff(data_inicial, data_final, 'year')

print(dif_dias)
print(dif_mes)
print(dif_ano)

730
24
2

RelativeDate (collectionpy.date)

A classe RelativeDate possui a maioria das funcionalidades do módulo dtget e dtmath, dentro de um objeto RelativeDate, temos um atributo que guarda o datetime

RelativeDate(dt:datetime)

dt(default=None) => Data atribuida no atribuito dt, caso não seja passado uma data, o objeto irá instanciar com a data atual

Propriedades

.datetime => Recupera o objeto Datetime atual
.initial_date => Recupera o objeto Datetime inicial
.second() => Recupera o segundo do objeto datetime atual
.minute() => Recupera o minuto do objeto datetime atual
.hour() => Recupera a hora do objeto datetime atual
.day() => Recupera o dia do objeto datetime atual
.month() => Recupera o mês do objeto datetime atual
.year() => Recupera o ano do objeto datetime atual

Exemplo:

from collectionpy.date import RelativeDate
from datetime import datetime

data = datetime(2024, 1, 5, 7, 55, 33)
rd = RelativeDate()

print(rd.datetime)
print(rd.second())
print(rd.minute())
print(rd.hour())
print(rd.day())
print(rd.month())
print(rd.year())

2024-01-26 10:25:30.340523
30
25
10
26
1
2024

Funcionalidades

.add(year=0, month=0, day=0, hour=0, minute=0, second=0) => Adiciona tempo no objeto Datetime atual
.dateDiff(dt, on='month') => Retorna a diferença de tempo do datetime informada no parâmetro com o objeto datetime atual
.lastDay() => Retorna o último dia do mês do objeto datetime atual (em formato de número)
.lastDate() => Retorna o último dia do mês do objeto datetime atual (em formado datetime
.getUtilDay(util_day, disregard=[]) => Retorna a data de um dia útil desejado (Considera apenas dias de semana como dia útil)

Exemplo:

from collectionpy.date import RelativeDate
from datetime import datetime

data = datetime(2024, 1, 5, 7, 55, 33)
segunda_data = datetime(2025, 9, 2, 7, 55, 33)

rd = RelativeDate()
print(rd.datetime)

rd.add(month=-1)
print(rd.datetime)

print(rd.dateDiff(segunda_data, 'month'))
print(rd.lastDay())
print(rd.lastDate())
print(rd.getUtilDay(7, [1, 2]))

2024-01-26 10:46:00.313805
2023-12-26 10:46:00.313805
21
31
2023-12-31 00:00:00
2023-12-12 00:00:00

Math (collectionpy.math)

A coleção Math, tem como objetivo facilitar alguns cálculos Matemáticos

normalized_mean (collectionpy.math.normalized_mean)

normalized_mean(max, min, mean, median, safety_factor=True)

Esse Cálculo serve para Normalizar a Média de resultados, seguindo os seguintes passos:

Realiza a ponderação da média para cima
Realiza a ponderação da média para baixo
Realiza a média da ponderação
Realiza a média do cálculo anterior com a mediana
Realiza a Média do resultado anterior com a média da Média + a Mediana
- Fator de Segurança = Verdadeiro (Default = True)

Text (collectionpy.text)

A coleção Text, tem como objetivo facilitar a exibição de strings e conversão de variável para string

number_to_money (collectionpy.text.number_to_money)

number_to_money(number, simbol=False, txt_simbol='brl')

Converte um número para Texto no formato de moeda

number(Obrigatório) => Número que será convertido em String
simbol(default=False) => Será exibido o simbolo da Moeda?
txt_simbol(default='brl') => ['brl', 'us']
- 'blr' => R$
- 'us' => $

number_to_percent (collectionpy.text.number_to_percent)

number_to_percent(number, simbol=False)

Converte um número para Texto no formato de porcentagem

number(Obrigatório) => Número que será convertido em String
simbol(default=False) => Será exibido o simbolo da procentagem?