====== 파이썬 Requests 라이브러리 사용 가이드 ======
파이썬 Requests 라이브러리는 HTTP 요청을 위한 강력하고 사용자 친화적인 도구입니다. 이 라이브러리는 웹 서비스와 통신하고, API를 활용하며, 웹 스크래핑을 수행하는 데 필수적인 기능을 제공합니다. 표준 라이브러리의 ''urllib''에 비해 훨씬 직관적이고 간결한 API를 제공하여 개발자가 복잡한 HTTP 통신을 쉽게 처리할 수 있도록 돕습니다.

이 문서는 Requests 라이브러리의 설치부터 기본적인 GET/POST 요청, 고급 기능(세션, 인증 등)까지 폭넓게 다룹니다. 각 섹션에서는 실제 코드 예제를 통해 Requests의 다양한 활용법을 설명합니다.

===== 1. Requests 라이브러리 소개 및 설치 =====
파이썬 Requests 라이브러리는 //인간을 위한 HTTP 라이브러리//를 표방하며, 복잡한 HTTP 요청을 단순화하여 개발 생산성을 크게 향상시킵니다.

----
==== 1) 설치 방법 ====
Requests 라이브러리는 Python Package Index (PyPI)를 통해 쉽게 설치할 수 있습니다. 다음 명령어를 사용하여 설치합니다:

<file>
pip install requests
</file>

----
==== 2) 설치 확인 ====
설치가 완료되었는지 확인하려면 파이썬 인터프리터에서 Requests를 임포트해봅니다.

<file>
import requests
print(requests.__version__)
</file>
오류 없이 버전 정보가 출력되면 정상적으로 설치된 것입니다.

===== 2. 기본적인 HTTP 요청 =====
Requests 라이브러리를 사용하여 가장 흔히 사용되는 HTTP 요청 메서드인 GET과 POST를 보내는 방법을 알아봅니다.

----
==== 1) GET 요청 ====
GET 요청은 주로 서버로부터 데이터를 검색하는 데 사용됩니다. ''requests.get()'' 메서드를 사용합니다.

  * **기본 GET 요청**
    - 웹 페이지의 내용을 가져오는 가장 기본적인 방법입니다.
<file>
import requests

response = requests.get('https://www.example.com')
print(response.status_code)
print(response.text)
</file>

  * **쿼리 파라미터 전달**
    - URL에 쿼리 문자열을 추가하여 데이터를 전달할 때 ''params'' 인자를 사용합니다.
<file>
import requests

params = {'key1': 'value1', 'key2': 'value2'}
response = requests.get('https://httpbin.org/get', params=params)
print(response.url)
print(response.json())
</file>

----
==== 2) POST 요청 ====
POST 요청은 주로 서버에 데이터를 제출하거나 생성할 때 사용됩니다. ''requests.post()'' 메서드를 사용합니다.

  * **폼 데이터 전송**
    - HTML 폼과 유사하게 ''data'' 인자를 사용하여 데이터를 전송합니다.
<file>
import requests

data = {'username': 'testuser', 'password': 'password123'}
response = requests.post('https://httpbin.org/post', data=data)
print(response.json())
</file>

  * **JSON 데이터 전송**
    - RESTful API 통신에서 흔히 사용되며, ''json'' 인자를 사용합니다. Requests는 자동으로 ''Content-Type'' 헤더를 ''application/json''으로 설정합니다.
<file>
import requests

json_data = {'title': 'foo', 'body': 'bar', 'userId': 1}
response = requests.post('https://jsonplaceholder.typicode.com/posts', json=json_data)
print(response.status_code)
print(response.json())
</file>

----
==== 3) 응답 객체 다루기 ====
HTTP 요청 후 반환되는 ''Response'' 객체는 다양한 유용한 속성과 메서드를 제공합니다.

  * **주요 속성 및 메서드**
    - 다음 표는 ''Response'' 객체의 주요 항목을 요약한 것입니다.

^ 속성/메서드 ^ 설명 ^ 예시 ^
| ''status_code'' | HTTP 응답 상태 코드 (예: 200, 404) | ''response.status_code'' |
| ''text'' | 응답 내용을 유니코드 텍스트로 반환 | ''response.text'' |
| ''content'' | 응답 내용을 바이트로 반환 | ''response.content'' |
| ''json()'' | 응답 내용을 JSON으로 파싱하여 반환 (오류 발생 시 예외) | ''response.json()'' |
| ''headers'' | 응답 헤더를 딕셔너리 형태로 반환 | ''response.headers'' |
| ''url'' | 요청에 사용된 최종 URL | ''response.url'' |
| ''raise_for_status()'' | 4xx 또는 5xx 클라이언트/서버 오류 발생 시 예외 발생 | ''response.raise_for_status()'' |

----
==== 4) 사용자 정의 헤더 ====
요청에 사용자 정의 HTTP 헤더를 추가하려면 ''headers'' 인자에 딕셔너리 형태로 전달합니다.

<file>
import requests

headers = {
    'User-Agent': 'MyCustomApp/1.0',
    'Accept': 'application/json'
}
response = requests.get('https://httpbin.org/headers', headers=headers)
print(response.json()['headers'])
</file>

----
==== 5) 타임아웃 설정 ====
요청이 너무 오래 걸리는 것을 방지하기 위해 ''timeout'' 인자를 사용하여 초 단위로 타임아웃을 설정할 수 있습니다.

<file>
import requests

try:
    response = requests.get('https://httpbin.org/delay/5', timeout=3)
    print(response.status_code)
except requests.exceptions.Timeout:
    print("요청 시간 초과!")
</file>

===== 3. 고급 Requests 기능 =====
Requests 라이브러리는 단순한 요청 외에도 복잡한 시나리오를 처리할 수 있는 다양한 고급 기능을 제공합니다.

----
==== 1) 세션 사용 ====
''Session'' 객체를 사용하면 여러 요청 간에 쿠키, 헤더, 인증 정보를 유지할 수 있어 효율적입니다. 로그인 세션 유지 등에 유용합니다.

<file>
import requests

with requests.Session() as session:
    # 세션에 로그인 (쿠키가 유지됨)
    login_data = {'username': 'user', 'password': 'password'}
    session.post('https://httpbin.org/post', data=login_data)

    # 로그인 후 다른 페이지 요청 (동일 세션 유지)
    response = session.get('https://httpbin.org/cookies')
    print(response.json())
</file>

----
==== 2) 인증 (Authentication) ====
Requests는 다양한 형태의 HTTP 인증을 지원합니다.

  * **기본 인증 (Basic Authentication)**
    - 사용자 이름과 비밀번호를 직접 전달합니다.
<file>
import requests
from requests.auth import HTTPBasicAuth

response = requests.get('https://httpbin.org/basic-auth/user/pass', auth=HTTPBasicAuth('user', 'pass'))
print(response.status_code)
print(response.text)
</file>

  * **토큰 기반 인증 (Token-based Authentication)**
    - ''headers'' 인자를 사용하여 ''Authorization'' 헤더에 토큰을 포함합니다.
<file>
import requests

token = "YOUR_ACCESS_TOKEN"
headers = {'Authorization': f'Bearer {token}'}
response = requests.get('https://api.example.com/data', headers=headers)
print(response.status_code)
</file>

----
==== 3) 파일 업로드 ====
''files'' 인자를 사용하여 파일을 업로드할 수 있습니다. 바이너리 모드(''rb'')로 파일을 열어야 합니다.

<file>
import requests

# 더미 파일 생성 (예시)
with open('my_file.txt', 'w') as f:
    f.write('This is a test file for upload.')

# 파일 업로드
with open('my_file.txt', 'rb') as f:
    files = {'upload_file': f}
    response = requests.post('https://httpbin.org/post', files=files)
    print(response.status_code)
    print(response.json()['files'])
</file>

----
==== 4) SSL 인증서 검증 ====
기본적으로 Requests는 SSL 인증서의 유효성을 검증합니다. 특정 상황에서 이를 비활성화하거나 사용자 정의 인증서를 사용할 수 있습니다.

  * **SSL 검증 비활성화 (권장하지 않음)**
    - 개발 환경 등 특수한 경우에만 사용하며, 프로덕션 환경에서는 보안 위험이 있습니다.
<file>
import requests
import urllib3

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
response = requests.get('https://self-signed.badssl.com/', verify=False)
print(response.status_code)
</file>

  * **사용자 정의 인증서 사용**
    - 로컬 경로의 CA 번들 파일이나 클라이언트 측 인증서(pem 파일)를 지정할 수 있습니다.
<file>
import requests

# response = requests.get('https://example.com', verify='/path/to/cert.pem')
# print(response.status_code)
print("사용자 정의 인증서 경로는 'verify' 인자에 지정합니다.")
</file>

===== 4. 오류 처리 =====
HTTP 요청 시 발생할 수 있는 다양한 오류를 적절히 처리하는 것은 견고한 애플리케이션을 만드는 데 중요합니다.

----
==== 1) HTTP 상태 코드 확인 ====
응답 객체의 ''status_code'' 속성을 확인하여 성공 여부를 판단할 수 있습니다.

<file>
import requests

response = requests.get('https://httpbin.org/status/404')
if response.status_code == 200:
    print("요청 성공!")
elif response.status_code == 404:
    print("페이지를 찾을 수 없습니다 (404 Not Found).")
else:
    print(f"오류 발생: {response.status_code}")
</file>

----
==== 2) ''raise_for_status()'' 사용 ====
''Response'' 객체의 ''raise_for_status()'' 메서드는 4xx 또는 5xx 상태 코드일 경우 ''HTTPError'' 예외를 발생시킵니다. 이를 통해 간편하게 오류를 처리할 수 있습니다.

<file>
import requests
from requests.exceptions import HTTPError

try:
    response = requests.get('https://httpbin.org/status/500')
    response.raise_for_status() # 4xx 또는 5xx 응답 시 HTTPError 발생
    print("요청 성공!")
except HTTPError as http_err:
    print(f"HTTP 오류 발생: {http_err}")
except Exception as err:
    print(f"기타 오류 발생: {err}")
</file>

----
==== 3) 연결 관련 예외 처리 ====
네트워크 문제, DNS 오류, 타임아웃 등 연결 자체에서 발생하는 예외도 처리해야 합니다.

<file>
import requests
from requests.exceptions import ConnectionError, Timeout, RequestException

try:
    response = requests.get('https://nonexistent-domain-12345.com', timeout=5)
    response.raise_for_status()
except ConnectionError as e:
    print(f"연결 오류 발생: {e}")
except Timeout as e:
    print(f"요청 시간 초과: {e}")
except RequestException as e:
    print(f"예상치 못한 Requests 오류 발생: {e}")
</file>

===== 5. 결론 =====
파이썬 Requests 라이브러리는 강력하고 유연하며 사용하기 쉬운 HTTP 클라이언트입니다. 이 문서를 통해 Requests의 기본적인 사용법부터 세션 관리, 인증, 파일 업로드, 그리고 중요한 오류 처리 방법까지 익혔기를 바랍니다.

Requests는 웹 애플리케이션 개발, API 연동, 데이터 수집 등 //다양한// 파이썬 프로젝트에서 핵심적인 역할을 수행합니다. 공식 문서를 참고하여 더 많은 기능을 탐색하고, 여러분의 프로젝트에 Requests를 적극적으로 활용해보세요.