requests 라이브러리 공식문서(번역)

2020. 12. 16. 20:47

requests 라이브러리 공식문서를 번역한 내용입니다.
영어실력이 빈약하므로 잘못된 내용에 대한 피드백 환영합니다!!!

참고:https://2.python-requests.org/en/master/user/quickstart/

----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Make a Request

requests 모듈을 가져오는 것부터 시작합니다.

import requests

github api에 get요청을 보내기

r = requests.get('https://api.github.com/events')

위의 코드로 r이라는 Response객체를 얻었다.
이 객체로부터 필요한 정보를 얻을 수 있다.
Reponse의 간단한 API는 모든 형태의 HTTP요청이 확실하다는 것을 의미한다.
아래 코드는 HTTP POST객체를 만드는 방법이다.

r = requests.post('https://httpbin.org/post', data = {'key':'value'})

API는 모든 형태의 HTTP 요청의 의미를 분명하게 한다.
다른 유형의 HTTP requests(put, delete, head, option)는? 간단하다.

r = requests.put('https://httpbin.org/put', data = {'key':'value'})
r = requests.delete('https://httpbin.org/delete')
r = requests.head('https://httpbin.org/get')
r = requests.options('https://httpbin.org/get')

이는 requests가 할 수 있는일의 일부분일 뿐이다.

Passing Parameters in URLs (URL에 매개변수 전달하기)

종종 URL의 쿼리 문자열에서 어떤 종류의 데이터를 보내고 싶어한다.
직접 URL을 구성하는 경우 이 데이터는 http 전달할 데이터는 물음표 뒤에 URL의 키/값 쌍으로 제공된다.ex)(httpbin.org/get?key=val)
요청은 이러한 인수를 매개 변수 키워드 인수를 사용하여 문자열 사전으로 제공할 수 있도록 한다.
requests을 사용하면 "params"키워드 인수를 사용하여 문자열 dict로 이러한 인수를 제공할 수 있습니다.
예를 들어 get로 key1=value1,key2=value2를 httpbin.org/get에 전달하려면 아래의 코드를 사용하십시오.

payload = {'key1': 'value1', 'key2': 'value2'}
r = requests.get('https://httpbin.org/get', params=payload)

url을 출력하면 url이 올바르게 인코딩되었음을 확인할 수 있다.

print(r.url)
#https://httpbin.org/get?key2=value2&key1=value1

value가 None인 Key는 url의 쿼리 문자열에 추가되지 않습니다.
또한 값으로 list도 전달할 수 있습니다.

payload = {'key1': 'value1', 'key2': ['value2', 'value3']}

r = requests.get('https://httpbin.org/get', params=payload)
print(r.url)
#https://httpbin.org/get?key1=value1&key2=value2&key2=value3

Response Content(응답 내용)

우리는 서버의 Response content(응답 내용)을 읽을 수 있다.
다시 github 타임라인을 보자

import requests

r = requests.get('https://api.github.com/events')
r.text
#'[{"repository":{"open_issues":0,"url":"https://github.com/...

Requests는 서버의 content를 자동적으로 디코딩한다.
대부분의 Unicode 문자들은 매끄럽게 디코딩됩니다.

Requests할 때, Requests는 http 헤더를 보고 response의 인코딩에 대해 추측할 수 있다.
reponse으로 추측할 수 있는 텍스트 인코딩은 r.text에 접근할 때 사용된다.
r.encoding 속성을 사용하여 요청에서 사용 중인 인코딩을 확인하고 변경할 수 있습니다.

r.encoding
'utf-8'
r.encoding = 'ISO-8859-1'

인코딩을 변경하면 requests는 r.text를 호출할 때마다 변경된 r.encoding의 값을 사용한다.
특수한 로직을 적용하여 content의 인코딩을 결정할 수 있는 상황에서 이 작업을 할 수 있습니다.
예를 들어 HTML과 XML은 본문에 인코딩을 지정할 수 있습니다.
이런 상황에서는 user.content를 사용하여 인코딩을 찾은 후 r.encoding를 설정해야 합니다.
이렇게 하면 올바른 인코딩의 user.text를 사용할 수 있습니다.

당신만의 인코딩을 만들어 코뎅 모듈에 등록했다면, 코덱 이름을 r.encoding의 값으로 사용할 수 있으며 Requests는 디코딩을 처리합니다.

Binary Response Content(이진 응답 내용)

텍스트가 아닌 requests의 reponse body에 바이트로 접근할 수 있습니다.

r.content
#b'[{"repository":{"open_issues":0,"url":"https://github.com/...

gzip와 deflate 전송-인코딩은 자동으로 디코딩 됩니다.
예를 들어, requests에 의해 반환된 이진 데이터에서 이미지를 생성하려면 다음 코드를 사용할 수 있습니다.

from PIL import Image
from io import BytesIO

i = Image.open(BytesIO(r.content))

JSON Response Content(JSON 응답 내용)

또한 JSON 데이터를 처리 할 때, JSON 디코더가 내장되어 있습니다.

import requests

r = requests.get('https://api.github.com/events')
r.json()[{'repository': {'open_issues': 0, 'url': 'https://github.com/...

JSON 디코딩이 실패 했을 경우에는, r.json()은 예외 처리를 합니다.
예를 들어, reponse에 204(No content)가 표시되거나 reponse에 잘못된 json이 포함된 경우
r.json()을 raises하려 하면 ValueError: No JSON object could be decoded 문구가 나옵니다.

Raw Response Content(저수준 응답 내용)

드물게 서버에서 저수준 소켓응답을 받고자 하는 경우 r.raw에 접근할 수 있다.
이렇게 하려면 초기 request에서 stream=True를 설정해야합니다.

r = requests.get('https://api.github.com/events', stream=True)
r.raw
#<urllib3.response.HTTPResponse object at 0x101194810>

#r.raw.read(10)
#'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03'

그러나 일반적으로 아래와 같은 패턴을 사용하여 스트리밍되는 내용을 파일로 저장해야 합니다.

with open(filename, 'wb') as fd:
    for chunk in r.iter_content(chunk_size=128):
        fd.write(chunk)

Response.iter_content를 사용하면 Response.raw를 직접 사용할 때 처리해야 할 많은 작업이 자동적으로 처리됩니다.
다운로드를 스트리밍할 때, 위의 방법이 선호되고 권장되는 content를 검색하는 방법입니다.

경우에 따라 chunk_size는 더 적합한 숫자로 자유롭게 조정할 수 있습니다 *

참고
Response.iter_content vs Response.raw 참고사항
Response.iter_content는 자동으로 gzip을 디코딩하고 전송 인코딩을 transfer-encodings(감압)합니다.
Response.raw는 바이트의 raw stream이며, 응답 내용을 변환하지 않습니다.
반환된 바이트에 액세스해야 하는 경우 Response.raw를 사용하십시오.

Custom Headers(사용자 지정 헤더)

requests에 HTTP headers를 추가하려면, dict자료형을 이용해 headers 매개변수에 전달 하십시오.

예를 들어, 이전 예시에서는 user-agent를 지정하지 않았습니다.

url = 'https://api.github.com/some/endpoint'
headers = {'user-agent': 'my-app/0.0.1'}
r = requests.get(url, headers=headers)

참고 : Custom Headers(사용자 지정 헤더)는 구체적인 정보 소스보다 낮은 우선순위가 부여됩니다.
예를 들어

자격 증명이 .netrc에 지정된 경우 header로 설정된 권한 부여 headers가 재정의 되며, 이는 다시 auth=parameter에 의해 재정의 됩니다.
requests는 ~/.netrc, ~/_netrc 또는 NETRC 환경 변수에 의해 지정된 경로에서 netrc 파일을 검색합니다.
Off-host(오프호스트)로 리디렉션되는 경우 권한 부여 헤더가 제거됨
Proxy-Authorization headers(프록시-인증 헤더)는 URL에 제공된 proxy credentials에 의해 재정의됩니다.
내용의 길이를 결정할 수 있는 경우 content-Length headers가 재정의 됩니다.

또한 requests는 지정된 사용자 정의 헤더를 기준으로 동작을 전혀 변경하지 않습니다.
헤더는 최종 요청으로 전달됩니다.

참고:
모든 header의 값은 문자열,bytestring 또는 Unicode이어야 합니다.
Unicode header 값을 전달하는것이 허용되더라도,전달하지 않는 것을 권고합니다.

POST a Multipart-Encoded File(다중 부분 인코딩 파일 발송)

Requests로 Multipart-Encoded file을 쉽게 업로드할 수 있습니다:

url = 'https://httpbin.org/post'
files = {'file': open('report.xls', 'rb')}
r = requests.post(url, files=files)
r.text
#{
#  ...
#  "files": {
#    "file": "<censored...binary...data>"
#  },
#  ...
#}

당신은 파일이름, content-type, header를 명시적으로 설정할 수 있다:

url = 'https://httpbin.org/post'
files = {'file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel', {'Expires': '0'})}
r = requests.post(url, files=files)
r.text
#{
#  ...
#  "files": {
#    "file": "<censored...binary...data>"
#  },
#  ...
#}

원한다면, 수신할 문자열을 파일로 보낼 수 있습니다:

url = 'https://httpbin.org/post'
files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')}
r = requests.post(url, files=files)
r.text
#{
#  ...
#  "files": {
#    "file": "some,data,to,send\\nanother,row,to,send\\n"
#  },
#  ...
#}

multipart/form-data requests로 대용량 파일을 발송하는 경우, requests을 stream할 수 있습니다.
기본적으로 requests는 이 기능을 지원하지 않지만, requests-toolbelt를 사용하는 별도의 패키지가 있습니다.
requests-toolbelt 사용 방법에 대한 자세한 내용은 (https://toolbelt.readthedocs.io/)->->) 공식문서를 참고하십시오.

주의:
binary-mode에서 파일을 여는 것을 강력하게 권고한다.
Requests이 사용자를 위해 Content-Length header을 제공하려 할 수 있으며, 그렇게 되면 이 값은 파일의 바이트 수로 설정 되기 때문입니다.
파일을 text mode로 열면 오류가 발생할 수 있습니다.

Response Status Codes(응답 상태 코드)

Reponse status Code(응답 상태 코드) 확인하기:

r = requests.get('https://httpbin.org/get')
r.status_code
#200

또한 Requests에는 쉽게 참조할 수 있도록 내장된 status code(상태 코드) 조회 object가 함께 제공됩니다.

r.status_code == requests.codes.ok
True

잘못된 request(4XX 클라이언트 오류 또는 5XX 서버 오류 응답)을 한 경우,Response.raise_for_status()로 requests를 올리 수 있다.

bad_r = requests.get('https://httpbin.org/status/404')
bad_r.status_code
#404

bad_r.raise_for_status()
#Traceback (most recent call last):
#  File "requests/models.py", line 832, in raise_for_status
#    raise http_error
#requests.exceptions.HTTPError: 404 Client Error

그러나 r에 대한 status_code가 200이었으므로 rise_for_status()호출하면 다음과 같은 결과가 나타납니다.

r.raise_for_status()None

모두 잘된다.

Response Headers(응답 헤더)

python dictionary를 사용하여 reponse headers을 볼 수 있습니다.

>>> r.headers
{
    'content-encoding': 'gzip',
    'transfer-encoding': 'chunked',
    'connection': 'close',
    'server': 'nginx/1.0.4',
    'x-runtime': '148ms',
    'etag': '"e1ca502697e5c9317743dc078f67693f"',
    'content-type': 'application/json'
}

???dict는 특별하지만 HTTP 헤더용으로만 만들어 졌습니다???
"RFC 7230"에 따르면, HTTP header names는 대소문자를 구분하지 않습니다.
따라서, 대소문자 상관없이 headers에 접근할 수 있습니다.

r.headers['Content-Type']
#'application/json'

r.headers.get('content-type')
#'application/json'

또한 서버가 다른 값을 가진 동일한 headers를 여러 번 전송할 수 있었지만, requests은 RFC 7230에 따라 단일 매핑 내에서 해당 header를 dict에 나타낼 수 있도록 결합합니다.

수신자는 쉼표로 구분된 조합된 필드 값에 각 후속 필드 값을 순서대로 추가하여 메시지의 의미를 변경하지 않고 동일한 필드 이름을 가진 여러 헤더 필드를 하나의 "필드 이름: 필드 값" 쌍으로 결합할 수 있습니다.
=> dict자료형을 사용하여 header에 다른값을 계속 전송하면 => values에 계속 쌓아간다는듯 합니다.

Cookies(쿠키)

reponse에 일부 Cookies가 포함된 경우 다음과 같이 빠르게 접근할 수 있습니다.

>>> url = 'http://example.com/some/cookie/setting/url'
>>> r = requests.get(url)
>>> r.cookies['example_cookie_name']
'example_cookie_value'

너의 cookies를 서버로 보내려면 cookies parameter(쿠키 매개변수)를 사용합니다.

url = 'https://httpbin.org/cookies'
cookies = dict(cookies_are='working')
r = requests.get(url, cookies=cookies)
r.text
#'{"cookies": {"cookies_are": "working"}}'

쿠키는 RequestsCookieJar로 반환되며,이는 dict와 같은 역할을 하지만 여러 도메인 또는 경로에 걸쳐 사용하기에 적합한 보다 완벽한 인터페이스를 제공합니다.
RequestsCookieJar은 requests에도 전달될 수 있습니다.

jar = requests.cookies.RequestsCookieJar()
jar.set('tasty_cookie', 'yum', domain='httpbin.org', path='/cookies')
jar.set('gross_cookie', 'blech', domain='httpbin.org', path='/elsewhere')
url = 'https://httpbin.org/cookies'
r = requests.get(url, cookies=jar)
r.text
#'{"cookies": {"tasty_cookie": "yum"}}'

Redirection and History

기본적으로 requests는 HEAD를 제외한 모든 verbs에 대해 위치 redirection을 수행한다.
response object의 history 속성을 사용하여 Redirection을 추적할 수 있습니다.
Response.history list는 request를 완료하기위해 생성된 개체인 reponse를 포함합니다.
이 list는 생성일자 기준 내림차순으로 정렬됩니다.

예를 들어 GitHub는 모든 HTTP requests를 HTTPS로 Redirect(리디렉션)합니다:

r = requests.get('http://github.com/')
r.url
#'https://github.com/'

r.status_code
#200

r.history
#[<Response [301]>]

GET, OPTIONS, POST, PUT, Patch 또는 Delete를 사용하는 경우 allow_redirects 매개 변수를 사용하여 Redirect(리디렉션) 처리를 비활성화할 수 있습니다:

r = requests.get('http://github.com/', allow_redirects=False)
r.status_code
#301

r.history
#[]

HEAD를 사용하는 경우, Redirect(리디렉션)을 활성화하십시오:

r = requests.head('http://github.com/', allow_redirects=True)
r.url
#'https://github.com/'

r.history
#[<Response [301]>]

Timeouts

timeout parameter(매개변수)를 사용하여 지정된 시간(초) 후에 requests에서 reponse의 대기 중을 중지하도록 지정할 수 있습니다. => reponse객체를 지정된 시간후에 받는다는 뜻으로 이해했음
거의 모든 production code가 거의 모든 requests에 이 parameter(매개변수)를 사용해야 합니다.
그렇지 않으면 프로그램이 무기한 중단될 수 있습니다:

requests.get('https://github.com/', timeout=0.001)
#Traceback (most recent call last):
#  File "<stdin>", line 1, in <module>
#requests.exceptions.Timeout: HTTPConnectionPool(host='github.com', port=80): Request timed out. (timeout=0.001)

참고:
timeout은 전체 response 다운로드에 대한 시간 제한이 아니며, 서버가 timeout초 동안 response를 발행하지 않은 경우(더 정확히 말하면, timeout초 동안 기본 소켓에 바이트가 수신되지 않은 경우) response가 발생합니다.
명시적으로 지정된 timeout가 없으면 requests는 timeout되지 않습니다.

Error or exceptions(오류 혹은 예외)

네트워크 문제(예: DNS 오류, 연결 거부 등)가 발생할 경우, requests에서 ConnectionError exception(연결 오류 예외)가 발생합니다.

HTTP 요청이 실패 상태 코드를 반환한 경우 Response.raise_for_status()가 HTTPError를 발생시킵니다.

request가 시간 초과되면 timeout 예외가 발생합니다.

request이 구성된 최대 리디렉션 수를 초과하면 TooManyRedirects 예외가 발생합니다.

request에서 명시적으로 발생하는 모든 예외는 요청에서 상속됩니다.예외 사항예외 요청.

Requests가 명시적으로 requests.exceptions.RequestException.로부터 상속을 올리는 모든 예외

requests 라이브러리 공식문서를 번역한 내용이다.
영어실력이 빈약하므로 잘못된 내용에 대한 피드백 환영합니다!!!

참고:https://2.python-requests.org/en/master/user/quickstart/

저작자표시

lks의 코딩일기