glimcrawl 0.1.2
A powerful Google image crawler that supports batch downloading, image processing, and proxy settings
License: MIT
Requires Python: >=3.8
Keywords: crawler, download, google, image, process

# GlimCrawl

[![PyPI version](https://img.shields.io/pypi/v/glimcrawl.svg)](https://pypi.org/project/glimcrawl/)
[![Python Version](https://img.shields.io/pypi/pyversions/glimcrawl.svg)](https://pypi.org/project/glimcrawl/)
[![License](https://img.shields.io/pypi/l/glimcrawl.svg)](https://gitee.com/duckweeds7/glimcrawl/blob/master/LICENSE)

[English](README.en.md) | 简体中文

一个强大的 Google 图片爬虫工具，支持批量下载、图片处理和代理设置。名称来源：glimpse（一瞥）+ crawl（爬行），强调"快速捕捉网络图片片段"。

## ✨ 特性

- 🚀 异步并发下载，提高效率
- 🎨 自动图片处理和优化（去水印、调整大小等）
- 🌐 支持代理设置，解决网络问题
- 📏 支持图片尺寸和时间筛选
- 🖥️ 命令行界面，易于使用
- 📦 支持作为 Python 库导入使用
- 🔒 安全可靠，遵循 Google 搜索规范
- 📁 灵活的目录管理（支持关键词子目录、目录存在处理等）

## 📦 安装

```bash
# 从 PyPI 安装（推荐）
pip install glimcrawl

# 安装 Playwright 浏览器（必需）
playwright install chromium
```

## 🚀 快速开始

### 命令行使用

```bash
# 基本使用
glimcrawl download "猫咪"

# 指定下载数量和保存目录
glimcrawl download "猫咪" -l 50 -d ./images

# 使用代理
glimcrawl download "猫咪" -p http://127.0.0.1:1080

# 筛选大图和最近图片
glimcrawl download "猫咪" -s l -t w

# 禁用关键词子目录
glimcrawl download "猫咪" --no-keyword-dir

# 目录已存在时跳过创建
glimcrawl download "猫咪" -e skip

# 以JSON格式输出结果
glimcrawl download "猫咪" -j
```

### Python 库使用

```python
import asyncio
from glimcrawl import GoogleImageCrawler
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        crawler = GoogleImageCrawler(browser)
        
        # 下载图片并获取结果
        result = await crawler.crawl_images(
            keyword="猫咪",
            max_images=20,
            save_dir="images",
            use_keyword_dir=True,
            if_exists="rename",
            size="l",  # 大图
            date="w"   # 一周内
        )
        
        # 打印下载结果
        print(result)
        
        # 获取下载的文件路径
        print("\n下载的文件:")
        for path in result.file_paths:
            print(f"- {path}")
            
        # 获取统计信息
        print(f"\n下载统计:")
        print(f"- 总图片数: {result.total_images}")
        print(f"- 成功下载: {result.success_count}")
        print(f"- 下载失败: {result.failed_count}")
        print(f"- 成功率: {result.success_rate:.1f}%")
        print(f"- 耗时: {result.duration:.1f}秒")
        
        await browser.close()

asyncio.run(main())
```

## 📝 参数说明

### 命令行参数

| 参数 | 说明 | 默认值 | 示例 |
|------|------|--------|------|
| `keyword` | 搜索关键词（必需） | - | `"猫咪"` |
| `-l, --limit` | 最大下载数量 | 100 | `-l 50` |
| `-d, --save-dir` | 保存目录 | images | `-d ./images` |
| `--use-keyword-dir/--no-keyword-dir` | 是否使用关键词创建子目录 | True | `--no-keyword-dir` |
| `-e, --if-exists` | 目录已存在时的处理方式 | rename | `-e skip` |
| `-p, --proxy` | 代理服务器 | None | `-p http://127.0.0.1:1080` |
| `-s, --size` | 图片尺寸 | None | `-s l` (大图) |
| `-t, --date` | 时间范围 | None | `-t w` (一周内) |

### 图片尺寸选项

- `l`: 大图
- `m`: 中图
- `i`: 图标

### 时间范围选项

- `d`: 24小时内
- `w`: 一周内
- `m`: 一月内
- `y`: 一年内

## 🛠️ 图片处理

下载的图片会自动进行以下处理：

1. 格式转换：统一转为 JPG 格式
2. 尺寸调整：最大 1920x1080，保持比例
3. 质量优化：85% 压缩率
4. 文件命名：使用 MD5 哈希，避免重复
5. 去水印：自动识别和移除水印（实验性功能）

## 🔒 安全建议

1. 使用代理时建议配置 HTTPS 代理
2. 遵循目标网站的爬虫规范
3. 合理设置下载间隔和并发数
4. 图片仅供学习研究使用

## 🤝 贡献

1. Fork 本仓库
2. 创建新分支: `git checkout -b feat/new-feature`
3. 提交更改: `git commit -am 'feat: add new feature'`
4. 推送分支: `git push origin feat/new-feature`
5. 提交 Pull Request

## 📄 许可证

[MIT License](LICENSE) © 2025 Duckweeds7

## 📋 更新日志

### v0.1.1 (2025-04-20)
- ✨ 新增目录管理功能
  - 支持使用关键词创建子目录
  - 支持目录已存在时的处理策略（跳过/覆盖/重命名）
  - 优化目录创建和文件保存逻辑
- 🐛 修复已知问题
  - 修复目录已存在时的处理逻辑
  - 优化文件命名和保存机制
- 📝 更新文档
  - 添加新功能使用说明
  - 完善参数说明
  - 更新示例代码

### v0.1.0 (2025-04-19)
- 🎉 首次发布
  - 支持基本的图片下载功能
  - 支持图片处理和优化
  - 支持代理设置
  - 支持命令行界面