# DSD

[![PyPI version](https://badge.fury.io/py/dsd.svg)](https://badge.fury.io/py/dsd)
[![Python Versions](https://img.shields.io/pypi/pyversions/dsd.svg)](https://pypi.org/project/dsd/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**DSD** é uma biblioteca Python para extração e processamento de dados do portal do **Supremo Tribunal Federal (STF)** do Brasil.

## 🚀 Funcionalidades

- ✅ **Web Scraping** do portal STF
- ✅ **Extração de processos** judiciais
- ✅ **Processamento de andamentos** processuais
- ✅ **Extração de partes** envolvidas
- ✅ **Limpeza e normalização** de dados
- ✅ **Exportação para CSV**
- ✅ **Type hints** completos (Python 3.7+)
- ✅ **Documentação** inline (docstrings)

## 📦 Instalação

### Via pip (recomendado)

```bash
pip install dsd-br
```

### Via repositório Git

```bash
git clone https://github.com/AlexandreAraujoCosta/DSD.git
cd dsd
pip install -e .
```

### Instalação para desenvolvimento

```bash
pip install -e ".[dev]"
```

## 🎯 Uso Rápido

### Exemplo Básico

```python
import dsd

# Fazer requisição ao STF
html = dsd.get("https://portal.stf.jus.br/processos/...")

# Extrair informações
partes = dsd.extrair_partes(html)
andamentos = dsd.extrair_andamentos(html)

# Processar dados
dados_limpos = dsd.limpar(dados)

# Salvar em CSV
dsd.write_csv_header("processos.csv", "processo;parte;data")
dsd.write_csv_row("processos.csv", [processo, parte, data])
```

### Trabalhando com Datas

```python
from dsd import date, ajustar_mes

# Converter formato de data
data_br = "31/12/2023"
data_iso = date(data_br)  # "2023-12-31"

# Converter mês abreviado
mes_numero = ajustar_mes("DEZ")  # "12"
```

### Trabalhando com Estados

```python
from dsd import limpa_estado, estado_nome_completo, siglas

# Converter estado para sigla
sigla = limpa_estado("SAO PAULO")  # "/SP"

# Converter sigla para nome completo
nome = estado_nome_completo("/SP")  # "SAO PAULO"

# Obter lista de siglas
lista_siglas = siglas()  # ['AC', 'AL', 'AP', ...]
```

### Extração de Texto

```python
from dsd import extract, clean

# Extrair texto entre delimitadores
texto_html = "<div>Conteúdo importante</div>"
conteudo = extract(texto_html, "<div>", "</div>")  # "Conteúdo importante"

# Limpar texto
texto_sujo = "  Texto   com\nespaços  "
texto_limpo = clean(texto_sujo)  # "Texto com espaços"
```

### Trabalhando com Arquivos

```python
from dsd import carregar_arquivo, gravar, csv_to_list

# Carregar arquivo
conteudo = carregar_arquivo("processo.html")

# Gravar dados
gravar("resultado.txt", "Dados processados")

# Converter CSV para lista
dados = csv_to_list("dados.csv")
```

## 📚 Documentação Completa

### Funções de Requisição HTTP

- `get(url: str) -> str`: Faz requisição GET e retorna HTML
- `get_json(url: str) -> dict`: Faz requisição GET e retorna JSON
- `get_response(url: str) -> Response`: Retorna objeto Response completo

### Funções de Extração

- `extract(source: str, start_at: str, end_at: str) -> str`: Extrai texto entre delimitadores
- `extrair_partes(string: str) -> str`: Extrai partes processuais do HTML
- `extrair_andamentos(string: str) -> list`: Extrai andamentos processuais

### Funções de Limpeza

- `clean(source: str) -> str`: Remove espaços e caracteres especiais
- `limpar(fonte: str) -> str`: Limpeza completa de texto
- `limpar_para_csv(fonte: str) -> str`: Prepara texto para CSV

### Funções de Arquivo e CSV

- `carregar_arquivo(nomedoarquivo: str) -> str`: Carrega arquivo
- `gravar(nomedoarquivo: str, dados: str) -> None`: Grava dados
- `csv_to_list(file: str) -> list`: Converte CSV para lista
- `write_csv_header(nomedoarquivo: str, string_campos: str) -> None`: Escreve cabeçalho CSV
- `write_csv_row(nomedoarquivo: str, dados: str) -> None`: Escreve linha CSV

## 🛠️ Requisitos

- Python >= 3.7
- requests >= 2.31.0
- selenium >= 4.0.0

## 🤝 Contribuindo

Contribuições são bem-vindas! Para contribuir:

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
3. Commit suas mudanças (`git commit -m 'Adiciona MinhaFeature'`)
4. Push para a branch (`git push origin feature/MinhaFeature`)
5. Abra um Pull Request

### Desenvolvimento

```bash
# Clone o repositório
git clone https://github.com/AlexandreAraujoCosta/DSD.git
cd dsd

# Instale em modo desenvolvimento
pip install -e ".[dev]"

# Execute os testes
pytest

# Formate o código
black dsd/

# Verifique tipos
mypy dsd/
```

## 📝 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.

## 👥 Autores

**Alexandre Araújo Costa**
- Email: alexandre.araujo.costa@gmail.com

**Henrique Araújo Costa**
- Coautor

## 🙏 Agradecimentos

- Comunidade Python Brasil
- Supremo Tribunal Federal por disponibilizar os dados publicamente

## 📊 Status do Projeto

🚧 **Em desenvolvimento ativo** - Versão 0.1.0

## 🔗 Links Úteis

- [Documentação do STF](https://portal.stf.jus.br)
- [PyPI Package](https://pypi.org/project/dsd-br/)
- [Issues](https://github.com/AlexandreAraujoCosta/DSD/issues)

## 📈 Changelog

### [0.1.0] - 2024-01-XX

#### Adicionado
- Estrutura inicial do pacote
- Funções de web scraping do STF
- Funções de processamento de dados
- Suporte a CSV
- Type hints completos
- Documentação inline

---

**⭐ Se este projeto foi útil para você, considere dar uma estrela no GitHub!**
