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 / 설치

pip install easyget

easyget is a zero-dependency tool that works with the Python 3.12+ standard library. Or go to Release page and download the latest version.

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

---

Usage / 사용법

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

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

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

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

3. Specify output filename / 파일명 지정

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

4. Resume download / 이어받기

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

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

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

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

easyget urls.csv

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

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

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

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)

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 요청 모드

# 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.

이 프로젝트는 MIT 라이선스를 따릅니다.

---

Contribute / 기여

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

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