pydevhelper 0.3.0
Um toolkit de produtividade para desenvolvedores em Python
License: MIT
Requires Python: >=3.9

# PyDevHelper

[![PyPI version](https://img.shields.io/pypi/v/pydevhelper.svg)](https://pypi.org/project/pydevhelper/)
[![Python versions](https://img.shields.io/pypi/pyversions/pydevhelper.svg)](https://pypi.org/project/pydevhelper/)
[![License](https://img.shields.io/pypi/l/pydevhelper.svg)](https://github.com/juliobrige/DevHelper/blob/main/LICENSE)

---

Uma coleção de **utilitários para desenvolvedores Python** — logging elegante, medição de tempo, retry automático, manipulação de JSON, tratamento de strings e muito mais.

A collection of **developer utilities for Python** — elegant logging, timing, retry decorator, JSON helpers, string utilities and more.

---

Um toolkit de produtividade para desenvolvedores Python, desenhado para acelerar tarefas comuns do dia a dia com ferramentas robustas e fáceis de usar.

Chega de copiar e colar o mesmo código de utilidade em todos os seus projetos! `pydevhelper` oferece soluções prontas e testadas para configuração, logging, debugging e manipulação de dados.

## Funcionalidades Principais

* **Configuração Segura:** Carregue e valide variáveis de ambiente a partir de um schema, com type casting automático.
* **Logging Inteligente:** Configure logs coloridos e úteis para o terminal com uma única linha de código.
* **Decorators Poderosos:** Adicione resiliência (`@retry`) e análise de performance (`@timer`) às suas funções sem esforço.
* **Utilidades de Dados:** Um conjunto rico de funções para limpar texto (`slugify`, `camel_to_snake`), manipular JSON (`read_json`, `write_json`) e apresentar dados em tabelas (`print_table`) com estilo.


## 🚀 Instalação | Installation

```bash
pip install pydevhelper


 ##Guia Rápido (Quick Start)

Veja como o `pydevhelper` pode simplificar o seu código.


```bash
```python
import logging
import requests
from dev_helper import setup_logging, load_env, EnvSpec, VarSpec, timer, retry, print_table

# 1. Configure logs coloridos para o terminal
```bash
setup_logging(colors=True)

# 2. Defina e carregue a configuração da sua aplicação de forma segura
# (Isto irá ler as variáveis de ambiente APP_API_URL e APP_RETRIES)
try:
    config = load_env(EnvSpec(
        vars=[
            VarSpec("API_URL", help="URL da API de dados"),
            VarSpec("RETRIES", type="int", default=3),
        ],
        prefix="APP_"
    ))
except Exception as e:
    logging.error(f"Erro de configuração: {e}")
    exit(1)

# 3. Crie uma função robusta e monitorizada com decorators
@retry(tries=config["RETRIES"], delay=1, exceptions=(requests.exceptions.RequestException,))
@timer(template="[PERF] '{func_name}' contactou a API em {elapsed:.2f}s")
def buscar_dados_de_utilizadores():
    """Busca dados de uma API externa, com retentativas em caso de falha."""
    logging.info(f"A contactar a API em {config['API_URL']}...")
    response = requests.get(config["API_URL"])
    response.raise_for_status() # Levanta um erro se o pedido falhar
    return response.json()

# 4. Execute e apresente os resultados com estilo
try:
    dados = buscar_dados_de_utilizadores()
    logging.info("Dados recebidos com sucesso!")
    
    # 5. Apresente os dados numa tabela bonita
    print_table(dados, title="Relatório de Utilizadores")
    
except Exception as e:
    logging.critical(f"Não foi possível obter os dados após várias tentativas: {e}")

```


## 📌 Roadmap

* [ ] Suporte a YAML (io_utils)
* [ ] Mais transformações de texto (snake → kebab, title case etc.)
* [ ] CLI para acessar utilitários diretamente no terminal

---

## 🇺🇸 Features (English)

- ✅ Logging setup in one line  
- ✅ Environment variable checking (`require_vars`)  
- ✅ Execution time measurement with `@timer`  
- ✅ Pretty-printing tables in the terminal (`print_table`)  

---




## ⚡ Uso rápido | Quick Usage
from dev_helper import setup_logging, require_vars, timer, print_table

# Setup logging
setup_logging()

# Ensure required environment variables exist
require_vars(["PATH"])

# Measure execution time
@timer
def main():
    data = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
    print_table(data)

main()



from dev_helper import setup_logging

setup_logging(colors=True)

import logging
logging.info("Mensagem colorida!")



from dev_helper import timer, setup_logging

setup_logging(colors=True)

@timer()
def process_data():
    return sum(range(100000))

process_data()



from dev_helper import retry
import random

@retry(tries=3, delay=1, backoff=2)
def unstable():
    if random.random() < 0.7:
        raise ValueError("Falhou")
    return "Sucesso!"

print(unstable())



from dev_helper import write_json, read_json

data = {"id": 1, "name": "Alice"}
write_json("data.json", data)

print(read_json("data.json"))



from dev_helper import slugify, camel_to_snake, snake_to_camel, extract_emails, extract_urls

print(slugify("Título de Exemplo com Áccentos"))  # titulo-de-exemplo-com-accents
print(slugify("日本語 テキスト", allow_unicode=True))  # 日本語-テキスト
print(camel_to_snake("CamelCaseTest"))  # camel_case_test
print(snake_to_camel("snake_case_test"))  # SnakeCaseTest
print(extract_emails("contato: dev@helper.org"))  # ['dev@helper.org']
print(extract_urls("Veja https://example.com"))   # ['https://example.com']



-----

## Referência da API (v0.2.0)

### Core

  * `load_env(spec: EnvSpec)`: Valida e carrega variáveis de ambiente.
  * `require_vars(vars: list[str])`: Garante que variáveis existem (versão legada).
  * `setup_logging(level, colors, file, logger_name)`: Configura o logging.

### Decorators

  * `@timer(level, template, logger)`: Mede e loga o tempo de execução de uma função.
  * `@retry(tries, delay, backoff, exceptions, ...)`: Tenta executar uma função novamente em caso de falha.

### Utils

  * `print_table(data, title)`: Imprime uma lista de dicionários como uma tabela estilizada (usando `rich`).
  * `slugify(text, allow_unicode)`: Converte texto num slug para URL.
  * `camel_to_snake(text)` e `snake_to_camel(text)`: Converte entre estilos de nomenclatura.
  * `normalize_whitespace(text)`: Limpa espaços extra.
  * `remove_html_tags(text)`: Remove tags HTML.
  * `extract_emails(text)` e `extract_urls(text)`: Extrai emails e URLs de um texto.
  * `read_json(path, safe)` e `write_json(path, data)`: Helpers para ficheiros JSON.
  * `append_json_line(path, record)`: Escreve no formato JSON Lines.
  * `pretty_print_json(data)`: Retorna uma string JSON formatada.

-----