"urllib.request" --- Extensible library for opening URLs
********************************************************

**소스 코드:** Lib/urllib/request.py

======================================================================

"urllib.request" 모듈은 복잡한 세계에서 URL(대부분 HTTP)을 여는 데 도
움이 되는 함수와 클래스를 정의합니다 --- 기본(basic)과 다이제스트 인증
, 리디렉션, 쿠키 등.

더 보기: 더 고수준 HTTP 클라이언트 인터페이스로 Requests 패키지를 권장합니다.

"urllib.request" 모듈은 다음 함수를 정의합니다:

urllib.request.urlopen(url, data=None[, timeout], *, cafile=None, capath=None, cadefault=False, context=None)

   Open the URL *url*, which can be either a string or a "Request"
   object.

   *data*는 서버로 전송할 추가 데이터를 지정하는 객체이거나, 그러한 데
   이터가 필요하지 않으면 "None"이어야 합니다. 자세한 내용은 "Request"
   를 참조하십시오.

   urllib.request 모듈은 HTTP/1.1을 사용하고 HTTP 요청에
   "Connection:close" 헤더를 포함합니다.

   선택적 *timeout* 매개 변수는 연결 시도와 같은 연산을 블로킹하기 위
   한 시간제한을 초 단위로 지정합니다 (지정하지 않으면 전역 기본 시간
   제한 설정이 사용됩니다). 이것은 실제로는 HTTP, HTTPS 및 FTP 연결에
   서만 작동합니다.

   *context*가 지정되면, 다양한 SSL 옵션을 기술하는 "ssl.SSLContext"
   인스턴스이어야 합니다. 자세한 내용은 "HTTPSConnection"을 참조하십시
   오.

   The optional *cafile* and *capath* parameters specify a set of
   trusted CA certificates for HTTPS requests.  *cafile* should point
   to a single file containing a bundle of CA certificates, whereas
   *capath* should point to a directory of hashed certificate files.
   More information can be found in
   "ssl.SSLContext.load_verify_locations()".

   The *cadefault* parameter is ignored.

   이 함수는 항상 *컨텍스트 관리자*로 작동할 수 있고 *url*, *headers*
   및 *status* 프로퍼티를 가진 객체를 반환합니다. 이러한 프로퍼티에 대
   한 자세한 내용은 "urllib.response.addinfourl"을 참조하십시오.

   HTTP 및 HTTPS URL의 경우, 이 함수는 약간 수정된
   "http.client.HTTPResponse" 객체를 반환합니다. 위의 세 가지 새로운
   메서드 외에도, msg 어트리뷰트에는 "HTTPResponse" 설명서에 지정된 대
   로 응답 헤더 대신 "reason" 어트리뷰트와 --- 서버가 반환한 이유 문구
   --- 같은 정보가 포함됩니다.

   FTP, 파일 및 데이터 URL과 레거시 "URLopener"와 "FancyURLopener" 클
   래스에서 명시적으로 처리된 요청의 경우, 이 함수는
   "urllib.response.addinfourl" 객체를 반환합니다.

   프로토콜 에러 시 "URLError"를 발생시킵니다.

   아무런 처리기도 요청을 처리하지 않으면 "None"이 반환될 수 있습니다
   (기본 설치된 전역 "OpenerDirector"는 "UnknownHandler"를 사용하여 이
   러한 상황이 발생하지 않도록 합니다).

   In addition, if proxy settings are detected (for example, when a
   "*_proxy" environment variable like "http_proxy" is set),
   "ProxyHandler" is default installed and makes sure the requests are
   handled through the proxy.

   파이썬 2.6 및 이전 버전의 레거시 "urllib.urlopen" 함수는 중단되었습
   니다; "urllib.request.urlopen()"는 이전 "urllib2.urlopen"에 해당합
   니다. 딕셔너리 매개 변수를 "urllib.urlopen"에 전달하여 수행되었던
   프락시 처리는 "ProxyHandler" 객체를 사용하여 얻을 수 있습니다.

   기본 오프너는 요청 객체에서 취한 인자 "fullurl", "data", "headers",
   "method"로 감사 이벤트 "urllib.Request"를 발생시킵니다.

   버전 3.2에서 변경: *cafile*과 *capath*가 추가되었습니다.

   버전 3.2에서 변경: HTTPS virtual hosts are now supported if
   possible (that is, if "ssl.HAS_SNI" is true).

   버전 3.2에 추가: *data*는 이터러블 객체일 수 있습니다.

   버전 3.3에서 변경: *cadefault*가 추가되었습니다.

   버전 3.4.3에서 변경: *context*가 추가되었습니다.

   버전 3.10에서 변경: HTTPS connection now send an ALPN extension
   with protocol indicator "http/1.1" when no *context* is given.
   Custom *context* should set ALPN protocols with
   "set_alpn_protocol()".

   버전 3.6부터 폐지: *cafile*, *capath* and *cadefault* are
   deprecated in favor of *context*. Please use
   "ssl.SSLContext.load_cert_chain()" instead, or let
   "ssl.create_default_context()" select the system's trusted CA
   certificates for you.

urllib.request.install_opener(opener)

   "OpenerDirector" 인스턴스를 기본 전역 오프너로 설치합니다. 오프너
   설치는 urlopen이 해당 오프너를 사용하도록 하려는 경우에만 필요합니
   다; 그렇지 않으면 단순히 "urlopen()" 대신 "OpenerDirector.open()"을
   호출하십시오. 코드는 실제 "OpenerDirector"를 확인하지 않으며, 적절
   한 인터페이스를 가진 클래스면 모두 작동합니다.

urllib.request.build_opener([handler, ...])

   주어진 순서대로 처리기를 연결하는 "OpenerDirector" 인스턴스를 반환
   합니다. *handler*는 "BaseHandler"의 인스턴스이거나 "BaseHandler"의
   서브 클래스(이 경우 매개 변수 없이 생성자를 호출할 수 있어야 합니다
   )일 수 있습니다. 다음과 같은 클래스들의 인스턴스는 *handler*에 그들
   , 그들의 인스턴스 또는 그들의 서브 클래스가 포함되지 않는 한
   *handler* 앞에 있습니다: "ProxyHandler" (프락시 설정이 감지되는 경
   우), "UnknownHandler", "HTTPHandler", "HTTPDefaultErrorHandler",
   "HTTPRedirectHandler", "FTPHandler", "FileHandler",
   "HTTPErrorProcessor".

   파이썬 설치에 SSL 지원이 있으면 (즉, "ssl" 모듈을 임포트 할 수 있으
   면) "HTTPSHandler"도 추가됩니다.

   "BaseHandler" 서브 클래스는 또한 "handler_order" 어트리뷰트를 변경
   하여 처리기 리스트에서 자신의 위치를 수정할 수 있습니다.

urllib.request.pathname2url(path)

   Convert the pathname *path* from the local syntax for a path to the
   form used in the path component of a URL.  This does not produce a
   complete URL.  The return value will already be quoted using the
   "quote()" function.

urllib.request.url2pathname(path)

   Convert the path component *path* from a percent-encoded URL to the
   local syntax for a path.  This does not accept a complete URL.
   This function uses "unquote()" to decode *path*.

urllib.request.getproxies()

   This helper function returns a dictionary of scheme to proxy server
   URL mappings. It scans the environment for variables named
   "<scheme>_proxy", in a case insensitive approach, for all operating
   systems first, and when it cannot find it, looks for proxy
   information from System Configuration for macOS and Windows Systems
   Registry for Windows. If both lowercase and uppercase environment
   variables exist (and disagree), lowercase is preferred.

   참고:

     일반적으로 스크립트가 CGI 환경에서 실행 중임을 나타내는 환경 변수
     "REQUEST_METHOD"가 설정되면, 환경 변수 "HTTP_PROXY"(대문자
     "_PROXY")는 무시됩니다. 이 변수는 "Proxy:" HTTP 헤더를 사용하여
     클라이언트가 주입할 수 있기 때문입니다. CGI 환경에서 HTTP 프락시
     를 사용해야 하면, "ProxyHandler"를 명시적으로 사용하거나 변수 이
     름이 소문자(또는 적어도 "_proxy" 접미사)가 되도록 하십시오.

다음과 같은 클래스가 제공됩니다:

class urllib.request.Request(url, data=None, headers={}, origin_req_host=None, unverifiable=False, method=None)

   이 클래스는 URL 요청의 추상화입니다.

   *url* should be a string containing a valid URL.

   *data*는 서버로 전송할 추가 데이터를 지정하는 객체이거나, 그러한 데
   이터가 필요하지 않으면 "None"이어야 합니다. 현재 HTTP 요청은 *data*
   를 사용하는 유일한 요청입니다. 지원되는 객체 형에는 바이트열, 파일
   류 객체 및 바이트열류 객체의 이터러블이 포함됩니다. "Content-
   Length"와 "Transfer-Encoding" 헤더 필드가 모두 제공되지 않으면,
   "HTTPHandler"는 *data*의 형에 따라 이러한 헤더를 설정합니다.
   "Content-Length"는 바이트열 객체를 보내는 데 사용되는 반면, **RFC
   7230**, 섹션 3.3.1에 지정된 "Transfer-Encoding: chunked"는 파일과
   다른 이터러블을 보내는 데 사용됩니다.

   HTTP POST 요청 메서드의 경우, *data*는 표준 *application/x-www-
   form-urlencoded* 형식의 버퍼여야 합니다. "urllib.parse.urlencode()"
   함수는 매핑이나 2-튜플의 시퀀스를 취하고 이 형식의 ASCII 문자열을
   반환합니다. *data* 매개 변수로 사용되기 전에 바이트열로 인코딩되어
   야 합니다.

   *headers* should be a dictionary, and will be treated as if
   "add_header()" was called with each key and value as arguments.
   This is often used to "spoof" the "User-Agent" header value, which
   is used by a browser to identify itself -- some HTTP servers only
   allow requests coming from common browsers as opposed to scripts.
   For example, Mozilla Firefox may identify itself as ""Mozilla/5.0
   (X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"", while
   "urllib"'s default user agent string is ""Python-urllib/2.6"" (on
   Python 2.6). All header keys are sent in camel case.

   An appropriate "Content-Type" header should be included if the
   *data* argument is present.  If this header has not been provided
   and *data* is not None, "Content-Type: application/x-www-form-
   urlencoded" will be added as a default.

   다음 두 인자는 제삼자 HTTP 쿠키를 올바르게 처리하는 데에만 관심이
   있습니다:

   *origin_req_host*는 **RFC 2965**에 의해 정의된 대로 오리진 트랜잭션
   의 요청 호스트여야 합니다. 기본값은
   "http.cookiejar.request_host(self)"입니다. 이것은 사용자가 시작한
   원래 요청의 호스트 이름이나 IP 주소입니다. 예를 들어, HTML 문서의
   이미지에 대한 요청이면, 이미지가 포함된 페이지에 대한 요청의 요청
   호스트여야 합니다.

   *unverifiable*은 **RFC 2965**에서 정의한 대로 요청을 확인할 수 없는
   지를 표시해야 합니다. 기본값은 "False"입니다. 확인할 수 없는 요청은
   사용자에게 URL에 대한 승인 옵션이 없는 요청입니다. 예를 들어, HTML
   문서의 이미지에 대한 요청이고, 사용자에게 이미지의 자동 가져오기를
   승인할 수 있는 옵션이 없으면, 이것은 참이어야 합니다.

   *method* should be a string that indicates the HTTP request method
   that will be used (e.g. "'HEAD'").  If provided, its value is
   stored in the "method" attribute and is used by "get_method()". The
   default is "'GET'" if *data* is "None" or "'POST'" otherwise.
   Subclasses may indicate a different default method by setting the
   "method" attribute in the class itself.

   참고:

     data 객체가 콘텐츠를 두 번 이상 (예를 들어 콘텐츠를 한 번만 생성
     할 수 있는 파일이나 이터러블) 전달할 수 없고 요청이 HTTP 리디렉션
     이나 인증을 위해 재시도되는 경우, 요청이 예상대로 작동하지 않습니
     다. *data*는 헤더 바로 다음에 HTTP 서버로 전송됩니다. 라이브러리
     에서 100-continue 예상(expectation)을 지원하지 않습니다.

   버전 3.3에서 변경: "Request.method" 인자가 Request 클래스에 추가됩
   니다.

   버전 3.4에서 변경: 클래스 수준에서 기본 "Request.method"를 지정할
   수 있습니다.

   버전 3.6에서 변경: "Content-Length"가 제공되지 않고 *data*가 "None"
   이나 바이트열 객체가 아닐 때 에러를 발생시키지 앖습니다. 대신 청크
   전송 인코딩(chunked transfer encoding)으로 폴백 합니다.

class urllib.request.OpenerDirector

   "OpenerDirector" 클래스는 서로 연결된 "BaseHandler"들을 통해 URL을
   엽니다. 처리기 연결과 에러 복구를 관리합니다.

class urllib.request.BaseHandler

   이것은 등록된 모든 처리기의 베이스 클래스이며 --- 간단한 등록 메커
   니즘만 처리합니다.

class urllib.request.HTTPDefaultErrorHandler

   HTTP 에러 응답에 대한 기본 처리기를 정의하는 클래스; 모든 응답은
   "HTTPError" 예외로 바뀝니다.

class urllib.request.HTTPRedirectHandler

   리디렉션을 처리하는 클래스.

class urllib.request.HTTPCookieProcessor(cookiejar=None)

   HTTP 쿠키를 처리하는 클래스.

class urllib.request.ProxyHandler(proxies=None)

   Cause requests to go through a proxy. If *proxies* is given, it
   must be a dictionary mapping protocol names to URLs of proxies. The
   default is to read the list of proxies from the environment
   variables "<protocol>_proxy".  If no proxy environment variables
   are set, then in a Windows environment proxy settings are obtained
   from the registry's Internet Settings section, and in a macOS
   environment proxy information is retrieved from the System
   Configuration Framework.

   자동 감지 프락시를 비활성화하려면 빈 딕셔너리를 전달하십시오.

   "no_proxy" 환경 변수를 사용하여 프락시를 통해 도달해서는 안 되는 호
   스트를 지정할 수 있습니다; 설정되면, 쉼표로 구분된 호스트 이름 접미
   사의 목록이어야 하며, 선택적으로 ":port"가 추가됩니다, 예를 들어
   "cern.ch,ncsa.uiuc.edu,some.host:8080".

      참고:

        변수 "REQUEST_METHOD"가 설정되면 "HTTP_PROXY"는 무시됩니다;
        "getproxies()"의 설명서를 참조하십시오.

class urllib.request.HTTPPasswordMgr

   "(realm, uri) -> (user, password)" 매핑 데이터베이스를 유지합니다.

class urllib.request.HTTPPasswordMgrWithDefaultRealm

   "(realm, uri) -> (user, password)" 매핑 데이터베이스를 유지합니다.
   "None" realm은 포괄(catch-all) 영역으로 간주하며 다른 영역에 맞지
   않으면 검색됩니다.

class urllib.request.HTTPPasswordMgrWithPriorAuth

   "uri -> is_authenticated" 매핑 데이터베이스도 포함하는
   "HTTPPasswordMgrWithDefaultRealm"의 변형. BasicAuth 처리기에서
   "401" 응답을 먼저 기다리는 대신 인증 자격 증명을 언제 보낼 것인지
   결정하는 데 사용할 수 있습니다.

   버전 3.5에 추가.

class urllib.request.AbstractBasicAuthHandler(password_mgr=None)

   원격 호스트와 프락시 모두에서 HTTP 인증을 돕는 믹스인 클래스입니다.
   *password_mgr*이 주어지면 "HTTPPasswordMgr" 과 호환되는 것이어야 합
   니다; 지원해야 하는 인터페이스에 대한 정보는 섹션 HTTPPasswordMgr
   객체를 참조하십시오. *passwd_mgr*이 "is_authenticated"와
   "update_authenticated" 메서드도 제공하면
   (HTTPPasswordMgrWithPriorAuth 객체를 참조하십시오), 처리기는 지정된
   URI에 대해 "is_authenticated" 결과를 사용하여 요청과 함께 인증 자격
   증명을 보낼지를 판별합니다. "is_authenticated"가 URI에 대해 "True"
   를 반환하면, 자격 증명이 전송됩니다. "is_authenticated"가 "False"이
   면, 자격 증명이 전송되지 않으며, 그런 다음 "401" 응답이 수신되면 요
   청이 인증 자격 증명과 함께 다시 전송됩니다. 인증이 성공하면, 이 URI
   에 대해 "is_authenticated"를 "True"로 설정하기 위해
   "update_authenticated"가 호출되어서, 이 URI나 모든 슈퍼 URI에 대한
   후속 요청에 인증 자격 증명이 자동으로 포함됩니다.

   버전 3.5에 추가: "is_authenticated" 지원이 추가되었습니다.

class urllib.request.HTTPBasicAuthHandler(password_mgr=None)

   원격 호스트와의 인증을 처리합니다. *password_mgr*이 주어지면
   "HTTPPasswordMgr" 과 호환되는 것이어야 합니다; 지원해야 하는 인터페
   이스에 대한 정보는 섹션 HTTPPasswordMgr 객체를 참조하십시오. 잘못된
   인증 스킴(Authentication scheme)을 제시하면 HTTPBasicAuthHandler 가
   "ValueError"를 발생시킵니다.

class urllib.request.ProxyBasicAuthHandler(password_mgr=None)

   프락시와의 인증을 처리합니다. *password_mgr*이 주어지면
   "HTTPPasswordMgr" 과 호환되는 것이어야 합니다; 지원해야 하는 인터페
   이스에 대한 정보는 섹션 HTTPPasswordMgr 객체를 참조하십시오.

class urllib.request.AbstractDigestAuthHandler(password_mgr=None)

   원격 호스트와 프락시 모두에서 HTTP 인증을 돕는 믹스인 클래스입니다.
   *password_mgr*이 주어지면 "HTTPPasswordMgr" 과 호환되는 것이어야 합
   니다; 지원해야 하는 인터페이스에 대한 정보는 섹션 HTTPPasswordMgr
   객체를 참조하십시오.

class urllib.request.HTTPDigestAuthHandler(password_mgr=None)

   원격 호스트와의 인증을 처리합니다. *password_mgr*이 주어지면
   "HTTPPasswordMgr" 과 호환되는 것이어야 합니다; 지원해야 하는 인터페
   이스에 대한 정보는 섹션 HTTPPasswordMgr 객체를 참조하십시오. 다이제
   스트 인증 처리기와 기본 인증 처리기가 모두 추가되면, 다이제스트 인
   증이 항상 먼저 시도됩니다. 다이제스트 인증이 다시 40x 응답을 반환하
   면, 기본 인증 처리기로 보내 처리됩니다. 이 처리기 메서드는 Digest나
   Basic 이외의 인증 스킴(authentication scheme)이 제공될 때
   "ValueError"를 발생시킵니다.

   버전 3.3에서 변경: 지원되지 않는 인증 스킴에 대해 "ValueError"를 발
   생시킵니다.

class urllib.request.ProxyDigestAuthHandler(password_mgr=None)

   프락시와의 인증을 처리합니다. *password_mgr*이 주어지면
   "HTTPPasswordMgr" 과 호환되는 것이어야 합니다; 지원해야 하는 인터페
   이스에 대한 정보는 섹션 HTTPPasswordMgr 객체를 참조하십시오.

class urllib.request.HTTPHandler

   HTTP URL 열기를 처리하는 클래스.

class urllib.request.HTTPSHandler(debuglevel=0, context=None, check_hostname=None)

   HTTPS URL 열기를 처리하는 클래스. *context*와 *check_hostname*은
   "http.client.HTTPSConnection"과 같은 의미입니다.

   버전 3.2에서 변경: *context*와 *check_hostname*이 추가되었습니다.

class urllib.request.FileHandler

   로컬 파일을 엽니다.

class urllib.request.DataHandler

   데이터 URL을 엽니다.

   버전 3.4에 추가.

class urllib.request.FTPHandler

   FTP URL을 엽니다.

class urllib.request.CacheFTPHandler

   지연 시간을 최소화하기 위해 열린 FTP 연결의 캐시를 유지하면서, FTP
   URL을 엽니다.

class urllib.request.UnknownHandler

   알 수 없는 URL을 처리하기 위한 포괄적인(catch-all) 클래스.

class urllib.request.HTTPErrorProcessor

   HTTP 에러 응답을 처리합니다.


Request 객체
============

다음 메서드는 "Request"의 공용 인터페이스를 설명하므로, 서브 클래스에
서 모두 재정의될 수 있습니다. 또한 클라이언트가 구문 분석된 요청을 검
사하는 데 사용할 수 있는 몇 가지 공용 어트리뷰트를 정의합니다.

Request.full_url

   생성자에 전달된 원래 URL.

   버전 3.4에서 변경.

   Request.full_url은 setter, getter 및 deleter가 있는 프로퍼티입니다.
   "full_url"을 읽으면 프래그먼트가 있는 원래 요청 URL을 반환합니다 (
   있다면).

Request.type

   URI 스킴.

Request.host

   URI 주체(authority), 일반적으로 호스트이지만 콜론으로 구분된 포트를
   포함할 수도 있습니다.

Request.origin_req_host

   포트가 없는, 요청의 원래 호스트.

Request.selector

   URI 경로. "Request"가 프락시를 사용하면, selector는 프락시로 전달되
   는 전체 URL이 됩니다.

Request.data

   요청의 엔티티 바디, 또는 지정되지 않으면 "None".

   버전 3.4에서 변경: "Request.data"의 값을 변경하면 이제 "Content-
   Length" 헤더가 이전에 설정되거나 계산되었다면 삭제됩니다.

Request.unverifiable

   불리언, **RFC 2965**에서 정의한 대로 요청을 확인할 수 없는지를 나타
   냅니다.

Request.method

   사용할 HTTP 요청 메서드. 기본적으로 값은 "None"입니다. 이는
   "get_method()"가 사용될 메서드의 일반적인 계산을 수행함을 뜻합니다.
   "Request" 서브 클래스의 클래스 수준에서 값을 설정해서 기본값을 제공
   하거나, *method* 인자를 통해 "Request" 생성자에 값을 전달하여 값을
   설정할 수 있습니다 (그래서 "get_method()"의 기본 계산을 무시합니다
   ).

   버전 3.3에 추가.

   버전 3.4에서 변경: 서브 클래스에서 이제 기본값을 설정할 수 있습니다
   ; 이전에는 생성자 인자를 통해서만 설정할 수 있었습니다.

Request.get_method()

   HTTP 요청 메서드를 나타내는 문자열을 반환합니다. "Request.method"가
   "None"이 아니면, 그 값을 반환하고, 그렇지 않으면 "Request.data"가
   "None"이면 "'GET'"을 반환하거나 그렇지 않으면 "'POST'"를 반환합니다
   . 이것은 HTTP 요청에만 의미가 있습니다.

   버전 3.3에서 변경: get_method는 이제 "Request.method"의 값을 조사합
   니다.

Request.add_header(key, val)

   Add another header to the request.  Headers are currently ignored
   by all handlers except HTTP handlers, where they are added to the
   list of headers sent to the server.  Note that there cannot be more
   than one header with the same name, and later calls will overwrite
   previous calls in case the *key* collides. Currently, this is no
   loss of HTTP functionality, since all headers which have meaning
   when used more than once have a (header-specific) way of gaining
   the same functionality using only one header.  Note that headers
   added using this method are also added to redirected requests.

Request.add_unredirected_header(key, header)

   리디렉션 된 요청에 추가되지 않을 헤더를 추가합니다.

Request.has_header(header)

   인스턴스에 명명된 헤더가 있는지를 반환합니다 (일반과 리디렉션되지
   않는 것을 모두 확인합니다).

Request.remove_header(header)

   요청 인스턴스에서 명명된 헤더를 제거합니다 (일반과 리디렉션되지 않
   은 헤더 모두).

   버전 3.4에 추가.

Request.get_full_url()

   생성자에 제공된 URL을 반환합니다.

   버전 3.4에서 변경.

   "Request.full_url"을 반환합니다

Request.set_proxy(host, type)

   프락시 서버에 연결하여 요청을 준비합니다. *host*와 *type*은 인스턴
   스의 것을 대체하고, 인스턴스의 selector는 생성자에 제공된 원래 URL
   이 됩니다.

Request.get_header(header_name, default=None)

   지정된 헤더의 값을 반환합니다. 헤더가 없으면, default 값을 반환합니
   다.

Request.header_items()

   요청 헤더의 튜플 (header_name, header_value) 리스트를 반환합니다.

버전 3.4에서 변경: 3.3부터 폐지된 add_data, has_data, get_data,
get_type, get_host, get_selector, get_origin_req_host 및
is_unverifiable 요청 메서드가 제거되었습니다.


OpenerDirector 객체
===================

"OpenerDirector" 인스턴스에는 다음과 같은 메서드가 있습니다:

OpenerDirector.add_handler(handler)

   *handler*는 "BaseHandler"의 인스턴스여야 합니다. 다음 메서드가 검색
   되어, 가능한 체인에 추가됩니다 (HTTP 에러는 특별한 경우임에 유의하
   십시오). 다음에서 *protocol*은 처리할 실제 프로토콜로 바꿔야 합니다
   , 예를 들어 "http_response()"는 HTTP 프로토콜 응답 처리기입니다. 또
   한 *type*은 실제 HTTP 코드로 대체해야 합니다, 예를 들어
   "http_error_404()"는 HTTP 404 에러를 처리합니다.

   * "<protocol>_open()" --- signal that the handler knows how to open
     *protocol* URLs.

     자세한 정보는 "BaseHandler.<protocol>_open()"을 참조하십시오.

   * "http_error_<type>()" --- signal that the handler knows how to
     handle HTTP errors with HTTP error code *type*.

     자세한 정보는 "BaseHandler.http_error_<nnn>()"을 참조하십시오.

   * "<protocol>_error()" --- signal that the handler knows how to
     handle errors from (non-"http") *protocol*.

   * "<protocol>_request()" --- signal that the handler knows how to
     pre-process *protocol* requests.

     자세한 정보는 "BaseHandler.<protocol>_request()"를 참조하십시오.

   * "<protocol>_response()" --- signal that the handler knows how to
     post-process *protocol* responses.

     자세한 정보는 "BaseHandler.<protocol>_response()"를 참조하십시오.

OpenerDirector.open(url, data=None[, timeout])

   Open the given *url* (which can be a request object or a string),
   optionally passing the given *data*. Arguments, return values and
   exceptions raised are the same as those of "urlopen()" (which
   simply calls the "open()" method on the currently installed global
   "OpenerDirector").  The optional *timeout* parameter specifies a
   timeout in seconds for blocking operations like the connection
   attempt (if not specified, the global default timeout setting will
   be used). The timeout feature actually works only for HTTP, HTTPS
   and FTP connections.

OpenerDirector.error(proto, *args)

   Handle an error of the given protocol.  This will call the
   registered error handlers for the given protocol with the given
   arguments (which are protocol specific).  The HTTP protocol is a
   special case which uses the HTTP response code to determine the
   specific error handler; refer to the "http_error_<type>()" methods
   of the handler classes.

   반환 값과 발생하는 예외는 "urlopen()"과 같습니다.

OpenerDirector 객체는 다음 3단계로 URL을 엽니다:

각 단계에서 이러한 메서드가 호출되는 순서는 처리기 인스턴스를 정렬하여
결정됩니다.

1. Every handler with a method named like "<protocol>_request()" has
   that method called to pre-process the request.

2. Handlers with a method named like "<protocol>_open()" are called to
   handle the request. This stage ends when a handler either returns a
   non-"None" value (ie. a response), or raises an exception (usually
   "URLError").  Exceptions are allowed to propagate.

   In fact, the above algorithm is first tried for methods named
   "default_open()".  If all such methods return "None", the algorithm
   is repeated for methods named like "<protocol>_open()".  If all
   such methods return "None", the algorithm is repeated for methods
   named "unknown_open()".

   이러한 메서드의 구현은 부모 "OpenerDirector" 인스턴스의 "open()"과
   "error()" 메서드의 호출을 수반할 수 있음에 유의하십시오.

3. Every handler with a method named like "<protocol>_response()" has
   that method called to post-process the response.


BaseHandler 객체
================

"BaseHandler" 객체는 직접적으로 유용한 몇 가지 메서드와 파생 클래스에
서 사용하기 위한 다른 메서드를 제공합니다. 다음은 직접 사용하기 위한
것입니다:

BaseHandler.add_parent(director)

   director를 부모로 추가합니다.

BaseHandler.close()

   모든 부모를 제거합니다.

다음 어트리뷰트와 메서드는 "BaseHandler"에서 파생된 클래스에서만 사용
해야 합니다.

참고:

  The convention has been adopted that subclasses defining
  "<protocol>_request()" or "<protocol>_response()" methods are named
  "*Processor"; all others are named "*Handler".

BaseHandler.parent

   다른 프로토콜을 사용하여 열거나 에러를 처리하는 데 사용할 수 있는
   유효한 "OpenerDirector".

BaseHandler.default_open(req)

   이 메서드는 "BaseHandler"에 정의되지 *않았지만*, 서브 클래스가 모든
   URL을 포착하려면 이를 정의해야 합니다.

   This method, if implemented, will be called by the parent
   "OpenerDirector".  It should return a file-like object as described
   in the return value of the "open()" method of "OpenerDirector", or
   "None". It should raise "URLError", unless a truly exceptional
   thing happens (for example, "MemoryError" should not be mapped to
   "URLError").

   이 메서드는 프로토콜별 open 메서드보다 먼저 호출됩니다.

BaseHandler.<protocol>_open(req)

   이 메서드는 "BaseHandler" 에 정의되지 *않았지만*, 서브 클래스가 주
   어진 프로토콜로 URL을 처리하려면 이를 정의해야 합니다.

   This method, if defined, will be called by the parent
   "OpenerDirector". Return values should be the same as for
   "default_open()".

BaseHandler.unknown_open(req)

   이 메서드는 "BaseHandler" 에 정의되지 *않았지만*, 서브 클래스는 등
   록된 특정 처리기가 없는 모든 URL을 잡아서 열려면 이를 정의해야 합니
   다.

   구현되면, 이 메서드는 "parent" "OpenerDirector"에 의해 호출됩니다.
   반환 값은 "default_open()"과 같아야 합니다.

BaseHandler.http_error_default(req, fp, code, msg, hdrs)

   이 메서드는 "BaseHandler" 에 정의되지 *않았지만*, 서브 클래스는 달
   리 처리되지 않은 HTTP 에러에 대해 포괄적인 처리를 제공하려면 이를
   재정의해야 합니다. 에러가 발생하는 "OpenerDirector"에 의해 자동으로
   호출되며, 다른 상황에서는 일반적으로 호출되지 않아야 합니다.

   *req*는 "Request" 객체, *fp*는 HTTP 에러 바디가 있는 파일류 객체,
   *code*는 에러의 3자리 코드, *msg*는 사용자가 볼 수 있는 코드 설명,
   *hdrs*는 에러의 헤더가 있는 매핑 객체가 됩니다.

   반환 값과 발생하는 예외는 "urlopen()"의 것과 같아야 합니다.

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

   *nnn*은 3자리 HTTP 에러 코드여야 합니다. 이 메서드도 "BaseHandler"
   에 정의되어 있지 않지만, 존재한다면 코드가 *nnn* 인 HTTP 에러가 발
   생할 때 서브 클래스의 인스턴스에 대해 호출됩니다.

   특정 HTTP 에러를 처리하려면 서브 클래스가 이 메서드를 재정의해야 합
   니다.

   Arguments, return values and exceptions raised should be the same
   as for "http_error_default()".

BaseHandler.<protocol>_request(req)

   이 메서드는 "BaseHandler" 에 정의되지 *않았지만*, 서브 클래스는 주
   어진 프로토콜의 요청을 전처리하려면 이를 정의해야 합니다.

   정의되면, 이 메서드는 부모 상위 "OpenerDirector"에 의해 호출됩니다.
   *req*는 "Request" 객체가 됩니다. 반환 값은 "Request" 객체여야 합니
   다.

BaseHandler.<protocol>_response(req, response)

   이 메서드는 "BaseHandler" 에 정의되지 *않았지만*, 서브 클래스는 주
   어진 프로토콜의 응답을 후처리하려면 이를 정의해야 합니다.

   정의되면, 이 메서드는 부모 "OpenerDirector"에 의해 호출됩니다.
   *req*는 "Request" 객체가 됩니다. *response*는 "urlopen()"의 반환 값
   과 같은 인터페이스를 구현하는 객체가 됩니다. 반환 값은 "urlopen()"
   의 반환 값과 같은 인터페이스를 구현해야 합니다.


HTTPRedirectHandler 객체
========================

참고:

  일부 HTTP 리디렉션은 이 모듈의 클라이언트 코드로부터의 액션을 요구합
  니다. 이 경우, "HTTPError"가 발생합니다. 다양한 리디렉션 코드의 정확
  한 의미에 대한 자세한 내용은 **RFC 2616**을 참조하십시오.An
  "HTTPError" exception raised as a security consideration if the
  HTTPRedirectHandler is presented with a redirected URL which is not
  an HTTP, HTTPS or FTP URL.

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

   Return a "Request" or "None" in response to a redirect. This is
   called by the default implementations of the "http_error_30*()"
   methods when a redirection is received from the server.  If a
   redirection should take place, return a new "Request" to allow
   "http_error_30*()" to perform the redirect to *newurl*.  Otherwise,
   raise "HTTPError" if no other handler should try to handle this
   URL, or return "None" if you can't but another handler might.

   참고:

     이 메서드의 기본 구현은 **RFC 2616**을 엄격하게 따르지 않습니다.
     즉, "POST" 요청에 대한 301과 302 응답은 사용자의 확인 없이 자동으
     로 리디렉션 되지 않아야 합니다. 실제로는, 브라우저들이 POST를
     "GET"으로 변경하여 이러한 응답의 자동 리디렉션을 허용하며, 기본
     구현은 이 동작을 재현합니다.

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)

   "Location:"이나 "URI:" URL로 리디렉션 합니다. 이 메서드는 HTTP
   'moved permanently(영구적으로 이전했음)' 응답을 받을 때 부모
   "OpenerDirector"에 의해 호출됩니다.

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)

   "http_error_301()"과 같지만, 'found(발견됨)' 응답에 대해 호출됩니다
   .

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)

   "http_error_301()"과 같지만, 'see other(다른 곳을 보세요)' 응답에
   대해 호출됩니다.

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)

   The same as "http_error_301()", but called for the 'temporary
   redirect' response.


HTTPCookieProcessor 객체
========================

"HTTPCookieProcessor" 인스턴스에는 하나의 어트리뷰트가 있습니다:

HTTPCookieProcessor.cookiejar

   쿠키가 저장되는 "http.cookiejar.CookieJar".


ProxyHandler 객체
=================

ProxyHandler.<protocol>_open(request)

   The "ProxyHandler" will have a method "<protocol>_open()" for every
   *protocol* which has a proxy in the *proxies* dictionary given in
   the constructor.  The method will modify requests to go through the
   proxy, by calling "request.set_proxy()", and call the next handler
   in the chain to actually execute the protocol.


HTTPPasswordMgr 객체
====================

이 메서드는 "HTTPPasswordMgr" 과 "HTTPPasswordMgrWithDefaultRealm" 객
체에서 사용 가능합니다.

HTTPPasswordMgr.add_password(realm, uri, user, passwd)

   *uri*는 단일 URI이거나 URI의 시퀀스일 수 있습니다. *realm*, *user*
   및 *passwd*는 문자열이어야 합니다. 이는 *realm*과 지정된 URI 중 어
   느 하나의 슈퍼 URI에 대한 인증이 주어질 때 "(user, passwd)"가 인증
   토큰으로 사용되도록 합니다.

HTTPPasswordMgr.find_user_password(realm, authuri)

   주어진 realm과 URI에 대한 사용자/암호를 (있다면) 가져옵니다. 일치하
   는 사용자/암호가 없으면 이 메서드는 "(None, None)"을 반환합니다.

   "HTTPPasswordMgrWithDefaultRealm" 객체의 경우, 주어진 *realm*에 일
   치하는 사용자/암호가 없으면 영역 "None"이 검색됩니다.


HTTPPasswordMgrWithPriorAuth 객체
=================================

이 암호 관리자는 "HTTPPasswordMgrWithDefaultRealm"를 확장하여 인증 자
격 증명을 항상 보내야 하는 URI를 추적하는 것을 지원합니다.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)

   *realm*, *uri*, *user*, *passwd*는 "HTTPPasswordMgr.add_password()"
   와 같습니다. *is_authenticated*는 주어진 URI나 URI 리스트에 대한
   "is_authenticated" 플래그의 초깃값을 설정합니다. *is_authenticated*
   가 "True"로 지정되면, *realm*는 무시됩니다.

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)

   "HTTPPasswordMgrWithDefaultRealm" 객체와 같습니다

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)

   주어진 *uri*나 URI 리스트에 대해 "is_authenticated" 플래그를 갱신합
   니다.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

   주어진 URI에 대한 "is_authenticated" 플래그의 현재 상태를 반환합니
   다.


AbstractBasicAuthHandler 객체
=============================

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

   사용자/암호 쌍을 가져오고 요청을 다시 시도하여 인증 요청을 처리합니
   다. *authreq*는 영역(realm)에 대한 정보가 요청에 포함된 헤더의 이름
   이어야 하고, *host*는 인증할 URL과 경로를 지정하고, *req*는 (실패한
   ) "Request" 객체여야 하며, *headers*는 에러 헤더여야 합니다.

   *host*는 주체(예를 들어 ""python.org"")거나 주체 구성 요소를 포함하
   는 URL(예를 들어 ""http://python.org/"")입니다. 어느 경우이든, 주체
   는 userinfo 구성 요소를 포함하지 않아야 합니다 (따라서,
   ""python.org""와 ""python.org:80""은 좋지만,
   ""joe:password@python.org""는 유효하지 않습니다).


HTTPBasicAuthHandler 객체
=========================

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)

   가능하다면 인증 정보로 요청을 재시도합니다.


ProxyBasicAuthHandler 객체
==========================

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)

   가능하다면 인증 정보로 요청을 재시도합니다.


AbstractDigestAuthHandler 객체
==============================

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)

   *authreq*는 영역(realm)에 대한 정보가 요청에 포함된 헤더의 이름이어
   야 하고, *host*는 인증할 호스트여야 하고, *req*는 (실패한)
   "Request" 객체여야 하며, *headers*는 에러 헤더여야 합니다.


HTTPDigestAuthHandler 객체
==========================

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)

   가능하다면 인증 정보로 요청을 재시도합니다.


ProxyDigestAuthHandler 객체
===========================

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)

   가능하다면 인증 정보로 요청을 재시도합니다.


HTTPHandler 객체
================

HTTPHandler.http_open(req)

   HTTP 요청을 보냅니다. "req.has_data()"에 따라, GET이나 POST일 수 있
   습니다.


HTTPSHandler 객체
=================

HTTPSHandler.https_open(req)

   HTTPS 요청을 보냅니다. "req.has_data()"에 따라, GET이나 POST일 수
   있습니다.


FileHandler 객체
================

FileHandler.file_open(req)

   호스트 이름이 없거나, 호스트 이름이 "'localhost'"인 경우 파일을 로
   컬에서 엽니다.

   버전 3.2에서 변경: This method is applicable only for local
   hostnames.  When a remote hostname is given, an "URLError" is
   raised.


DataHandler 객체
================

DataHandler.data_open(req)

   Read a data URL. This kind of URL contains the content encoded in
   the URL itself. The data URL syntax is specified in **RFC 2397**.
   This implementation ignores white spaces in base64 encoded data
   URLs so the URL may be wrapped in whatever source file it comes
   from. But even though some browsers don't mind about a missing
   padding at the end of a base64 encoded data URL, this
   implementation will raise an "ValueError" in that case.


FTPHandler 객체
===============

FTPHandler.ftp_open(req)

   *req*로 표시된 FTP 파일을 엽니다. 로그인은 항상 빈 사용자 이름과 암
   호로 수행됩니다.


CacheFTPHandler 객체
====================

"CacheFTPHandler" 객체는 다음과 같은 추가 메서드가 있는 "FTPHandler"
객체입니다:

CacheFTPHandler.setTimeout(t)

   연결 시간제한을 *t* 초로 설정합니다.

CacheFTPHandler.setMaxConns(m)

   캐시 된 최대 연결 수를 *m*으로 설정합니다.


UnknownHandler 객체
===================

UnknownHandler.unknown_open()

   "URLError" 예외를 발생시킵니다.


HTTPErrorProcessor 객체
=======================

HTTPErrorProcessor.http_response(request, response)

   HTTP 에러 응답을 처리합니다.

   200 에러 코드의 경우, 응답 객체가 즉시 반환됩니다.

   For non-200 error codes, this simply passes the job on to the
   "http_error_<type>()" handler methods, via
   "OpenerDirector.error()". Eventually, "HTTPDefaultErrorHandler"
   will raise an "HTTPError" if no other handler handles the error.

HTTPErrorProcessor.https_response(request, response)

   HTTPS 에러 응답을 처리합니다.

   동작은 "http_response()"와 같습니다.


예
==

아래 예 외에도 urllib 패키지를 사용하여 인터넷 리소스를 가져오는 방법
에는 더 많은 예가 나와 있습니다.

This example gets the python.org main page and displays the first 300
bytes of it.

   >>> import urllib.request
   >>> with urllib.request.urlopen('http://www.python.org/') as f:
   ...     print(f.read(300))
   ...
   b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
   xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
   <meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
   <title>Python Programming '

urlopen은 바이트열 객체를 반환함에 유의하십시오. 이는 urlopen이 HTTP
서버로부터 수신한 바이트 스트림의 인코딩을 자동으로 결정할 방법이 없기
때문입니다. 일반적으로, 프로그램은 일단 적절한 인코딩을 결정하거나 추
측하면 반환된 바이트열 객체를 문자열로 디코딩합니다.

The following W3C document,
https://www.w3.org/International/O-charset, lists the various ways in
which an (X)HTML or an XML document could have specified its encoding
information.

As the python.org website uses *utf-8* encoding as specified in its
meta tag, we will use the same for decoding the bytes object.

   >>> with urllib.request.urlopen('http://www.python.org/') as f:
   ...     print(f.read(100).decode('utf-8'))
   ...
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtm

It is also possible to achieve the same result without using the
*context manager* approach.

   >>> import urllib.request
   >>> f = urllib.request.urlopen('http://www.python.org/')
   >>> print(f.read(100).decode('utf-8'))
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtm

다음 예에서는, CGI의 표준 입력으로 데이터 스트림을 전송하고 반환되는
데이터를 읽습니다. 이 예제는 파이썬 설치가 SSL을 지원할 때만 작동함에
유의하십시오.

   >>> import urllib.request
   >>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
   ...                       data=b'This data is passed to stdin of the CGI')
   >>> with urllib.request.urlopen(req) as f:
   ...     print(f.read().decode('utf-8'))
   ...
   Got Data: "This data is passed to stdin of the CGI"

위 예제에서 사용한 샘플 CGI의 코드는 다음과 같습니다:

   #!/usr/bin/env python
   import sys
   data = sys.stdin.read()
   print('Content-type: text/plain\n\nGot Data: "%s"' % data)

다음은 "Request"를 사용하여 "PUT" 요청을 수행하는 예입니다:

   import urllib.request
   DATA = b'some data'
   req = urllib.request.Request(url='http://localhost:8080', data=DATA, method='PUT')
   with urllib.request.urlopen(req) as f:
       pass
   print(f.status)
   print(f.reason)

기본 HTTP 인증 사용:

   import urllib.request
   # Create an OpenerDirector with support for Basic HTTP Authentication...
   auth_handler = urllib.request.HTTPBasicAuthHandler()
   auth_handler.add_password(realm='PDQ Application',
                             uri='https://mahler:8092/site-updates.py',
                             user='klem',
                             passwd='kadidd!ehopper')
   opener = urllib.request.build_opener(auth_handler)
   # ...and install it globally so it can be used with urlopen.
   urllib.request.install_opener(opener)
   urllib.request.urlopen('http://www.example.com/login.html')

"build_opener()" provides many handlers by default, including a
"ProxyHandler".  By default, "ProxyHandler" uses the environment
variables named "<scheme>_proxy", where "<scheme>" is the URL scheme
involved.  For example, the "http_proxy" environment variable is read
to obtain the HTTP proxy's URL.

This example replaces the default "ProxyHandler" with one that uses
programmatically supplied proxy URLs, and adds proxy authorization
support with "ProxyBasicAuthHandler".

   proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
   proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
   proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

   opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
   # This time, rather than install the OpenerDirector, we use it directly:
   opener.open('http://www.example.com/login.html')

HTTP 헤더 추가하기:

"Request" 생성자에 *headers* 인자를 사용하십시오, 또는:

   import urllib.request
   req = urllib.request.Request('http://www.example.com/')
   req.add_header('Referer', 'http://www.python.org/')
   # Customize the default User-Agent header value:
   req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
   r = urllib.request.urlopen(req)

"OpenerDirector"는 모든 "Request"에 *User-Agent* 헤더를 자동으로 추가
합니다. 이것을 바꾸려면:

   import urllib.request
   opener = urllib.request.build_opener()
   opener.addheaders = [('User-agent', 'Mozilla/5.0')]
   opener.open('http://www.example.com/')

또한, "Request"가 "urlopen()"(또는 "OpenerDirector.open()")으로 전달될
때 몇 가지 표준 헤더(*Content-Length*, *Content-Type* 및 *Host*)가 추
가됨을 기억하십시오.

다음은 "GET" 메서드를 사용하여 파라미터가 포함된 URL을 가져오는 예제
세션입니다:

   >>> import urllib.request
   >>> import urllib.parse
   >>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
   >>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % params
   >>> with urllib.request.urlopen(url) as f:
   ...     print(f.read().decode('utf-8'))
   ...

다음 예제는 대신 "POST" 메서드를 사용합니다. urlencode의 파라미터 출력
이 데이터로 urlopen에 보내기 전에 바이트열로 인코딩됨에 유의하십시오:

   >>> import urllib.request
   >>> import urllib.parse
   >>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
   >>> data = data.encode('ascii')
   >>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
   ...     print(f.read().decode('utf-8'))
   ...

다음 예제는 명시적으로 지정된 HTTP 프락시를 사용하여 환경 설정을 대체
합니다:

   >>> import urllib.request
   >>> proxies = {'http': 'http://proxy.example.com:8080/'}
   >>> opener = urllib.request.FancyURLopener(proxies)
   >>> with opener.open("http://www.python.org") as f:
   ...     f.read().decode('utf-8')
   ...

다음 예제는 프락시를 전혀 사용하지 않도록 환경 설정을 대체합니다:

   >>> import urllib.request
   >>> opener = urllib.request.FancyURLopener({})
   >>> with opener.open("http://www.python.org/") as f:
   ...     f.read().decode('utf-8')
   ...


레거시 인터페이스
=================

다음 함수와 클래스는 파이썬 2 모듈 "urllib"("urllib2"가 아니라)에서 이
식됩니다. 나중에 언젠가 폐지될 수 있습니다.

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)

   Copy a network object denoted by a URL to a local file. If the URL
   points to a local file, the object will not be copied unless
   filename is supplied. Return a tuple "(filename, headers)" where
   *filename* is the local file name under which the object can be
   found, and *headers* is whatever the "info()" method of the object
   returned by "urlopen()" returned (for a remote object). Exceptions
   are the same as for "urlopen()".

   있다면, 두 번째 인자는 복사할 파일 위치를 지정합니다 (없으면, 위치
   는 생성된 이름을 가진 임시 파일이 됩니다). 있다면, 세 번째 인자는
   네트워크 연결이 이루어질 때 한 번 호출되고 그 이후에 각 블록을 읽을
   때마다 한 번씩 호출되는 콜러블입니다. 콜러블에는 세 개의 인자가 전
   달됩니다; 지금까지 전송된 블록 수, 바이트 단위의 블록 크기 및 파일
   의 전체 크기. 세 번째 인자는 가져오기 요청에 대한 응답으로 파일 크
   기를 반환하지 않는 구형 FTP 서버에서 "-1"일 수 있습니다.

   다음 예는 가장 일반적인 사용 시나리오를 보여줍니다:

      >>> import urllib.request
      >>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
      >>> html = open(local_filename)
      >>> html.close()

   *url*이 "http:" 스킴 식별자를 사용하면, "POST" 요청을 지정하기 위해
   선택적 *data* 인자가 제공될 수 있습니다 (일반적으로 요청형은 "GET"
   입니다). *data* 인자는 표준 *application/x-www-form-urlencoded* 형
   식의 바이트열 객체여야 합니다; "urllib.parse.urlencode()" 함수를 참
   조하십시오.

   "urlretrieve()" will raise "ContentTooShortError" when it detects
   that the amount of data available  was less than the expected
   amount (which is the size reported by a  *Content-Length* header).
   This can occur, for example, when the  download is interrupted.

   *Content-Length*는 하한값으로 취급됩니다: 읽을 데이터가 더 있으면,
   urlretrieve는 더 많은 데이터를 읽지만, 사용 가능한 데이터가 부족하
   면 예외가 발생합니다.

   You can still retrieve the downloaded data in this case, it is
   stored  in the "content" attribute of the exception instance.

   *Content-Length* 헤더가 제공되지 않으면, urlretrieve는 다운로드 한
   데이터의 크기를 확인할 수 없고, 그냥 반환합니다. 이 경우 다운로드가
   성공했다고 가정해야 합니다.

urllib.request.urlcleanup()

   "urlretrieve()"에 대한 이전 호출로 남겨졌을 수 있는 임시 파일을 정
   리합니다.

class urllib.request.URLopener(proxies=None, **x509)

   버전 3.3부터 폐지.

   URL을 열고 읽는 베이스 클래스. "http:", "ftp:" 또는 "file:" 이외의
   스킴을 사용하여 객체 열기를 지원할 필요가 있지 않은 한, 아마도
   "FancyURLopener"를 사용하고 싶을 것입니다.

   기본적으로, "URLopener" 클래스는 *User-Agent* 헤더로 "urllib/VVV"를
   전송합니다. 여기서 *VVV*는 "urllib" 버전 번호입니다. 응용 프로그램
   은 "URLopener"나 "FancyURLopener"를 서브 클래싱하고 클래스 어트리뷰
   트 "version"을 서브 클래스 정의에서 적절한 문자열 값으로 설정하여
   자체 *User-Agent* 헤더를 정의할 수 있습니다.

   선택적 *proxies* 매개 변수는 스킴 이름을 프락시 URL로 매핑하는 딕셔
   너리여야 합니다. 여기서 빈 딕셔너리는 프락시를 완전히 끕니다. 기본
   값은 "None"이며, 이 경우 위의 "urlopen()" 정의에서 설명한 대로 환경
   프락시 설정이 있으면 사용됩니다.

   *x509*로 수집된 추가 키워드 매개 변수는 "https:" 스킴을 사용할 때
   클라이언트의 인증에 사용될 수 있습니다. 키워드 *key_file*과
   *cert_file*은 SSL 키와 인증서를 제공하기 위해 지원됩니다; 클라이언
   트 인증을 지원하려면 둘 다 필요합니다.

   서버가 에러 코드를 반환하면 "URLopener" 객체는 "OSError" 예외를 발
   생시킵니다.

   open(fullurl, data=None)

      적절한 프로토콜을 사용하여 *fullurl*을 엽니다. 이 메서드는 캐시
      와 프락시 정보를 설정한 다음, 입력 인자로 적절한 open 메서드를
      호출합니다. 스킴이 인식되지 않으면, "open_unknown()"이 호출됩니
      다. *data* 인자는 "urlopen()"의 *data* 인자와 같은 의미입니다.

      이 메서드는 항상 "quote()"를 사용하여 *fullurl*을 인용합니다.

   open_unknown(fullurl, data=None)

      알 수 없는 URL 유형을 여는 재정의 가능한 인터페이스.

   retrieve(url, filename=None, reporthook=None, data=None)

      *url*의 내용을 가져와서 *filename*에 배치합니다. 반환 값은 로컬
      파일명과 응답 헤더를 포함하는 "email.message.Message" 객체 (원격
      URL의 경우) 또는 "None"(로컬 URL의 경우)으로 구성된 튜플입니다.
      그러면 호출자는 *filename*의 내용을 열고 읽어야 합니다.
      *filename*이 제공되지 않고 URL이 로컬 파일을 참조하면, 입력 파일
      명이 반환됩니다. URL이 로컬이 아니고 *filename*이 제공되지 않으
      면, 파일 이름은 입력 URL의 마지막 경로 구성 요소의 접미사와 일치
      하는 접미사로 "tempfile.mktemp()" 한 출력입니다. *reporthook*이
      제공되면, 세 개의 숫자 매개 변수를 받아들이는 함수여야 합니다:
      청크 번호, 청크를 읽을 최대 크기 및 다운로드의 전체 크기 (알 수
      없으면 -1). 처음에 한 번 호출되고 네트워크에서 각 데이터 청크를
      읽은 후에 한 번씩 호출됩니다. 로컬 URL의 경우 *reporthook*은 무
      시됩니다.

      *url*이 "http:" 스킴 식별자를 사용하면, "POST" 요청을 지정하기
      위해 선택적 *data* 인자가 제공될 수 있습니다 (일반적으로 요청형
      은 "GET"입니다). *data* 인자는 표준 *application/x-www-form-
      urlencoded* 형식이어야 합니다; "urllib.parse.urlencode()" 함수를
      참조하십시오.

   version

      오프너 객체의 사용자 에이전트를 지정하는 변수. "urllib"가 서버에
      특정 사용자 에이전트임을 알리려면, 서브 클래스에서 클래스 변수로
      설정하거나 생성자에서 베이스 생성자를 호출하기 전에 이를 설정하
      십시오.

class urllib.request.FancyURLopener(...)

   버전 3.3부터 폐지.

   "FancyURLopener"는 다음 HTTP 응답 코드에 대한 기본 처리를 제공하는
   "URLopener" 서브 클래스입니다: 301, 302, 303, 307 및 401. 위에 나열
   된 30x 응답 코드의 경우, 실제 URL을 가져오는 데 *Location* 헤더가
   사용됩니다. 401 응답 코드(authentication required - 인증 필요)의 경
   우, 기본 HTTP 인증이 수행됩니다. 30x 응답 코드의 경우, 재귀는
   *maxtries* 어트리뷰트 값에 의해 제한되며, 기본값은 10입니다.

   For all other response codes, the method "http_error_default()" is
   called which you can override in subclasses to handle the error
   appropriately.

   참고:

     **RFC 2616**의 편지(letter)에 따르면, POST 요청에 대한 301과 302
     응답은 사용자의 확인 없이 자동으로 리디렉션 되지 않아야 합니다.
     실제로는, 브라우저들이 POST를 GET으로 변경하여 이러한 응답의 자동
     리디렉션을 허용하고, "urllib"는 이 동작을 재현합니다.

   생성자의 매개 변수는 "URLopener"의 매개 변수와 같습니다.

   참고:

     기본 인증을 수행할 때, "FancyURLopener" 인스턴스는
     "prompt_user_passwd()" 메서드를 호출합니다. 기본 구현은 사용자에
     게 제어 터미널에서 필요한 정보를 요청합니다. 필요하면 서브 클래스
     가 이 메서드를 재정의하여 더 적절한 동작을 지원할 수 있습니다.

   "FancyURLopener" 클래스는 적절한 동작을 제공하기 위해 재정의되어야
   하는 하나의 추가 메서드를 제공합니다:

   prompt_user_passwd(host, realm)

      지정된 보안 영역(realm)의 지정된 호스트에서 사용자를 인증하는 데
      필요한 정보를 반환합니다. 반환 값은 기본 인증에 사용될 수 있는
      튜플 "(user, password)"여야 합니다.

      구현은 터미널에서 이 정보를 요구합니다; 로컬 환경에서 적절한 상
      호 작용 모델을 사용하려면 응용 프로그램이 이 메서드를 재정의해야
      합니다.


"urllib.request" 제약 사항
==========================

* 현재, 다음과 같은 프로토콜만 지원됩니다: HTTP (버전 0.9와 1.0), FTP,
  로컬 파일 및 데이터 URL.

  버전 3.4에서 변경: 데이터 URL에 대한 지원이 추가되었습니다.

* "urlretrieve()"의 캐싱 기능은 누군가가 만료 시간 헤더의 적절한 처리
  를 해킹할 시간을 찾을 때까지 비활성화되었습니다.

* 특정 URL이 캐시에 있는지를 조회하는 함수가 있어야 합니다.

* 이전 버전과의 호환성을 위해, URL이 로컬 파일을 가리키는 것으로 보이
  지만 파일을 열 수 없으면, FTP 프로토콜을 사용하여 URL을 다시 해석합
  니다. 이로 인해 때때로 혼란스러운 에러 메시지가 발생할 수 있습니다.

* The "urlopen()" and "urlretrieve()" functions can cause arbitrarily
  long delays while waiting for a network connection to be set up.
  This means that it is difficult to build an interactive web client
  using these functions without using threads.

* "urlopen()"이나 "urlretrieve()"가 반환한 데이터는 서버가 반환한 원시
  데이터입니다. 바이너리 데이터 (가령 이미지), 평문 텍스트 또는 (예를
  들어) HTML일 수 있습니다. HTTP 프로토콜은 응답 헤더에 유형 정보를 제
  공하는데, *Content-Type* 헤더를 통해 검사할 수 있습니다. 반환된 데이
  터가 HTML이면, "html.parser" 모듈을 사용하여 구문 분석할 수 있습니다
  .

* FTP 프로토콜을 처리하는 코드는 파일과 디렉터리를 구별할 수 없습니다.
  이는 액세스 할 수 없는 파일을 가리키는 URL을 읽으려고 할 때 예기치
  않은 동작을 일으킬 수 있습니다. URL이 "/"로 끝나면, 디렉터리를 참조
  하는 것으로 간주하고 그에 따라 처리됩니다. 그러나 파일을 읽으려는 시
  도가 550 에러를 일으키면 (URL을 찾을 수 없거나 액세스할 수 없다는 뜻
  인데, 종종 권한 문제입니다), URL이 디렉터리를 지정하지만, 후행 "/"를
  붙이지 않은 경우를 처리하기 위해 경로가 디렉터리로 처리됩니다. 이는
  읽기 권한이 액세스할 수 없도록 지정된 파일을 가져오려고 시도할 때 잘
  못된 결과를 만들 수 있도록 합니다; FTP 코드가 이를 읽으려고 시도하고
  , 550 에러로 실패한 다음, 읽을 수 없는 파일에 대해 디렉터리 리스팅을
  수행합니다. 세밀한 제어가 필요하면, "ftplib" 모듈 사용,
  "FancyURLopener" 서브 클래싱 또는 필요에 맞게 *_urlopener*를 변경하
  는 것을 고려하십시오.


"urllib.response" --- urllib가 사용하는 응답 클래스
***************************************************

"urllib.response" 모듈은 "read()"와 "readline()"을 포함하여 최소한의
파일류 인터페이스를 정의하는 함수와 클래스를 정의합니다. 이 모듈에 의
해 정의된 함수는 "urllib.request" 모듈에 의해 내부적으로 사용됩니다.
일반적인 응답 객체는 "urllib.response.addinfourl" 인스턴스입니다:

class urllib.response.addinfourl

   url

      가져온 자원의 URL, 일반적으로 리디렉션을 따라갔는지 판별하는 데
      사용됩니다.

   headers

      "EmailMessage" 인스턴스 형식으로 응답의 헤더를 반환합니다.

   status

      버전 3.9에 추가.

      서버가 반환한 상태 코드.

   geturl()

      버전 3.9부터 폐지: 폐지되었고 "url"로 대체되었습니다.

   info()

      버전 3.9부터 폐지: 폐지되었고 "headers"로 대체되었습니다.

   code

      버전 3.9부터 폐지: 폐지되었고 "status"로 대체되었습니다.

   getcode()

      버전 3.9부터 폐지: 폐지되었고 "status"로 대체되었습니다.
