Metadata-Version: 2.4
Name: scrapy_html
Version: 1.2.0
Summary: 🌐 Um scraper que retorna o HTML completo de uma URL, tags, classes e atributos usando BeautifulSoup
Home-page: https://github.com/robertolima-dev/scrapy-html
Author: Roberto Lima
Author-email: Roberto Lima <robertolima.izphera@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/robertolima-dev/scrapy-html
Project-URL: Repository, https://github.com/robertolima-dev/scrapy-html
Project-URL: Issues, https://github.com/robertolima-dev/scrapy-html/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: requests>=2.31.0
Requires-Dist: lxml>=4.9.0
Provides-Extra: lxml
Requires-Dist: lxml>=4.9.0; extra == "lxml"
Provides-Extra: html5lib
Requires-Dist: html5lib>=1.1; extra == "html5lib"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

### 🚀 **README.md**

# 🌐 Scrapy-HTML

🔍 **Scrapy-HTML** é um pacote Python simples e eficiente para scraping de conteúdo HTML de qualquer página web. Agora com **parâmetros avançados** para filtragem por tag, múltiplas tags, classe CSS e atributos personalizados, tornando a raspagem muito mais flexível e poderosa. Ele utiliza as bibliotecas **BeautifulSoup4** e **Requests** para realizar a raspagem e retornar o HTML de forma estruturada e legível.

---

## ✨ **Características Principais**

- 🌎 Faz scraping de qualquer página web com uma URL válida.
- 🔍 **Filtragem avançada** por:
  - Tag única (`tag`)
  - Múltiplas tags (`tags`)
  - Classe CSS (`class_`)
  - ID (`id_`)
  - Atributos personalizados (`attrs`)
  - Headers HTTP personalizados (`headers`)
- ⚡ **Múltiplos parsers HTML**:
  - `html.parser` (padrão): Parser nativo do Python
  - `lxml`: Parser rápido baseado em C
  - `html5lib`: Parser mais leniente e compatível com HTML5
- ⚡ Retorna o HTML formatado e legível usando `BeautifulSoup`.
- 🔒 Tratamento de erros robusto para URLs inválidas ou problemas de rede.
- 💡 Leve e fácil de usar, com dependências mínimas.

---

## ⚡ **Instalação**

Instale o pacote diretamente do **PyPI**:

```bash
pip install scrapy_html
```

### 📦 **Parsers Opcionais**

Para usar parsers alternativos, instale as dependências opcionais:

```bash
# Para usar o parser lxml (mais rápido)
pip install scrapy_html[lxml]

# Para usar o parser html5lib (mais leniente)
pip install scrapy_html[html5lib]

# Para usar todos os parsers
pip install scrapy_html[lxml,html5lib]
```

---

## 💻 **Como Usar**

### 🔥 **Exemplo básico de uso:**
```python
from scrapy_html.scraper import get_html_content

# 🌐 URL da página
url = "https://www.example.com"

# 🔄 Obtendo o conteúdo HTML completo
dados = get_html_content(url)
print(dados)
```

### 🎯 **Filtragem Avançada:**

#### 🔍 **Filtrar por tag única:**
```python
dados = get_html_content(url, tag="p")
print(dados)  # Exibe todas as tags <p>
```

#### 🏷 **Filtrar por múltiplas tags:**
```python
dados = get_html_content(url, tags="div,span")
print(dados)  # Exibe todas as tags <div> e <span>
```

#### 🎨 **Filtrar por classe CSS:**
```python
dados = get_html_content(url, tag="a", class_="link-destaque")
print(dados)
```

#### 🆔 **Filtrar por ID:**
```python
dados = get_html_content(url, tag="section", id_="conteudo-principal")
print(dados)
```

#### 🛠 **Filtrar por atributos personalizados:**
```python
dados = get_html_content(url, tag="img", attrs={"alt": "Imagem principal"})
print(dados)
```

#### 🔒 **Usar headers personalizados:**
```python
headers = {
    "User-Agent": "Mozilla/5.0",
    "Accept": "text/html",
    "Accept-Language": "pt-BR"
}
dados = get_html_content(url, headers=headers)
print(dados)
```

#### 🔍 **Usar diferentes parsers HTML:**
```python
# Usando o parser padrão (html.parser)
dados = get_html_content(url)
print(dados)

# Usando o parser lxml (mais rápido)
dados = get_html_content(url, parser="lxml")
print(dados)

# Usando o parser html5lib (mais leniente)
dados = get_html_content(url, parser="html5lib")
print(dados)
```

---

## 🛠 **Requisitos**

- Python >= 3.6
- [beautifulsoup4](https://pypi.org/project/beautifulsoup4/)
- [requests](https://pypi.org/project/requests/)

As dependências são instaladas automaticamente com:

```bash
pip install scrapy_html
```

---

## 🧪 **Testes**

Este projeto inclui testes usando **pytest**. Para rodar os testes localmente:

```bash
pip install pytest
pytest tests/
```

---

## 🎨 **Recursos Futuros**

- [x] 🔍 Parâmetros avançados para scraping filtrado.
- [ ] 🌐 Suporte a diferentes parsers (`lxml`, `html5lib`).
- [ ] 🔄 Scraping assíncrono para maior desempenho.
- [ ] ⚡ Download de recursos estáticos (imagens, CSS, JS).
- [ ] 🧪 Testes automatizados avançados com `requests-mock`.

---

## 🏗 **Estrutura do Projeto**

```
scrapy_html/
│
├── scrapy_html/             # 📦 Código principal
│   ├── __init__.py
│   └── scraper.py           # ⚡ Função principal: get_html_content()
│
├── tests/                   # 🧪 Testes automatizados
│   └── test_scraper.py
│
├── setup.py                 # ⚙️ Configuração para PyPI
├── pyproject.toml           # 📦 Configuração moderna
├── README.md                # 📚 Documentação do projeto
├── LICENSE                  # 📜 Licença MIT
└── MANIFEST.in              # 📋 Inclusão de arquivos extras
```

---

## 🔧 **Contribuindo**

Contribuições são bem-vindas! 🚀  
Para contribuir, siga estas etapas:

1. **Fork** este repositório.
2. Crie uma nova branch:
   ```bash
   git checkout -b minha-nova-funcionalidade
   ```
3. Faça suas alterações e commit:
   ```bash
   git commit -m "✨ Adicionando nova funcionalidade incrível"
   ```
4. Envie para o branch:
   ```bash
   git push origin minha-nova-funcionalidade
   ```
5. **Abra um Pull Request**. 💡

---

## 👨‍💻 **Autor**

Desenvolvido por **[Roberto Lima](https://github.com/robertolima-dev)** 🚀✨

---

## 💬 **Contato**

- 📧 **Email**: robertolima.izphera@gmail.com
- 💼 **LinkedIn**: [Roberto Lima](https://www.linkedin.com/in/roberto-lima-01/)
- 💼 **Website**: [Roberto Lima](https://robertolima-developer.vercel.app/)
- 💼 **Gravatar**: [Roberto Lima](https://gravatar.com/deliciouslyautomaticf57dc92af0)


---

## 📄 Licença
MIT License
