# CaspyORM - Documentação Completa
## Índice
1. [Visão Geral](#visão-geral)
2. [Instalação](#instalação)
3. [Configuração](#configuração)
4. [Conceitos Básicos](#conceitos-básicos)
5. [Modelos e Campos](#modelos-e-campos)
6. [Operações CRUD](#operações-crud)
7. [Queries e Filtros](#queries-e-filtros)
8. [Tipos de Dados](#tipos-de-dados)
9. [User-Defined Types (UDT)](#user-defined-types-udt)
10. [Operações em Lote](#operações-em-lote)
11. [Migrações](#migrações)
12. [CLI (Interface de Linha de Comando)](#cli-interface-de-linha-de-comando)
13. [Integração com FastAPI](#integração-com-fastapi)
14. [Performance e Otimização](#performance-e-otimização)
15. [Tratamento de Erros](#tratamento-de-erros)
16. [Exemplos Práticos](#exemplos-práticos)
17. [Referência da API](#referência-da-api)
---
## Visão Geral
CaspyORM é um ORM (Object-Relational Mapping) moderno e eficiente para Apache Cassandra, construído com Python e Pydantic. Ele oferece uma interface intuitiva e type-safe para trabalhar com o Cassandra, combinando a simplicidade do Pydantic com a potência do Cassandra.
### Características Principais
- **Type Safety**: Validação automática de tipos usando Pydantic
- **Interface Intuitiva**: API similar ao Django ORM e SQLAlchemy
- **Suporte Completo ao Cassandra**: Todos os tipos de dados nativos
- **User-Defined Types**: Suporte completo a UDTs
- **Operações em Lote**: Otimizações para grandes volumes de dados
- **Migrações**: Sistema de migrações automático
- **CLI**: Interface de linha de comando para operações comuns
- **Integração FastAPI**: Suporte nativo para FastAPI
- **Performance**: Otimizado para alta performance
---
## Instalação
### Instalação Básica
```bash
pip install caspyorm
```
### Instalação com Dependências Opcionais
```bash
# Com suporte a FastAPI
pip install caspyorm[fastapi]
# Com suporte a operações assíncronas otimizadas
pip install caspyorm[async]
# Com todas as dependências opcionais
pip install caspyorm[fastapi,async]
```
### Instalação para Desenvolvimento
```bash
git clone https://github.com/caspyorm/caspyorm.git
cd caspyorm
pip install -e .
```
---
## Configuração
### Configuração Básica
```python
from caspyorm import connect
# Conectar ao Cassandra
connect(
contact_points=['localhost'],
keyspace='my_keyspace',
port=9042
)
```
### Configuração Avançada
```python
from caspyorm import connect
connect(
contact_points=['cassandra1.example.com', 'cassandra2.example.com'],
keyspace='production_keyspace',
port=9042,
username='myuser',
password='mypassword',
ssl_options={
'ca_certs': '/path/to/ca.crt',
'check_hostname': True
},
protocol_version=4,
connect_timeout=10,
request_timeout=30
)
```
### Configuração via Arquivo
Crie um arquivo `caspy.toml` na raiz do projeto:
```toml
[cassandra]
hosts = ["localhost"]
keyspace = "my_keyspace"
port = 9042
username = "myuser"
password = "mypassword"
ssl = false
protocol_version = 4
connect_timeout = 10
request_timeout = 30
```
### Configuração via Variáveis de Ambiente
```bash
export CASPY_HOSTS="localhost"
export CASPY_KEYSPACE="my_keyspace"
export CASPY_PORT="9042"
export CASPY_USERNAME="myuser"
export CASPY_PASSWORD="mypassword"
```
---
## Conceitos Básicos
### Estrutura de um Modelo
```python
from caspyorm import Model
from caspyorm.core.fields import Text, Integer, Boolean, Timestamp
class User(Model):
__table_name__ = "users"
id = Integer(primary_key=True)
username = Text(required=True)
email = Text(required=True)
is_active = Boolean(default=True)
created_at = Timestamp()
```
### Principais Componentes
1. **Model**: Classe base para todos os modelos
2. **Fields**: Definição dos tipos de dados
3. **Connection**: Gerenciamento de conexões
4. **Query**: Construção de consultas
5. **Batch**: Operações em lote
---
## Modelos e Campos
### Definição de Modelos
```python
from caspyorm import Model
from caspyorm.core.fields import (
Text, Integer, Boolean, Timestamp,
UUID, Float, List, Set, Map, Tuple
)
class Product(Model):
__table_name__ = "products"
# Chaves primárias
id = UUID(primary_key=True) # Gera UUID automaticamente
category_id = Integer(partition_key=True)
# Campos básicos
name = Text(required=True)
description = Text()
price = Float(required=True)
is_active = Boolean(default=True)
# Campos de data
created_at = Timestamp()
updated_at = Timestamp()
# Campos de coleção
tags = Set(Text(), default=set)
attributes = Map(Text(), Text(), default=dict)
dimensions = Tuple(Integer(), Integer(), Integer())
images = List(Text(), default=list)
```
### Tipos de Chaves
```python
class Order(Model):
__table_name__ = "orders"
# Chave de partição (obrigatória)
user_id = Integer(partition_key=True)
# Chaves de clustering (opcionais)
order_date = Timestamp(clustering_key=True)
order_id = UUID(clustering_key=True)
# Campos normais
status = Text(required=True)
total = Float(required=True)
```
### Campos com Índices
```python
class User(Model):
__table_name__ = "users"
id = Integer(primary_key=True)
email = Text(required=True, index=True) # Índice secundário
username = Text(required=True, index=True)
```
---
## Operações CRUD
### Create (Criar)
```python
# Criar um objeto
user = User(
username="john_doe",
email="john@example.com",
is_active=True
)
# Salvar no banco
user.save()
# Criar com dados específicos
user = User.create(
username="jane_doe",
email="jane@example.com"
)
```
### Read (Ler)
```python
# Buscar por chave primária
user = User.get(id=1)
# Buscar todos os registros
all_users = User.all().all()
# Buscar com limite
users = User.all().limit(10).all()
# Buscar com filtros
active_users = User.all().filter(is_active=True).all()
```
### Update (Atualizar)
```python
# Atualizar um objeto
user = User.get(id=1)
user.email = "new_email@example.com"
user.save()
# Atualizar múltiplos campos
user.update(
email="new_email@example.com",
is_active=False
)
```
### Delete (Deletar)
```python
# Deletar um objeto
user = User.get(id=1)
user.delete()
# Deletar por chave primária
User.delete(id=1)
```
---
## Queries e Filtros
### Queries Básicas
```python
# Buscar todos
users = User.all().all()
# Buscar com limite
users = User.all().limit(10).all()
# Buscar com ordenação
users = User.all().order_by('created_at', 'DESC').all()
# Buscar com filtros
users = User.all().filter(
is_active=True,
created_at__gte=datetime(2023, 1, 1)
).all()
```
### Filtros Avançados
```python
# Filtros de comparação
users = User.all().filter(
age__gte=18,
age__lte=65,
email__contains="@gmail.com"
).all()
# Filtros em coleções
products = Product.all().filter(
tags__contains="electronics",
attributes__contains_key="color"
).all()
# Filtros com operadores lógicos
users = User.all().filter(
(User.is_active == True) & (User.age >= 18)
).all()
```
### Queries Personalizadas
```python
from caspyorm.core.connection import execute
# Query SQL direta
result = execute("SELECT COUNT(*) FROM users WHERE is_active = true")
count = result[0].count
# Query com parâmetros
result = execute(
"SELECT * FROM users WHERE age >= %s AND city = %s",
[18, "New York"]
)
```
---
## Tipos de Dados
### Tipos Básicos
```python
from caspyorm.core.fields import (
Text, Integer, Float, Boolean, Timestamp, UUID
)
class BasicTypes(Model):
__table_name__ = "basic_types"
id = Integer(primary_key=True)
name = Text(required=True)
age = Integer()
height = Float()
is_active = Boolean(default=True)
created_at = Timestamp()
user_id = UUID()
```
### Tipos de Coleção
```python
from caspyorm.core.fields import List, Set, Map, Tuple
class CollectionTypes(Model):
__table_name__ = "collection_types"
id = Integer(primary_key=True)
# Lista
tags = List(Text(), default=list)
# Conjunto
categories = Set(Text(), default=set)
# Mapa
metadata = Map(Text(), Text(), default=dict)
# Tupla
coordinates = Tuple(Integer(), Integer())
```
### Uso de Coleções
```python
# Criar com coleções
product = Product(
id=1,
name="Laptop",
tags=["electronics", "computer"],
categories={"tech", "hardware"},
metadata={"brand": "Dell", "model": "XPS"},
dimensions=(15, 10, 1)
)
# Modificar coleções
product.tags.append("gaming")
product.categories.add("gaming")
product.metadata["price"] = "999.99"
product.save()
```
---
## User-Defined Types (UDT)
### Definindo UDTs
```python
from caspyorm.types.usertype import UserType
from caspyorm.core.fields import Text, Integer
class Address(UserType):
street = Text()
city = Text()
state = Text()
zip_code = Text()
country = Text()
class Contact(UserType):
phone = Text()
email = Text()
website = Text()
```
### Usando UDTs em Modelos
```python
from caspyorm.core.fields import UserDefinedType
class Customer(Model):
__table_name__ = "customers"
id = Integer(primary_key=True)
name = Text(required=True)
address = UserDefinedType(Address)
contact = UserDefinedType(Contact)
```
### Operações com UDTs
```python
# Criar UDT
address = Address(
street="123 Main St",
city="New York",
state="NY",
zip_code="10001",
country="USA"
)
contact = Contact(
phone="+1-555-1234",
email="john@example.com",
website="https://example.com"
)
# Usar em modelo
customer = Customer(
id=1,
name="John Doe",
address=address,
contact=contact
)
customer.save()
# Acessar campos do UDT
print(customer.address.street) # "123 Main St"
print(customer.contact.email) # "john@example.com"
# Modificar UDT
customer.address.city = "Los Angeles"
customer.save()
```
---
## Operações em Lote
### Inserção em Lote
```python
from caspyorm.types.batch import BatchQuery
# Inserir múltiplos registros
users = [
User(username="user1", email="user1@example.com"),
User(username="user2", email="user2@example.com"),
User(username="user3", email="user3@example.com")
]
with BatchQuery():
for user in users:
user.save()
```
### Atualização em Lote
```python
# Atualizar múltiplos registros
users = User.all().filter(is_active=False).all()
with BatchQuery():
for user in users:
user.is_active = True
user.save()
```
### Deleção em Lote
```python
# Deletar múltiplos registros
users = User.all().filter(created_at__lt=datetime(2020, 1, 1)).all()
with BatchQuery():
for user in users:
user.delete()
```
### Performance de Lote
```python
import time
# Teste de performance
N = 1000
batch_size = 100
t0 = time.time()
for start in range(0, N, batch_size):
end = min(start + batch_size, N)
with BatchQuery():
for i in range(start, end):
User(username=f"user{i}", email=f"user{i}@example.com").save()
t1 = time.time()
print(f"Tempo para inserir {N} registros: {t1-t0:.2f}s")
```
---
## Migrações
### Inicialização
```bash
# Inicializar sistema de migrações
caspyorm migrate init --keyspace my_keyspace
```
### Criar Nova Migração
```bash
# Criar nova migração
caspyorm migrate new create_users_table
```
### Estrutura de Migração
```python
# migrations/V001_create_users_table.py
from caspyorm.core.connection import get_session
from caspyorm.utils.schema import create_table
from models import User
def upgrade():
"""Executa a migração para cima."""
session = get_session()
create_table(session, User)
def downgrade():
"""Reverte a migração."""
session = get_session()
session.execute("DROP TABLE IF EXISTS users")
```
### Aplicar Migrações
```bash
# Aplicar todas as migrações pendentes
caspyorm migrate apply --keyspace my_keyspace
# Verificar status das migrações
caspyorm migrate status --keyspace my_keyspace
# Reverter última migração
caspyorm migrate downgrade --keyspace my_keyspace --force
```
### Migrações Complexas
```python
def upgrade():
session = get_session()
# Criar nova tabela
session.execute("""
CREATE TABLE IF NOT EXISTS user_profiles (
user_id int PRIMARY KEY,
bio text,
avatar_url text,
preferences map<text, text>
)
""")
# Adicionar coluna a tabela existente
session.execute("""
ALTER TABLE users ADD phone text
""")
# Criar índice
session.execute("""
CREATE INDEX IF NOT EXISTS idx_users_email ON users (email)
""")
def downgrade():
session = get_session()
# Remover índice
session.execute("DROP INDEX IF EXISTS idx_users_email")
# Remover coluna
session.execute("ALTER TABLE users DROP phone")
# Remover tabela
session.execute("DROP TABLE IF EXISTS user_profiles")
```
---
## CLI (Interface de Linha de Comando)
### Comandos Básicos
```bash
# Informações da conexão
caspyorm info
# Listar modelos disponíveis
caspyorm models
# Conectar ao Cassandra
caspyorm connect --keyspace my_keyspace
# Executar query SQL
caspyorm sql "SELECT COUNT(*) FROM users"
# Query em modelo
caspyorm query users count
caspyorm query users filter --filter "is_active=true" --limit 10
```
### Comandos de Migração
```bash
# Inicializar migrações
caspyorm migrate init --keyspace my_keyspace
# Criar nova migração
caspyorm migrate new create_table_name
# Aplicar migrações
caspyorm migrate apply --keyspace my_keyspace
# Status das migrações
caspyorm migrate status --keyspace my_keyspace
# Reverter migração
caspyorm migrate downgrade --keyspace my_keyspace --force
```
### Configuração da CLI
```bash
# Via variáveis de ambiente
export CASPY_HOSTS="localhost"
export CASPY_KEYSPACE="my_keyspace"
export CASPY_PORT="9042"
# Via arquivo caspy.toml
caspyorm --config caspy.toml info
```
---
## Integração com FastAPI
### Configuração Básica
```python
from fastapi import FastAPI
from caspyorm.contrib.fastapi import CaspyORM
app = FastAPI()
# Configurar CaspyORM
caspyorm = CaspyORM(
contact_points=['localhost'],
keyspace='my_keyspace',
port=9042
)
# Incluir no app
app.include_router(caspyorm.router)
```
### Modelos FastAPI
```python
from pydantic import BaseModel
from typing import Optional, List
class UserCreate(BaseModel):
username: str
email: str
is_active: bool = True
class UserResponse(BaseModel):
id: int
username: str
email: str
is_active: bool
created_at: Optional[datetime]
# Endpoints automáticos
@caspyorm.crud(User, UserCreate, UserResponse)
class UserCRUD:
pass
```
### Endpoints Customizados
```python
from fastapi import APIRouter, HTTPException
router = APIRouter()
@router.get("/users/{user_id}")
async def get_user(user_id: int):
user = User.get(id=user_id)
if not user:
raise HTTPException(status_code=404, detail="User not found")
return user
@router.post("/users")
async def create_user(user_data: UserCreate):
user = User(**user_data.dict())
user.save()
return user
@router.put("/users/{user_id}")
async def update_user(user_id: int, user_data: UserCreate):
user = User.get(id=user_id)
if not user:
raise HTTPException(status_code=404, detail="User not found")
user.update(**user_data.dict())
return user
@router.delete("/users/{user_id}")
async def delete_user(user_id: int):
user = User.get(id=user_id)
if not user:
raise HTTPException(status_code=404, detail="User not found")
user.delete()
return {"message": "User deleted"}
```
---
## Performance e Otimização
### Estratégias de Otimização
1. **Uso de Índices**
```python
class User(Model):
__table_name__ = "users"
id = Integer(primary_key=True)
email = Text(required=True, index=True) # Índice para busca por email
username = Text(required=True, index=True)
```
2. **Operações em Lote**
```python
# Inserir em lotes para melhor performance
with BatchQuery():
for user in users:
user.save()
```
3. **Limitação de Resultados**
```python
# Usar LIMIT para evitar carregar muitos dados
users = User.all().limit(100).all()
```
4. **Filtros Eficientes**
```python
# Usar chaves de partição e clustering
orders = Order.all().filter(
user_id=123,
order_date__gte=datetime(2023, 1, 1)
).all()
```
### Monitoramento de Performance
```python
import time
from caspyorm.core.connection import get_session
# Medir tempo de query
t0 = time.time()
users = User.all().all()
t1 = time.time()
print(f"Query executada em {t1-t0:.2f}s")
# Verificar estatísticas da sessão
session = get_session()
print(f"Queries executadas: {session.query_count}")
print(f"Tempo total: {session.total_time:.2f}s")
```
---
## Tratamento de Erros
### Exceções Comuns
```python
from caspyorm.utils.exceptions import (
ValidationError, ConnectionError, QueryError
)
try:
user = User(username="john", email="invalid-email")
user.save()
except ValidationError as e:
print(f"Erro de validação: {e}")
except ConnectionError as e:
print(f"Erro de conexão: {e}")
except QueryError as e:
print(f"Erro de query: {e}")
```
### Validação de Dados
```python
from caspyorm.utils.exceptions import ValidationError
# Validação automática
try:
user = User(
id="not_an_integer", # Erro: deve ser int
email="invalid-email" # Erro: formato inválido
)
except ValidationError as e:
print(f"Erros de validação: {e.errors}")
```
### Tratamento de Conexão
```python
from caspyorm import connect, disconnect
from caspyorm.utils.exceptions import ConnectionError
try:
connect(contact_points=['localhost'], keyspace='my_keyspace')
# Operações com o banco
except ConnectionError as e:
print(f"Falha na conexão: {e}")
finally:
disconnect()
```
---
## Exemplos Práticos
### Sistema de Blog
```python
from caspyorm import Model
from caspyorm.core.fields import (
Integer, Text, Timestamp, Set, Map, UserDefinedType, Boolean
)
from caspyorm.types.usertype import UserType
class Author(UserType):
name = Text()
email = Text()
bio = Text()
class Post(Model):
__table_name__ = "posts"
id = Integer(primary_key=True)
title = Text(required=True)
content = Text(required=True)
author = UserDefinedType(Author)
tags = Set(Text(), default=set)
metadata = Map(Text(), Text(), default=dict)
created_at = Timestamp()
updated_at = Timestamp()
is_published = Boolean(default=False)
# Criar post
author = Author(name="John Doe", email="john@example.com", bio="Tech writer")
post = Post(
title="Getting Started with CaspyORM",
content="CaspyORM is a modern ORM for Cassandra...",
author=author,
tags={"cassandra", "python", "orm"},
metadata={"category": "tutorial", "difficulty": "beginner"}
)
post.save()
# Buscar posts
published_posts = Post.all().filter(is_published=True).all()
tech_posts = Post.all().filter(tags__contains="python").all()
```
### Sistema de E-commerce
```python
class Product(Model):
__table_name__ = "products"
id = Integer(primary_key=True)
name = Text(required=True)
description = Text()
price = Float(required=True)
category_id = Integer(partition_key=True)
tags = Set(Text(), default=set)
attributes = Map(Text(), Text(), default=dict)
stock = Integer(default=0)
is_active = Boolean(default=True)
created_at = Timestamp()
class Order(Model):
__table_name__ = "orders"
user_id = Integer(partition_key=True)
order_date = Timestamp(clustering_key=True)
order_id = UUID(clustering_key=True)
status = Text(required=True)
total = Float(required=True)
items = List(Text(), default=list) # Lista de IDs de produtos
shipping_address = UserDefinedType(Address)
created_at = Timestamp()
# Buscar produtos por categoria
electronics = Product.all().filter(category_id=1, is_active=True).all()
# Buscar pedidos de um usuário
user_orders = Order.all().filter(user_id=123).order_by('order_date', 'DESC').all()
# Buscar pedidos por status
pending_orders = Order.all().filter(status="pending").all()
```
---
## Referência da API
### Model
```python
class Model:
# Métodos de classe
@classmethod
def all(cls) -> Query
@classmethod
def get(cls, **kwargs) -> Optional[Model]
@classmethod
def create(cls, **kwargs) -> Model
@classmethod
def delete(cls, **kwargs) -> bool
# Métodos de instância
def save(self) -> None
def update(self, **kwargs) -> None
def delete(self) -> None
def model_dump(self) -> dict
def model_dump_json(self) -> str
```
### Query
```python
class Query:
def filter(self, **kwargs) -> Query
def order_by(self, field: str, direction: str = "ASC") -> Query
def limit(self, limit: int) -> Query
def allow_filtering(self) -> Query
def all(self) -> List[Model]
def first(self) -> Optional[Model]
def count(self) -> int
```
### Fields
```python
# Tipos básicos
Text(primary_key=False, required=False, default=None, index=False)
Integer(primary_key=False, required=False, default=None, index=False)
Float(primary_key=False, required=False, default=None, index=False)
Boolean(primary_key=False, required=False, default=None, index=False)
Timestamp(primary_key=False, required=False, default=None, index=False)
UUID(primary_key=False, required=False, default=None, index=False)
# Tipos de coleção
List(inner_field: BaseField, **kwargs)
Set(inner_field: BaseField, **kwargs)
Map(key_field: BaseField, value_field: BaseField, **kwargs)
Tuple(*field_types: BaseField, **kwargs)
# User-Defined Types
UserDefinedType(udt_class: Type, **kwargs)
```
### Connection
```python
def connect(
contact_points: List[str],
keyspace: str,
port: int = 9042,
username: Optional[str] = None,
password: Optional[str] = None,
ssl_options: Optional[dict] = None,
protocol_version: int = 4,
connect_timeout: int = 10,
request_timeout: int = 30
) -> None
def disconnect() -> None
def get_session() -> Session
def execute(query: str, params: Optional[List] = None) -> ResultSet
```
### Batch
```python
class BatchQuery:
def __enter__(self) -> BatchQuery
def __exit__(self, exc_type, exc_val, exc_tb) -> None
```
### Exceptions
```python
class ValidationError(Exception)
class ConnectionError(Exception)
class QueryError(Exception)
class SchemaError(Exception)
```
---
## Conclusão
CaspyORM oferece uma solução completa e moderna para trabalhar com Apache Cassandra em Python. Com sua interface intuitiva, validação automática de tipos, suporte completo aos recursos do Cassandra e ferramentas de desenvolvimento, é a escolha ideal para projetos que precisam de performance e escalabilidade.
Para mais informações, exemplos e atualizações, visite:
- [Documentação Oficial](https://caspyorm.dev)
- [GitHub Repository](https://github.com/caspyorm/caspyorm)
- [PyPI Package](https://pypi.org/project/caspyorm/)
## Licença
Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
## Contribuindo
Contribuições são bem-vindas! Por favor, leia o [guia de contribuição](CONTRIBUTING.md) antes de submeter um pull request.
Raw data
{
"_id": null,
"home_page": null,
"name": "caspyorm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cassandra, database, fastapi, nosql, orm, pydantic",
"author": null,
"author_email": "CaspyORM Team <team@caspyorm.dev>",
"download_url": "https://files.pythonhosted.org/packages/11/e9/70bb4b1a42bfad15e787ab57c0c1ab05c2a409fa0597b39fdbdad4111c44/caspyorm-0.1.7.tar.gz",
"platform": null,
"description": "# CaspyORM - Documenta\u00e7\u00e3o Completa\n\n## \u00cdndice\n\n1. [Vis\u00e3o Geral](#vis\u00e3o-geral)\n2. [Instala\u00e7\u00e3o](#instala\u00e7\u00e3o)\n3. [Configura\u00e7\u00e3o](#configura\u00e7\u00e3o)\n4. [Conceitos B\u00e1sicos](#conceitos-b\u00e1sicos)\n5. [Modelos e Campos](#modelos-e-campos)\n6. [Opera\u00e7\u00f5es CRUD](#opera\u00e7\u00f5es-crud)\n7. [Queries e Filtros](#queries-e-filtros)\n8. [Tipos de Dados](#tipos-de-dados)\n9. [User-Defined Types (UDT)](#user-defined-types-udt)\n10. [Opera\u00e7\u00f5es em Lote](#opera\u00e7\u00f5es-em-lote)\n11. [Migra\u00e7\u00f5es](#migra\u00e7\u00f5es)\n12. [CLI (Interface de Linha de Comando)](#cli-interface-de-linha-de-comando)\n13. [Integra\u00e7\u00e3o com FastAPI](#integra\u00e7\u00e3o-com-fastapi)\n14. [Performance e Otimiza\u00e7\u00e3o](#performance-e-otimiza\u00e7\u00e3o)\n15. [Tratamento de Erros](#tratamento-de-erros)\n16. [Exemplos Pr\u00e1ticos](#exemplos-pr\u00e1ticos)\n17. [Refer\u00eancia da API](#refer\u00eancia-da-api)\n\n---\n\n## Vis\u00e3o Geral\n\nCaspyORM \u00e9 um ORM (Object-Relational Mapping) moderno e eficiente para Apache Cassandra, constru\u00eddo com Python e Pydantic. Ele oferece uma interface intuitiva e type-safe para trabalhar com o Cassandra, combinando a simplicidade do Pydantic com a pot\u00eancia do Cassandra.\n\n### Caracter\u00edsticas Principais\n\n- **Type Safety**: Valida\u00e7\u00e3o autom\u00e1tica de tipos usando Pydantic\n- **Interface Intuitiva**: API similar ao Django ORM e SQLAlchemy\n- **Suporte Completo ao Cassandra**: Todos os tipos de dados nativos\n- **User-Defined Types**: Suporte completo a UDTs\n- **Opera\u00e7\u00f5es em Lote**: Otimiza\u00e7\u00f5es para grandes volumes de dados\n- **Migra\u00e7\u00f5es**: Sistema de migra\u00e7\u00f5es autom\u00e1tico\n- **CLI**: Interface de linha de comando para opera\u00e7\u00f5es comuns\n- **Integra\u00e7\u00e3o FastAPI**: Suporte nativo para FastAPI\n- **Performance**: Otimizado para alta performance\n\n---\n\n## Instala\u00e7\u00e3o\n\n### Instala\u00e7\u00e3o B\u00e1sica\n\n```bash\npip install caspyorm\n```\n\n### Instala\u00e7\u00e3o com Depend\u00eancias Opcionais\n\n```bash\n# Com suporte a FastAPI\npip install caspyorm[fastapi]\n\n# Com suporte a opera\u00e7\u00f5es ass\u00edncronas otimizadas\npip install caspyorm[async]\n\n# Com todas as depend\u00eancias opcionais\npip install caspyorm[fastapi,async]\n```\n\n### Instala\u00e7\u00e3o para Desenvolvimento\n\n```bash\ngit clone https://github.com/caspyorm/caspyorm.git\ncd caspyorm\npip install -e .\n```\n\n---\n\n## Configura\u00e7\u00e3o\n\n### Configura\u00e7\u00e3o B\u00e1sica\n\n```python\nfrom caspyorm import connect\n\n# Conectar ao Cassandra\nconnect(\n contact_points=['localhost'],\n keyspace='my_keyspace',\n port=9042\n)\n```\n\n### Configura\u00e7\u00e3o Avan\u00e7ada\n\n```python\nfrom caspyorm import connect\n\nconnect(\n contact_points=['cassandra1.example.com', 'cassandra2.example.com'],\n keyspace='production_keyspace',\n port=9042,\n username='myuser',\n password='mypassword',\n ssl_options={\n 'ca_certs': '/path/to/ca.crt',\n 'check_hostname': True\n },\n protocol_version=4,\n connect_timeout=10,\n request_timeout=30\n)\n```\n\n### Configura\u00e7\u00e3o via Arquivo\n\nCrie um arquivo `caspy.toml` na raiz do projeto:\n\n```toml\n[cassandra]\nhosts = [\"localhost\"]\nkeyspace = \"my_keyspace\"\nport = 9042\nusername = \"myuser\"\npassword = \"mypassword\"\nssl = false\nprotocol_version = 4\nconnect_timeout = 10\nrequest_timeout = 30\n```\n\n### Configura\u00e7\u00e3o via Vari\u00e1veis de Ambiente\n\n```bash\nexport CASPY_HOSTS=\"localhost\"\nexport CASPY_KEYSPACE=\"my_keyspace\"\nexport CASPY_PORT=\"9042\"\nexport CASPY_USERNAME=\"myuser\"\nexport CASPY_PASSWORD=\"mypassword\"\n```\n\n---\n\n## Conceitos B\u00e1sicos\n\n### Estrutura de um Modelo\n\n```python\nfrom caspyorm import Model\nfrom caspyorm.core.fields import Text, Integer, Boolean, Timestamp\n\nclass User(Model):\n __table_name__ = \"users\"\n \n id = Integer(primary_key=True)\n username = Text(required=True)\n email = Text(required=True)\n is_active = Boolean(default=True)\n created_at = Timestamp()\n```\n\n### Principais Componentes\n\n1. **Model**: Classe base para todos os modelos\n2. **Fields**: Defini\u00e7\u00e3o dos tipos de dados\n3. **Connection**: Gerenciamento de conex\u00f5es\n4. **Query**: Constru\u00e7\u00e3o de consultas\n5. **Batch**: Opera\u00e7\u00f5es em lote\n\n---\n\n## Modelos e Campos\n\n### Defini\u00e7\u00e3o de Modelos\n\n```python\nfrom caspyorm import Model\nfrom caspyorm.core.fields import (\n Text, Integer, Boolean, Timestamp, \n UUID, Float, List, Set, Map, Tuple\n)\n\nclass Product(Model):\n __table_name__ = \"products\"\n \n # Chaves prim\u00e1rias\n id = UUID(primary_key=True) # Gera UUID automaticamente\n category_id = Integer(partition_key=True)\n \n # Campos b\u00e1sicos\n name = Text(required=True)\n description = Text()\n price = Float(required=True)\n is_active = Boolean(default=True)\n \n # Campos de data\n created_at = Timestamp()\n updated_at = Timestamp()\n \n # Campos de cole\u00e7\u00e3o\n tags = Set(Text(), default=set)\n attributes = Map(Text(), Text(), default=dict)\n dimensions = Tuple(Integer(), Integer(), Integer())\n images = List(Text(), default=list)\n```\n\n### Tipos de Chaves\n\n```python\nclass Order(Model):\n __table_name__ = \"orders\"\n \n # Chave de parti\u00e7\u00e3o (obrigat\u00f3ria)\n user_id = Integer(partition_key=True)\n \n # Chaves de clustering (opcionais)\n order_date = Timestamp(clustering_key=True)\n order_id = UUID(clustering_key=True)\n \n # Campos normais\n status = Text(required=True)\n total = Float(required=True)\n```\n\n### Campos com \u00cdndices\n\n```python\nclass User(Model):\n __table_name__ = \"users\"\n \n id = Integer(primary_key=True)\n email = Text(required=True, index=True) # \u00cdndice secund\u00e1rio\n username = Text(required=True, index=True)\n```\n\n---\n\n## Opera\u00e7\u00f5es CRUD\n\n### Create (Criar)\n\n```python\n# Criar um objeto\nuser = User(\n username=\"john_doe\",\n email=\"john@example.com\",\n is_active=True\n)\n\n# Salvar no banco\nuser.save()\n\n# Criar com dados espec\u00edficos\nuser = User.create(\n username=\"jane_doe\",\n email=\"jane@example.com\"\n)\n```\n\n### Read (Ler)\n\n```python\n# Buscar por chave prim\u00e1ria\nuser = User.get(id=1)\n\n# Buscar todos os registros\nall_users = User.all().all()\n\n# Buscar com limite\nusers = User.all().limit(10).all()\n\n# Buscar com filtros\nactive_users = User.all().filter(is_active=True).all()\n```\n\n### Update (Atualizar)\n\n```python\n# Atualizar um objeto\nuser = User.get(id=1)\nuser.email = \"new_email@example.com\"\nuser.save()\n\n# Atualizar m\u00faltiplos campos\nuser.update(\n email=\"new_email@example.com\",\n is_active=False\n)\n```\n\n### Delete (Deletar)\n\n```python\n# Deletar um objeto\nuser = User.get(id=1)\nuser.delete()\n\n# Deletar por chave prim\u00e1ria\nUser.delete(id=1)\n```\n\n---\n\n## Queries e Filtros\n\n### Queries B\u00e1sicas\n\n```python\n# Buscar todos\nusers = User.all().all()\n\n# Buscar com limite\nusers = User.all().limit(10).all()\n\n# Buscar com ordena\u00e7\u00e3o\nusers = User.all().order_by('created_at', 'DESC').all()\n\n# Buscar com filtros\nusers = User.all().filter(\n is_active=True,\n created_at__gte=datetime(2023, 1, 1)\n).all()\n```\n\n### Filtros Avan\u00e7ados\n\n```python\n# Filtros de compara\u00e7\u00e3o\nusers = User.all().filter(\n age__gte=18,\n age__lte=65,\n email__contains=\"@gmail.com\"\n).all()\n\n# Filtros em cole\u00e7\u00f5es\nproducts = Product.all().filter(\n tags__contains=\"electronics\",\n attributes__contains_key=\"color\"\n).all()\n\n# Filtros com operadores l\u00f3gicos\nusers = User.all().filter(\n (User.is_active == True) & (User.age >= 18)\n).all()\n```\n\n### Queries Personalizadas\n\n```python\nfrom caspyorm.core.connection import execute\n\n# Query SQL direta\nresult = execute(\"SELECT COUNT(*) FROM users WHERE is_active = true\")\ncount = result[0].count\n\n# Query com par\u00e2metros\nresult = execute(\n \"SELECT * FROM users WHERE age >= %s AND city = %s\",\n [18, \"New York\"]\n)\n```\n\n---\n\n## Tipos de Dados\n\n### Tipos B\u00e1sicos\n\n```python\nfrom caspyorm.core.fields import (\n Text, Integer, Float, Boolean, Timestamp, UUID\n)\n\nclass BasicTypes(Model):\n __table_name__ = \"basic_types\"\n \n id = Integer(primary_key=True)\n name = Text(required=True)\n age = Integer()\n height = Float()\n is_active = Boolean(default=True)\n created_at = Timestamp()\n user_id = UUID()\n```\n\n### Tipos de Cole\u00e7\u00e3o\n\n```python\nfrom caspyorm.core.fields import List, Set, Map, Tuple\n\nclass CollectionTypes(Model):\n __table_name__ = \"collection_types\"\n \n id = Integer(primary_key=True)\n \n # Lista\n tags = List(Text(), default=list)\n \n # Conjunto\n categories = Set(Text(), default=set)\n \n # Mapa\n metadata = Map(Text(), Text(), default=dict)\n \n # Tupla\n coordinates = Tuple(Integer(), Integer())\n```\n\n### Uso de Cole\u00e7\u00f5es\n\n```python\n# Criar com cole\u00e7\u00f5es\nproduct = Product(\n id=1,\n name=\"Laptop\",\n tags=[\"electronics\", \"computer\"],\n categories={\"tech\", \"hardware\"},\n metadata={\"brand\": \"Dell\", \"model\": \"XPS\"},\n dimensions=(15, 10, 1)\n)\n\n# Modificar cole\u00e7\u00f5es\nproduct.tags.append(\"gaming\")\nproduct.categories.add(\"gaming\")\nproduct.metadata[\"price\"] = \"999.99\"\n\nproduct.save()\n```\n\n---\n\n## User-Defined Types (UDT)\n\n### Definindo UDTs\n\n```python\nfrom caspyorm.types.usertype import UserType\nfrom caspyorm.core.fields import Text, Integer\n\nclass Address(UserType):\n street = Text()\n city = Text()\n state = Text()\n zip_code = Text()\n country = Text()\n\nclass Contact(UserType):\n phone = Text()\n email = Text()\n website = Text()\n```\n\n### Usando UDTs em Modelos\n\n```python\nfrom caspyorm.core.fields import UserDefinedType\n\nclass Customer(Model):\n __table_name__ = \"customers\"\n \n id = Integer(primary_key=True)\n name = Text(required=True)\n address = UserDefinedType(Address)\n contact = UserDefinedType(Contact)\n```\n\n### Opera\u00e7\u00f5es com UDTs\n\n```python\n# Criar UDT\naddress = Address(\n street=\"123 Main St\",\n city=\"New York\",\n state=\"NY\",\n zip_code=\"10001\",\n country=\"USA\"\n)\n\ncontact = Contact(\n phone=\"+1-555-1234\",\n email=\"john@example.com\",\n website=\"https://example.com\"\n)\n\n# Usar em modelo\ncustomer = Customer(\n id=1,\n name=\"John Doe\",\n address=address,\n contact=contact\n)\n\ncustomer.save()\n\n# Acessar campos do UDT\nprint(customer.address.street) # \"123 Main St\"\nprint(customer.contact.email) # \"john@example.com\"\n\n# Modificar UDT\ncustomer.address.city = \"Los Angeles\"\ncustomer.save()\n```\n\n---\n\n## Opera\u00e7\u00f5es em Lote\n\n### Inser\u00e7\u00e3o em Lote\n\n```python\nfrom caspyorm.types.batch import BatchQuery\n\n# Inserir m\u00faltiplos registros\nusers = [\n User(username=\"user1\", email=\"user1@example.com\"),\n User(username=\"user2\", email=\"user2@example.com\"),\n User(username=\"user3\", email=\"user3@example.com\")\n]\n\nwith BatchQuery():\n for user in users:\n user.save()\n```\n\n### Atualiza\u00e7\u00e3o em Lote\n\n```python\n# Atualizar m\u00faltiplos registros\nusers = User.all().filter(is_active=False).all()\n\nwith BatchQuery():\n for user in users:\n user.is_active = True\n user.save()\n```\n\n### Dele\u00e7\u00e3o em Lote\n\n```python\n# Deletar m\u00faltiplos registros\nusers = User.all().filter(created_at__lt=datetime(2020, 1, 1)).all()\n\nwith BatchQuery():\n for user in users:\n user.delete()\n```\n\n### Performance de Lote\n\n```python\nimport time\n\n# Teste de performance\nN = 1000\nbatch_size = 100\n\nt0 = time.time()\nfor start in range(0, N, batch_size):\n end = min(start + batch_size, N)\n with BatchQuery():\n for i in range(start, end):\n User(username=f\"user{i}\", email=f\"user{i}@example.com\").save()\nt1 = time.time()\n\nprint(f\"Tempo para inserir {N} registros: {t1-t0:.2f}s\")\n```\n\n---\n\n## Migra\u00e7\u00f5es\n\n### Inicializa\u00e7\u00e3o\n\n```bash\n# Inicializar sistema de migra\u00e7\u00f5es\ncaspyorm migrate init --keyspace my_keyspace\n```\n\n### Criar Nova Migra\u00e7\u00e3o\n\n```bash\n# Criar nova migra\u00e7\u00e3o\ncaspyorm migrate new create_users_table\n```\n\n### Estrutura de Migra\u00e7\u00e3o\n\n```python\n# migrations/V001_create_users_table.py\nfrom caspyorm.core.connection import get_session\nfrom caspyorm.utils.schema import create_table\nfrom models import User\n\ndef upgrade():\n \"\"\"Executa a migra\u00e7\u00e3o para cima.\"\"\"\n session = get_session()\n create_table(session, User)\n\ndef downgrade():\n \"\"\"Reverte a migra\u00e7\u00e3o.\"\"\"\n session = get_session()\n session.execute(\"DROP TABLE IF EXISTS users\")\n```\n\n### Aplicar Migra\u00e7\u00f5es\n\n```bash\n# Aplicar todas as migra\u00e7\u00f5es pendentes\ncaspyorm migrate apply --keyspace my_keyspace\n\n# Verificar status das migra\u00e7\u00f5es\ncaspyorm migrate status --keyspace my_keyspace\n\n# Reverter \u00faltima migra\u00e7\u00e3o\ncaspyorm migrate downgrade --keyspace my_keyspace --force\n```\n\n### Migra\u00e7\u00f5es Complexas\n\n```python\ndef upgrade():\n session = get_session()\n \n # Criar nova tabela\n session.execute(\"\"\"\n CREATE TABLE IF NOT EXISTS user_profiles (\n user_id int PRIMARY KEY,\n bio text,\n avatar_url text,\n preferences map<text, text>\n )\n \"\"\")\n \n # Adicionar coluna a tabela existente\n session.execute(\"\"\"\n ALTER TABLE users ADD phone text\n \"\"\")\n \n # Criar \u00edndice\n session.execute(\"\"\"\n CREATE INDEX IF NOT EXISTS idx_users_email ON users (email)\n \"\"\")\n\ndef downgrade():\n session = get_session()\n \n # Remover \u00edndice\n session.execute(\"DROP INDEX IF EXISTS idx_users_email\")\n \n # Remover coluna\n session.execute(\"ALTER TABLE users DROP phone\")\n \n # Remover tabela\n session.execute(\"DROP TABLE IF EXISTS user_profiles\")\n```\n\n---\n\n## CLI (Interface de Linha de Comando)\n\n### Comandos B\u00e1sicos\n\n```bash\n# Informa\u00e7\u00f5es da conex\u00e3o\ncaspyorm info\n\n# Listar modelos dispon\u00edveis\ncaspyorm models\n\n# Conectar ao Cassandra\ncaspyorm connect --keyspace my_keyspace\n\n# Executar query SQL\ncaspyorm sql \"SELECT COUNT(*) FROM users\"\n\n# Query em modelo\ncaspyorm query users count\ncaspyorm query users filter --filter \"is_active=true\" --limit 10\n```\n\n### Comandos de Migra\u00e7\u00e3o\n\n```bash\n# Inicializar migra\u00e7\u00f5es\ncaspyorm migrate init --keyspace my_keyspace\n\n# Criar nova migra\u00e7\u00e3o\ncaspyorm migrate new create_table_name\n\n# Aplicar migra\u00e7\u00f5es\ncaspyorm migrate apply --keyspace my_keyspace\n\n# Status das migra\u00e7\u00f5es\ncaspyorm migrate status --keyspace my_keyspace\n\n# Reverter migra\u00e7\u00e3o\ncaspyorm migrate downgrade --keyspace my_keyspace --force\n```\n\n### Configura\u00e7\u00e3o da CLI\n\n```bash\n# Via vari\u00e1veis de ambiente\nexport CASPY_HOSTS=\"localhost\"\nexport CASPY_KEYSPACE=\"my_keyspace\"\nexport CASPY_PORT=\"9042\"\n\n# Via arquivo caspy.toml\ncaspyorm --config caspy.toml info\n```\n\n---\n\n## Integra\u00e7\u00e3o com FastAPI\n\n### Configura\u00e7\u00e3o B\u00e1sica\n\n```python\nfrom fastapi import FastAPI\nfrom caspyorm.contrib.fastapi import CaspyORM\n\napp = FastAPI()\n\n# Configurar CaspyORM\ncaspyorm = CaspyORM(\n contact_points=['localhost'],\n keyspace='my_keyspace',\n port=9042\n)\n\n# Incluir no app\napp.include_router(caspyorm.router)\n```\n\n### Modelos FastAPI\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Optional, List\n\nclass UserCreate(BaseModel):\n username: str\n email: str\n is_active: bool = True\n\nclass UserResponse(BaseModel):\n id: int\n username: str\n email: str\n is_active: bool\n created_at: Optional[datetime]\n\n# Endpoints autom\u00e1ticos\n@caspyorm.crud(User, UserCreate, UserResponse)\nclass UserCRUD:\n pass\n```\n\n### Endpoints Customizados\n\n```python\nfrom fastapi import APIRouter, HTTPException\n\nrouter = APIRouter()\n\n@router.get(\"/users/{user_id}\")\nasync def get_user(user_id: int):\n user = User.get(id=user_id)\n if not user:\n raise HTTPException(status_code=404, detail=\"User not found\")\n return user\n\n@router.post(\"/users\")\nasync def create_user(user_data: UserCreate):\n user = User(**user_data.dict())\n user.save()\n return user\n\n@router.put(\"/users/{user_id}\")\nasync def update_user(user_id: int, user_data: UserCreate):\n user = User.get(id=user_id)\n if not user:\n raise HTTPException(status_code=404, detail=\"User not found\")\n \n user.update(**user_data.dict())\n return user\n\n@router.delete(\"/users/{user_id}\")\nasync def delete_user(user_id: int):\n user = User.get(id=user_id)\n if not user:\n raise HTTPException(status_code=404, detail=\"User not found\")\n \n user.delete()\n return {\"message\": \"User deleted\"}\n```\n\n---\n\n## Performance e Otimiza\u00e7\u00e3o\n\n### Estrat\u00e9gias de Otimiza\u00e7\u00e3o\n\n1. **Uso de \u00cdndices**\n```python\nclass User(Model):\n __table_name__ = \"users\"\n \n id = Integer(primary_key=True)\n email = Text(required=True, index=True) # \u00cdndice para busca por email\n username = Text(required=True, index=True)\n```\n\n2. **Opera\u00e7\u00f5es em Lote**\n```python\n# Inserir em lotes para melhor performance\nwith BatchQuery():\n for user in users:\n user.save()\n```\n\n3. **Limita\u00e7\u00e3o de Resultados**\n```python\n# Usar LIMIT para evitar carregar muitos dados\nusers = User.all().limit(100).all()\n```\n\n4. **Filtros Eficientes**\n```python\n# Usar chaves de parti\u00e7\u00e3o e clustering\norders = Order.all().filter(\n user_id=123,\n order_date__gte=datetime(2023, 1, 1)\n).all()\n```\n\n### Monitoramento de Performance\n\n```python\nimport time\nfrom caspyorm.core.connection import get_session\n\n# Medir tempo de query\nt0 = time.time()\nusers = User.all().all()\nt1 = time.time()\nprint(f\"Query executada em {t1-t0:.2f}s\")\n\n# Verificar estat\u00edsticas da sess\u00e3o\nsession = get_session()\nprint(f\"Queries executadas: {session.query_count}\")\nprint(f\"Tempo total: {session.total_time:.2f}s\")\n```\n\n---\n\n## Tratamento de Erros\n\n### Exce\u00e7\u00f5es Comuns\n\n```python\nfrom caspyorm.utils.exceptions import (\n ValidationError, ConnectionError, QueryError\n)\n\ntry:\n user = User(username=\"john\", email=\"invalid-email\")\n user.save()\nexcept ValidationError as e:\n print(f\"Erro de valida\u00e7\u00e3o: {e}\")\nexcept ConnectionError as e:\n print(f\"Erro de conex\u00e3o: {e}\")\nexcept QueryError as e:\n print(f\"Erro de query: {e}\")\n```\n\n### Valida\u00e7\u00e3o de Dados\n\n```python\nfrom caspyorm.utils.exceptions import ValidationError\n\n# Valida\u00e7\u00e3o autom\u00e1tica\ntry:\n user = User(\n id=\"not_an_integer\", # Erro: deve ser int\n email=\"invalid-email\" # Erro: formato inv\u00e1lido\n )\nexcept ValidationError as e:\n print(f\"Erros de valida\u00e7\u00e3o: {e.errors}\")\n```\n\n### Tratamento de Conex\u00e3o\n\n```python\nfrom caspyorm import connect, disconnect\nfrom caspyorm.utils.exceptions import ConnectionError\n\ntry:\n connect(contact_points=['localhost'], keyspace='my_keyspace')\n # Opera\u00e7\u00f5es com o banco\nexcept ConnectionError as e:\n print(f\"Falha na conex\u00e3o: {e}\")\nfinally:\n disconnect()\n```\n\n---\n\n## Exemplos Pr\u00e1ticos\n\n### Sistema de Blog\n\n```python\nfrom caspyorm import Model\nfrom caspyorm.core.fields import (\n Integer, Text, Timestamp, Set, Map, UserDefinedType, Boolean\n)\nfrom caspyorm.types.usertype import UserType\n\nclass Author(UserType):\n name = Text()\n email = Text()\n bio = Text()\n\nclass Post(Model):\n __table_name__ = \"posts\"\n \n id = Integer(primary_key=True)\n title = Text(required=True)\n content = Text(required=True)\n author = UserDefinedType(Author)\n tags = Set(Text(), default=set)\n metadata = Map(Text(), Text(), default=dict)\n created_at = Timestamp()\n updated_at = Timestamp()\n is_published = Boolean(default=False)\n\n# Criar post\nauthor = Author(name=\"John Doe\", email=\"john@example.com\", bio=\"Tech writer\")\npost = Post(\n title=\"Getting Started with CaspyORM\",\n content=\"CaspyORM is a modern ORM for Cassandra...\",\n author=author,\n tags={\"cassandra\", \"python\", \"orm\"},\n metadata={\"category\": \"tutorial\", \"difficulty\": \"beginner\"}\n)\npost.save()\n\n# Buscar posts\npublished_posts = Post.all().filter(is_published=True).all()\ntech_posts = Post.all().filter(tags__contains=\"python\").all()\n```\n\n### Sistema de E-commerce\n\n```python\nclass Product(Model):\n __table_name__ = \"products\"\n \n id = Integer(primary_key=True)\n name = Text(required=True)\n description = Text()\n price = Float(required=True)\n category_id = Integer(partition_key=True)\n tags = Set(Text(), default=set)\n attributes = Map(Text(), Text(), default=dict)\n stock = Integer(default=0)\n is_active = Boolean(default=True)\n created_at = Timestamp()\n\nclass Order(Model):\n __table_name__ = \"orders\"\n \n user_id = Integer(partition_key=True)\n order_date = Timestamp(clustering_key=True)\n order_id = UUID(clustering_key=True)\n status = Text(required=True)\n total = Float(required=True)\n items = List(Text(), default=list) # Lista de IDs de produtos\n shipping_address = UserDefinedType(Address)\n created_at = Timestamp()\n\n# Buscar produtos por categoria\nelectronics = Product.all().filter(category_id=1, is_active=True).all()\n\n# Buscar pedidos de um usu\u00e1rio\nuser_orders = Order.all().filter(user_id=123).order_by('order_date', 'DESC').all()\n\n# Buscar pedidos por status\npending_orders = Order.all().filter(status=\"pending\").all()\n```\n\n---\n\n## Refer\u00eancia da API\n\n### Model\n\n```python\nclass Model:\n # M\u00e9todos de classe\n @classmethod\n def all(cls) -> Query\n @classmethod\n def get(cls, **kwargs) -> Optional[Model]\n @classmethod\n def create(cls, **kwargs) -> Model\n @classmethod\n def delete(cls, **kwargs) -> bool\n \n # M\u00e9todos de inst\u00e2ncia\n def save(self) -> None\n def update(self, **kwargs) -> None\n def delete(self) -> None\n def model_dump(self) -> dict\n def model_dump_json(self) -> str\n```\n\n### Query\n\n```python\nclass Query:\n def filter(self, **kwargs) -> Query\n def order_by(self, field: str, direction: str = \"ASC\") -> Query\n def limit(self, limit: int) -> Query\n def allow_filtering(self) -> Query\n def all(self) -> List[Model]\n def first(self) -> Optional[Model]\n def count(self) -> int\n```\n\n### Fields\n\n```python\n# Tipos b\u00e1sicos\nText(primary_key=False, required=False, default=None, index=False)\nInteger(primary_key=False, required=False, default=None, index=False)\nFloat(primary_key=False, required=False, default=None, index=False)\nBoolean(primary_key=False, required=False, default=None, index=False)\nTimestamp(primary_key=False, required=False, default=None, index=False)\nUUID(primary_key=False, required=False, default=None, index=False)\n\n# Tipos de cole\u00e7\u00e3o\nList(inner_field: BaseField, **kwargs)\nSet(inner_field: BaseField, **kwargs)\nMap(key_field: BaseField, value_field: BaseField, **kwargs)\nTuple(*field_types: BaseField, **kwargs)\n\n# User-Defined Types\nUserDefinedType(udt_class: Type, **kwargs)\n```\n\n### Connection\n\n```python\ndef connect(\n contact_points: List[str],\n keyspace: str,\n port: int = 9042,\n username: Optional[str] = None,\n password: Optional[str] = None,\n ssl_options: Optional[dict] = None,\n protocol_version: int = 4,\n connect_timeout: int = 10,\n request_timeout: int = 30\n) -> None\n\ndef disconnect() -> None\ndef get_session() -> Session\ndef execute(query: str, params: Optional[List] = None) -> ResultSet\n```\n\n### Batch\n\n```python\nclass BatchQuery:\n def __enter__(self) -> BatchQuery\n def __exit__(self, exc_type, exc_val, exc_tb) -> None\n```\n\n### Exceptions\n\n```python\nclass ValidationError(Exception)\nclass ConnectionError(Exception)\nclass QueryError(Exception)\nclass SchemaError(Exception)\n```\n\n---\n\n## Conclus\u00e3o\n\nCaspyORM oferece uma solu\u00e7\u00e3o completa e moderna para trabalhar com Apache Cassandra em Python. Com sua interface intuitiva, valida\u00e7\u00e3o autom\u00e1tica de tipos, suporte completo aos recursos do Cassandra e ferramentas de desenvolvimento, \u00e9 a escolha ideal para projetos que precisam de performance e escalabilidade.\n\nPara mais informa\u00e7\u00f5es, exemplos e atualiza\u00e7\u00f5es, visite:\n- [Documenta\u00e7\u00e3o Oficial](https://caspyorm.dev)\n- [GitHub Repository](https://github.com/caspyorm/caspyorm)\n- [PyPI Package](https://pypi.org/project/caspyorm/)\n\n## Licen\u00e7a\n\nEste projeto est\u00e1 licenciado sob a Licen\u00e7a MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.\n\n## Contribuindo\n\nContribui\u00e7\u00f5es s\u00e3o bem-vindas! Por favor, leia o [guia de contribui\u00e7\u00e3o](CONTRIBUTING.md) antes de submeter um pull request.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Um ORM moderno e eficiente para Apache Cassandra",
"version": "0.1.7",
"project_urls": {
"Bug Tracker": "https://github.com/caspyorm/caspyorm/issues",
"Documentation": "https://caspyorm.readthedocs.io",
"Homepage": "https://github.com/caspyorm/caspyorm",
"Repository": "https://github.com/caspyorm/caspyorm",
"Source Code": "https://github.com/caspyorm/caspyorm"
},
"split_keywords": [
"cassandra",
" database",
" fastapi",
" nosql",
" orm",
" pydantic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bab26c4ee6f5af1daa993c82f8fd5d2151e7ca8b9697fc8aa71516046023c130",
"md5": "86c629a1c5e9a1f224247f107f14a810",
"sha256": "9ca561b735afbe6850f492a86bf85e22c7eb6e3fbee274578365d917278dddf1"
},
"downloads": -1,
"filename": "caspyorm-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86c629a1c5e9a1f224247f107f14a810",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9121,
"upload_time": "2025-07-12T14:19:49",
"upload_time_iso_8601": "2025-07-12T14:19:49.672734Z",
"url": "https://files.pythonhosted.org/packages/ba/b2/6c4ee6f5af1daa993c82f8fd5d2151e7ca8b9697fc8aa71516046023c130/caspyorm-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "11e970bb4b1a42bfad15e787ab57c0c1ab05c2a409fa0597b39fdbdad4111c44",
"md5": "bde3adc9780e8af657c881c94ebac5e6",
"sha256": "f53f8c7ff072bafc268b8d759f477a351b1b8dd3f8e0473c1de0264bd3848fe7"
},
"downloads": -1,
"filename": "caspyorm-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "bde3adc9780e8af657c881c94ebac5e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 45387,
"upload_time": "2025-07-12T14:19:51",
"upload_time_iso_8601": "2025-07-12T14:19:51.167110Z",
"url": "https://files.pythonhosted.org/packages/11/e9/70bb4b1a42bfad15e787ab57c0c1ab05c2a409fa0597b39fdbdad4111c44/caspyorm-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 14:19:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caspyorm",
"github_project": "caspyorm",
"github_not_found": true,
"lcname": "caspyorm"
}
JSON
