Metadata-Version: 2.4
Name: bravaorm
Version: 0.0.31
Summary: Python ORM for MySQL
Home-page: https://github.com/robertons/bravaorm
Author: Roberto Neves
Author-email: robertonsilva@gmail.com
License: MIT
Keywords: orm,datamodel,database,model,entity,sdk,mysql,mariadb
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mysql-connector-python
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary






# Brava ORM para MySQL/MariaDB

SDK fornece uma série de recursos para aumentar produtividade no desenvolvimento de aplicações com integração a banco de dados relacional MySql/MariaDB.

# Instalação

Instalação utilizando Pip

```bash
pip install bravaorm
```

Git/Clone
```
git clone https://github.com/robertons/bravaorm
cd bravaorm
pip install -r requirements.txt
python setup.py install
```


## Dados de Entrada

| entrada     | default |    tipo     | obrigatório |                  |
|-------------|---------|-------------|-------------|------------------|
| db_user     | None    | string      | sim         | Nome Usuário     |
| db_password | None    | string      | sim         | Senha Usuario    |
| db_host     | None    | string      | sim         | Host             |
| db_port     | None    | string      | sim         | Porta            |
| db_database | None    | string      | sim         | Nome DB          |
| db_ssl      | False   | boolean     | não         | Conexão Segura   |
| db_ssl_ca   | None    | string      | não         | Certificado CA   |
| db_ssl_cert | None    | string      | não         | Certificado      |
| db_ssl_key  | None    | string      | não         | Chave Certificado|
| db_charset  | utf8    | string      | não         | Charset DB       |
| log_level   | error   | string      | não         | Nível log        |

##  Saída

| método       | aplicável 		    |    resultado 					  			
|--------------|--------------------|--------------------------------------------
| first    	   |  Conexão           | objeto de um select     
| all    	   |  Conexão           | lista de objetos de um select|
| fetch   	   |  Conexão           | lista  de um select sem conversão em objeto
| delete(*obj*)| Conexão    		| exclui um objeto
| save()  	   | Conexão    		| salva operações no db
| add(*obj*)   | Objeto, Conexão    | adiciona objeto a uma lista/tabela
| ToJSON()     | Objeto, Conexão    | resultado em formato dict


## Conexão com Banco de dados

```python
import bravaorm

conn = bravaorm.Connection(db_user="root", db_password="pass", db_host="host", db_port=3306, db_database="dbmae", db_charset="utf8mb4")

```

## Gerando Modelo de Entidade

```python

import os
import bravaorm

bravaorm.Make(dir = os.path.dirname(os.path.abspath(__file__)), db_user="user", db_password="pass", db_host="host", db_port=3306, db_database="dbname")

```

> O script acima irá gerar na raiz do projeto as classes objetos baseados no Banco de Dados. As tabelas do banco dedos devem seguir os requisitos de pluralização, conforme exemplo abaixo:

```bash
.
├── ...
├── model                           # Raiz Entidade
│   ├── __init__.py          
│   ├── categoria.py               # Classe Categoria | Tabela categorias
│   ├── cliente.py                 # Classe Cliente  	| Tabela clientes
│   └── compra.py                  # Classe Compra  	| Tabela compras
│   └── produto.py                 # Classe Produto  	| Tabela produtos
└── ...
```

Tomando como exemplo a tabela produtos, a classe gerada estará assim:

```python
# -*- coding: utf-8 -*-
from bravaorm.entity import *

class Produto(Entity):

	def __init__(cls, **kw):
		cls.__metadata__ = {'pk': ['id']}

		cls.id = Int(pk=True, auto_increment=True, not_null=True, precision=10, scale=0)
		cls.id_categoria = Int(fk=True, not_null=True, precision=10, scale=0)
		cls.prod_nome = String(max=155)
		cls.prod_preco = Decimal(not_null=True, precision=19, scale=2)
		cls.prod_data_fabricacao = DateTime(format='%d/%m/%Y')
		cls.prod_data_modificacao = DateTime(format='%d/%m/%Y HH:MM:SS')

		# One-to-One
		cls.categorias = Obj(context=cls, keyname='categorias', name='Categoria', key='id', reference='id_categoria', table='categorias')

		# One-to-many
		cls.compras = ObjList(context=cls, keyname='compras',name='Compra', key='id_compra', reference='id', table='compras')

		super().__init__(**kw)
```


# Seleção de Objetos e Condições

```python
produto = conn.produtos.where("id=10").first
print(produto)
print(produto.toJSON())
```

**> <model.produto.Produto object at 0x101237c10>**

**> {'id': 10, 'id_categoria': 10, 'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22)}**

# Condição 'Ou'

A condição orwhere é dependente de condição where, e cria novos blocos a cada utilização.

```python
produtos = conn.produtos.where("id=10").orwhere("id=12").orwhere("id=14").all
print(produtos.toJSON())
```
**> [{'id': 10, 'id_categoria': 10,  'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22)}, {'id': 12, 'prod_nome': 'Outro Exemplo ', 'prod_preco':  Decimal('88,20'), 'prod_data_fabricacao': datetime(2011, 10, 8, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 02, 12, 10, 24, 20)}, {'id': 14, 'prod_nome': 'Novo Exemplo', 'prod_preco':  Decimal('129,90'), 'prod_data_fabricacao': datetime(2009, 11, 7, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 01, 10, 14, 34, 15)}]**

# Seleção de Campos
```python
produto = conn.produtos.where("id=10").select("id, prod_nome").first
print(produto.toJSON())
```
**> {'id': 10, 'prod_nome': 'Exemplo'}**

# Alias de Funções ou Campos
```python
produto = conn.produtos.alias('prod_nome','nome').where("id=10").first
print(produto['nome'])
print(produto.prod_nome)
```
**> Exemplo**
**> Exemplo**

*Alias são campos não editáveis*

# Ordenamento


```python
# ORDERBY
produto = conn.produtos.orderby("prod_nome").all
produto = conn.produtos.orderby("prod_nome DESC").all

```
# Agrupamento

```python
# GROUPBY
produto = conn.produtos.groupby("id_categoria").all
```

# Limite

```python
# LIMIT
produto = conn.produtos.orderby("prod_nome").limit(0,10).all

```

# União de Objetos

O métodos "join" e "inner" são recomendados para uso de objetos com relacionamento "um para um",  ou em casos onde o resultado da tabela secundária irá retornar apenas **um resultado.** A utilização desses métodos em casos de seleção "um para vários" o resultado será baseado na tabela secundária, podendo ocorrer a repetição do objeto principal. Neste neste caso é recomendável a utilização do método "include" onde o resultado da lista será com objetos únicos incluindo os vários resultados da tabela secundária.

**Exemplos:**

## Join

O método join, é equivalente ao "LEFT JOIN" e retorna o objeto principal incluindo a seleção secundária, de duas tabelas.

```python
produto = conn.produtos.join("categegorias").all

```

**> {'id': 10, 'id_categoria': 10, 'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22), 'categorias': {'id':1, 'cat_nome':'Categoria Teste'}}**


## Inner

O método inner, é equivalente ao "INNER JOIN" e retorna o objeto principal baseado na interceção da tabela secundária.

```python
produto = conn.produtos.inner("categorias").where("categorias.id=1").all

```

**> [{'id': 10, 'id_categoria': 10, 'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22), 'categorias': {'id':1, 'cat_nome':'Categoria Teste'}}, {'id': 12, 'prod_nome': 'Outro Exemplo ', 'prod_preco':  Decimal('88,20'), 'prod_data_fabricacao': datetime(2011, 10, 8, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 02, 12, 10, 24, 20), 'categorias': {'id':1, 'cat_nome':'Categoria Teste'}}, {'id': 14, 'prod_nome': 'Novo Exemplo', 'prod_preco':  Decimal('129,90'), 'prod_data_fabricacao': datetime(2009, 11, 7, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 01, 10, 14, 34, 15), 'categorias': {'id':1, 'cat_nome':'Categoria Teste'}}]**

## Include

O método include, faz seleção de um ou vários objetos relacionados ao objeto principal, recomendado para relacionamento um para vários.

*este método requer atenção em relação a performance para grandes seleções*

```python
produto = conn.produtos.include("compras").where("id=10, compras.compra_paga=1").all

```

**> [{'id': 10, 'id_categoria': 10, 'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22), 'compras': [{'id':1, 'compra_data':datetime(2010, 12, 10, 0, 0, 0), 'id_cliente':12}, {'id':23, 'compra_data':datetime(2017, 11, 13, 0, 0, 0), 'id_cliente':54}, {'id':34, 'compra_data':datetime(2018, 1 11, 0, 0, 0), 'id_cliente':20}, {'id':110, 'compra_data':datetime(2019, 7, 22, 0, 0, 0), 'id_cliente':16}]}]**

## ON

O método on, é possibilidade de escritas de join personalizados com tabelas sem relacionamentos. É possível escrever qualquer condição,  "RIGHT, INNER, LEFT JOIN" e retorna o objeto principal com os campos em alias de acordo com a tabela incluída.

O método possui 4 parametros de entrada, select ( campos da tabela selecionada), metodo join (left, right, inner), tabela e condição

No exemplo abaixo, selecionamos produtos com cupons de desconto, onde o preço do produto atinge o limite do preço do cumpom

```python
produto = conn.produtos.on("cupons.cod_cupom, cupons.cup_preco_max", "left", "cupons" , "cupons.cup_preco_max >= produtos.prod_preco").where("NOT cupons.id IS NULL").all

```

**> {'id': 10, 'id_categoria': 10, 'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22), 'cod_cupom': 'ACAFS' ,'cup_preco_max': Decimal(19,00)}**


#  Fetch

O método fetch  permite o obter a resposta direta do DB em formato dict a partir de um select, sem a conversão dos dados em classe/objeto. Este método oferece ganho significativo de performance.

```python
# GROUPBY
produtos = conn.produtos.fetch

```

**> [{'id': 10, 'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22)}, {'id': 12, 'prod_nome': 'Outro Exemplo ', 'prod_preco':  Decimal('88,20'), 'prod_data_fabricacao': datetime(2011, 10, 8, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 02, 12, 10, 24, 20)}, {'id': 14, 'prod_nome': 'Novo Exemplo', 'prod_preco':  Decimal('129,90'), 'prod_data_fabricacao': datetime(2009, 11, 7, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 01, 10, 14, 34, 15)}]**

## Método toJSON()

O metodo toJSON() retorna o objeto ou lista de resultado em formato dict.

```python
	print(produto)
	print(produto.toJSON())
```
**> <model.produto.Produto object at 0x107737c10>**

**> {'id': 10, 'prod_nome': 'Exemplo', 'prod_preco':  Decimal('99.90'), 'prod_data_fabricacao': datetime(2010, 12, 10, 0, 0, 0), 'prod_data_modificacao': 'datetime(2021, 03, 31, 16, 54, 22)}**


# Criação de Objetos
## Simples
```python
from model import *

produto = Produto()
produto.prod_nome = 'Exemplo'
produto.prod_preco = Decimal('99.90')
produto.prod_data_fabricacao = datetime(2010, 12, 10, 0, 0, 0)
produto.prod_data_modificacao = '31/03/2021 16:54:22' # Conversão para datetime seguindo formato '%d/%m/%Y HH:MM:SS'

conn.add(produto)
conn.save()

```

**OU**

```python
from model import *

produto = Produto(prod_nome='Exemplo', prod_preco=Decimal('99.90'), prod_data_fabricacao = datetime(2010, 12, 10, 0, 0, 0), prod_data_modificacao = '31/03/2021 16:54:22')

conn.add(produto)
conn.save()
```

**OU**

```python
from model import *

produto = Produto(**{prod_nome:'Exemplo', prod_preco:Decimal('99.90'), prod_data_fabricacao:datetime(2010, 12, 10, 0, 0, 0), prod_data_modificacao :'31/03/2021 16:54:22'})

conn.add(produto)
conn.save()
```

## Com Relacionamentos

No exemplo abaixo, criamos um produto na tabela *produtos* com 3 fotos na tabela *produtos_fotos*

```python
from model import *

produto = Produto()
produto.prod_nome = 'Exemplo'
produto.prod_preco = Decimal('99.90')
produto.prod_data_fabricacao = datetime(2010, 12, 10, 0, 0, 0)
produto.prod_data_modificacao = '31/03/2021 16:54:22' # Conversão para datetime seguindo formato '%d/%m/%Y HH:MM:SS'

foto = ProdutoFoto()
foto.foto_descricao = 'Vista Frontal'
foto.foto_arquivo =  'fronta.jpg'
produto.produtos_fotos.add(foto)

foto = ProdutoFoto(**{foto_descricao:'Vista Lateral', foto_arquivo:'lateral.jpg'})
produto.produtos_fotos.add(foto)

produto.produtos_fotos.add(ProdutoFoto(foto_descricao='Vista Lateral', foto_arquivo='lateral.jpg'))

conn.add(produto)
conn.save()

```

# Atualizando Objeto

```python
produto = conn.produtos.where("id=10").first
produto.prod_preco = Decimal(89.90)
conn.add(produto).save()
```
**ou vários**

```python
produtos = db.produtos.where("prod_preco>=100").all
for produto in produtos:
	produto.prod_preco = produto.prod_preco * 0.9
	conn.add(produto)
db.save()
```

**ou relativos**

```python
categoria = db.categorias.include("produtos").where("id=1, produtos.pro_preco>=100").all
for produto in categoria.produtos:
	produto.prod_preco = produto.prod_preco * 0.9
	conn.add(produto)
db.save()
```

# Exclusão de Objetos

O método requer um objeto de entrada, ou uma condição where definida:

```python
conn.delete(produto).save()
```
ou condicional

```python
conn.produtos.where("prod_preco=100").delete()
```

# Contador

```python
quantidade_produtos = conn.produtos.where("prod_preco=100").count

print(quantidade_produtos)
```

**> 113 **

# Update Query

Realizar Atualização de registros com condição.


Atualizando um campo
```python
conn.produtos.where("prod_active=0").set("prod_active", 1)
```

Atualizando um ou mais campos

```python
conn.produtos.where("prod_active=0").update(**{"prod_active": 1, "prod_promo": 1})
```

OU

```python
conn.produtos.where("prod_active=0").update(prod_active=1, prod_promo=0)
```

# Execute Query

É possível executar queries mais complexas e com condicionais específicas, nesse caso é possível escrever a query diretamente na conexão e informar qual o tipo de objeto será retornado a partir dela.

A definição do objeto é opcional.



```python
produtos = conn.execute("SELECT * FROM produtos WHERE preco > 100", "Produto")
```

A consulta acima irá retornar uma lista de  objetos *Produto*


```python
produtos = conn.execute("SELECT * FROM produtos WHERE preco > 100")
```

A consulta acima irá retornar uma lista com dictionary  com dados de produtos

# Descrição completa do Projeto e arquitetura

## 🧬 Visão Geral do Projeto

O BravaORM é um SDK (Object-Relational Mapper) desenvolvido em Python projetado especificamente para MySQL e MariaDB, focado em aumentar a produtividade. Ele possui uma abordagem intuitiva e amigável para Query Building (similar aos ORMs mais modernos), com suporte embutido a relacionamentos complexos e foco em performance e praticidade.

A filosofia do ORM, centrada principalmente em "Gerar o Código do Modelo a partir do Banco de Dados", lembra abordagens consolidadas e altamente produtivas na web hoje.

## 📂 Dependência Princial
mysql-connector-python

## 📂 Estrutura da Arquitetura (Core)
A biblioteca está debaixo do diretório principal bravaorm/. Esse diretório é inteligentemente dividido em três domínios principais:

### 1. Módulo context (O Motor do Banco de Dados)

Responsável por estabelecer e gerenciar a comunicação com o MySql/MariaDB.

connection.py: A espinha dorsal das conexões (bravaorm.Connection), capaz de traduzir a sintaxe fluida do Python para as queries em SQL, aplicando where, orderby, groupby, limites e gerindo as transações com save() ou execuções diretas com execute().

database.py: Abstrações gerais e handlers de queries sobre as instâncias do DB.

### 2. Módulo entity (Abstração dos Dados)
Gerencia as classes que abstraem as tabelas.

entity.py: Contém a classe base Entity da qual todos os modelos gerados herdam. É o que permite gerir o ciclo de vida do objeto e sua serialização rápida (toJSON()).

datatype.py : Define a tipagem rigorosa que espelha os tipos do banco de dados relacional para o Python. Estão lá as definições de Int, String, Decimal, DateTime, além dos objetos relacionais Obj (One-to-One) e ObjList (One-to-Many).

### 3. Módulo utils (Ferramentas de Produtividade)
Aqui moram as "mágicas" do seu orquestrador.

make.py (bravaorm.Make): Um recurso incrível de introspecção do DB. Ele varre as tabelas, analisa as FKs/PKs e escreve sozinho as classes de modelo em código Python na raiz do projeto.

inflector/: Essencial para o ORM. Lida com a pluralização natural das tabelas (ex: entende que a tabela produtos se refere ao objeto Produto).
log/: Estrutura padronizada para manter registros de debug e de erros baseada no DB.

angular.py: Um recurso de introspecção do DB. Ele varre as tabelas, analisa as FKs/PKs e escreve sozinho as classes de modelo em código TypeScript no diretório desejado.

## 💡 Destaques da API (O que torna o BravaORM forte)
Sintaxe Fluente (Query Builder): A interface para buscar dados é muito polida.
Ex: conn.produtos.where("id=10").alias('prod_nome','nome').first

### Relacionamentos Bem Resolvidos:
join(...) e inner(...) resolvem bem e de forma previsível buscas One-to-One / Many-to-One.
include(...) lida com o complexo problema N+1 ao fazer Eager Loading para One-to-Many (ex: busque as compras do produto X). O on(..) para junções customizadas para tabelas sem relacionamento fixo (ideal para relatórios).

### Conversão Imediata (Data to Dictionary) 
O método .toJSON() direto no objeto, ou o uso imediato de .fetch ignorando classes, é excelente para APIs REST onde o desenvolvedor só precisa transferir o dado em JSON pela reposta HTTP sem overhead de parser.


## License

MIT

Copyright (c) 2019-2021 Roberto Neves. All rights reserved. info (at) robertonsilva@gmail.com
