Metadata-Version: 2.4
Name: easyget
Version: 1.1.0
Summary: Fast, easy-to-use multi-platform file downloader with zero dependencies
Author: easyget
License-Expression: MIT
Project-URL: Repository, https://github.com/gaon12/easyget
Keywords: downloader,wget,curl,http-client,cli,zero-dependency
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# easyget

`easyget` is a wget/curl-compatible command-line downloader written in Python.  
It supports modern features like multithreading, speed limits, resume support, wildcard URL expansion, and progress bars — all in a user-friendly bilingual (English + Korean) interface.

`easyget`는 Python으로 작성된 wget/curl 호환 명령줄 다운로드 도구입니다.  
멀티스레드, 속도 제한, 이어받기, 와일드카드 URL 확장, 진행률 표시 등 현대적인 기능을 지원하며, 영어와 한국어로 모두 친절하게 안내합니다.

`easyget` philosophy: **Easy for human, optimized for AI**.  
`easyget` 철학: **사람에게는 쉽고, AI에는 토큰 효율적으로 최적화**.

---

## Features / 특징

- ✅ **wget/curl-style options** (`-O`, `-c`, `--limit-rate`)
- ✅ **Multithreaded downloads** (default 4 threads)
- ✅ **Speed limits** (e.g., `--max-speed 1M`)
- ✅ **Resume support** (`--resume` or `-c`)
- ✅ **Wildcard (*) expansion in URLs** (parsing directory listings)
- ✅ **Input from txt, csv, tsv files**
- ✅ **Progress bars** (total file count and individual download progress)
- ✅ **Ignore cache** (`--no-cache`, ignore `.part` files)
- ✅ **Basic auth / Bearer token support**
- ✅ **Python HTTP client API (sync + async)** for `requests`/`aiohttp`-style migration (the async API offloads the shared sync engine onto worker threads — still zero-dependency)
- ✅ **AI-optimized structured outputs** (`--ai`) and structured diagnostics for automation/agents
- ✅ **Download modes** (`--mode fast` or `accurate`)
  - `fast` (default): minimizes metadata probes and downloads immediately in common single-file cases
  - `accurate`: probes metadata (HEAD/Range) to improve size/range detection and multithread decisions
- ✅ **English/Korean comments and docs**

- ✅ **wget/curl 스타일 옵션 지원** (`-O`, `-c`, `--limit-rate`)
- ✅ **멀티스레드 다운로드** (기본 4개 스레드)
- ✅ **속도 제한** (e.g., `--max-speed 1M`)
- ✅ **이어받기 지원** (`--resume` 또는 `-c`)
- ✅ **URL 내 와일드카드(*) 확장 지원** (디렉토리 리스트 파싱)
- ✅ **txt, csv, tsv 파일 입력 지원**
- ✅ **진행률 표시** (총 파일 수 및 개별 파일 다운로드)
- ✅ **캐시 무시 기능** (`--no-cache`, `.part` 파일 무시)
- ✅ **기본 인증 / Bearer 토큰 지원**
- ✅ **Python HTTP 클라이언트 API (동기 + 비동기)** (`requests`/`aiohttp` 마이그레이션 용도. 비동기 API는 동기 엔진을 워커 스레드로 오프로드하며 무의존성 유지)
- ✅ **AI 최적화 구조화 출력** (`--ai`) 및 구조화 진단 정보
- ✅ **다운로드 모드** (`--mode fast` 또는 `accurate`)
  - `fast` (기본값): 일반적인 단일 파일 다운로드에서 메타데이터 조회를 최소화하고 즉시 다운로드
  - `accurate`: HEAD/Range 기반 메타데이터를 조회해 크기/Range/멀티스레드 판단 정확도를 높임
- ✅ **영어/한글 주석 및 문서**

---

## Installation / 설치

```bash
pip install easyget
```

`easyget` is a zero-dependency tool that works with the Python 3.12+ standard library. Or go to [Release page](https://github.com/gaon12/easyget/releases/latest) and download the latest version.

`easyget`은 Python 3.12+ 표준 라이브러리만 사용하는 무의존성(zero-dependency) 도구입니다. 또는 [릴리즈 페이지](https://github.com/gaon12/easyget/releases/latest)에서 최신 버전을 다운로드하세요.

---

## Usage / 사용법

### 1. Single file download / 단일 파일 다운로드

```bash
easyget "https://example.com/file.zip"
# or
python -m easyget "https://example.com/file.zip"
```

### 2. Specify mode / 모드 지정 (fast or accurate)

```bash
easyget --mode accurate "https://example.com/file.zip"
```

### 3. Specify output filename / 파일명 지정

```bash
easyget "https://example.com/file.zip" -O myfile.zip
```

### 4. Resume download / 이어받기

```bash
easyget "https://example.com/file.zip" -c
```

### 5. Multi-threaded with speed limit / 멀티스레드 + 속도 제한

```bash
easyget "https://example.com/large.iso" --mode accurate --multi 8 --max-speed 2M
```

### 6. Use input file list (txt, csv, tsv) / URL 리스트로 다운로드

```bash
easyget urls.csv
```

### 7. Wildcard in URL / 와일드카드 URL 사용

```bash
easyget "https://example.com/files/*.zip"
```

### 8. Python API (sync + async) / 파이썬 API (동기 + 비동기)

```python
import easyget

# Sync (requests-like)
resp = easyget.get("https://httpbin.org/get", params={"q": "easyget"})
resp.raise_for_status()
print(resp.status_code, resp.json())

# auth + cookies
secure = easyget.get(
    "https://httpbin.org/headers",
    auth=("user", "pass"),
    cookies={"sid": "abc"},
)
print(secure.status_code)

# Multipart upload
upload = easyget.post(
    "https://httpbin.org/post",
    data={"name": "demo"},
    files={"file": ("hello.txt", b"hello world", "text/plain")},
)
print(upload.status_code)
```

```python
import asyncio
import easyget


async def main():
    async with easyget.AsyncSession() as session:
        # aiohttp-like: async with session.get(...)
        async with session.get("https://httpbin.org/get") as resp:
            data = await resp.json()
            print(resp.status, data)


asyncio.run(main())
```

### 9. curl-style HTTP request mode / curl 스타일 HTTP 요청 모드

```bash
# POST JSON request
easyget -X POST --json-data '{"name":"easyget"}' -i -L https://httpbin.org/post

# HEAD request
easyget -I https://example.com

# TLS/proxy + compressed response
easyget -X GET --proxy http://proxy.local:8080 --cacert ./ca.pem --compressed https://example.com/api

# Multipart form upload
easyget -X POST -F "name=demo" -F "file=@./hello.txt;type=text/plain" https://httpbin.org/post

# AI-optimized compact payload
easyget --ai -X GET --output-select status https://example.com/api
```

---

## Input File Format / 입력 파일 형식

### txt

```
https://example.com/file1.zip
https://example.com/file2.zip
```

### csv or tsv

| url                         | filename         |
|----------------------------|------------------|
| https://example.com/a.pdf  | lecture_a.pdf    |
| https://example.com/b.pdf  | lecture_b.pdf    |

---

## Advanced Options / 고급 옵션

| Option                   | Description / 설명 |
|--------------------------|---------------------|
| `--output`, `-o`, `-O`   | Output file name (단일 파일 다운로드 시) |
| `--resume`, `-c`         | Resume download (이어받기) |
| `--multi`                | Number of threads (스레드 수) |
| `--max-speed`            | Download speed limit (e.g., 1M, 500K) |
| `--no-cache`             | Ignore .part cache and force redownload |
| `--header`               | Custom HTTP headers (e.g., `"Key: Value"`) |
| `--user-agent`           | User-Agent 설정 |
| `--username`, `--password` | Basic 인증용 계정 정보 |
| `--token`                | Bearer 토큰 인증 |
| `--mode`                 | Download mode: `fast` or `accurate` |
| `-f`, `--force`          | Overwrite existing files without prompting |
| `-s`, `--skip-existing`  | Skip files that already exist |
| `-P`, `--output-dir`     | Directory to save downloaded files |
| `-q`, `--quiet`          | Quiet mode (no output) |
| `-v`, `--verbose`        | Display debug logs |
| `--continue`, `--retry`, `--retry-delay`, `--retry-max-delay`, `--retry-backoff`, `--timestamping` | wget-style advanced download controls |
| `-X`, `-d`, `--json-data`, `--data-urlencode` | HTTP request mode body/method options |
| `-F`, `-I`, `-L`, `--fail`, `-i` | curl-style request mode controls |
| `--output-select`        | request mode response selection (`all/status/headers/body`) |
| `--proxy`, `--cacert`, `-k`, `--cert`, `--key`, `--compressed` | request mode transport/TLS controls |
| `--timeout`              | HTTP timeout in seconds for request mode (기본값: 30) |
| `--json`, `--ai`         | machine output mode / AI compact output mode |
| `--data-binary`          | Raw request body; `@path` reads from a file (request mode) |
| `-V`, `--version`        | Print version and exit (버전 출력) |

---

## Notes / 주의사항

- When a download is interrupted, a `.part` file is created. Multithreaded downloads also keep a `.part.meta` sidecar tracking completed byte ranges, so `-c` resumes only the missing segments instead of restarting — and a half-written `.part` can never be mistaken for a finished file.
- Use `--no-cache` to ignore existing `.part` files and redownload.
- Wildcard URLs are based on `href="..."` format in HTML directory listings.
- Downloads always follow redirects; `-L` only controls redirect handling in request mode.
- Progress bars are written to stderr, so stdout stays clean for `--json` and shell pipes.
- URLs without a filename (e.g., `https://host/dir/`) are saved as `index.html`, matching wget.
- Server-provided filenames are sanitized to a safe basename.

- 다운로드가 중단되면 `.part` 파일이 생성됩니다. 멀티스레드 다운로드는 완료된 바이트 범위를 기록하는 `.part.meta` 파일도 함께 유지하므로, `-c` 이어받기가 남은 세그먼트만 다시 받습니다. 덜 쓰인 `.part`가 완성 파일로 오인되는 일도 없습니다.
- `--no-cache` 옵션을 사용하면 기존 `.part` 파일을 무시하고 새로 다운로드합니다.
- 와일드카드 URL은 HTML 디렉토리 리스트에서 `href="..."` 형식을 기반으로 파일을 찾습니다.
- 다운로드는 항상 리다이렉트를 따르며, `-L`은 요청 모드에서만 리다이렉트 처리를 제어합니다.
- 진행률 표시는 stderr로 출력되므로 `--json` 출력과 셸 파이프가 깨끗하게 유지됩니다.
- 파일명이 없는 URL(예: `https://host/dir/`)은 wget과 마찬가지로 `index.html`로 저장됩니다.
- 서버가 보낸 파일명은 안전한 basename으로 정제됩니다.

---

## License

This project is licensed under the [MIT License](./LICENSE).

이 프로젝트는 [MIT 라이선스](./LICENSE)를 따릅니다.

---

## Contribute / 기여

For questions or improvements, feel free to open an issue or pull request!

기여하고 싶거나 궁금한 점이 있으면 언제든 이슈나 PR을 열어주세요!
