"urllib.parse" --- URL을 구성 요소로 구문 분석
**********************************************

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

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

이 모듈은 URL(Uniform Resource Locator) 문자열을 구성 요소(주소 지정
체계, 네트워크 위치, 경로 등)로 분리하고, 구성 요소를 다시 URL 문자열
로 결합하고, "상대 URL"을 주어진 "기본 URL"에 따라 절대 URL로 변환하는
표준 인터페이스를 정의합니다.

이 모듈은 상대 URL(Relative Uniform Resource Locators)의 인터넷 RFC와
일치하도록 설계되었습니다. 다음과 같은 URL 스킴을 지원합니다: "file",
"ftp", "gopher", "hdl", "http", "https", "imap", "itms-services",
"mailto", "mms", "news", "nntp", "prospero", "rsync", "rtsp", "rtsps",
"rtspu", "sftp", "shttp", "sip", "sips", "snews", "svn", "svn+ssh",
"telnet", "wais", "ws", "wss".

**CPython 구현 상세:** The inclusion of the "itms-services" URL scheme
can prevent an app from passing Apple's App Store review process for
the macOS and iOS App Stores. Handling for the "itms-services" scheme
is always removed on iOS; on macOS, it *may* be removed if CPython has
been built with the "--with-app-store-compliance" option.

"urllib.parse" 모듈은 두 가지 넓은 범주에 속하는 함수들을 정의합니다:
URL 구문 분석과 URL 인용(quoting). 이에 대해서는 다음 섹션에서 자세히
설명합니다.

This module's functions use the deprecated term "netloc" (or
"net_loc"), which was introduced in **RFC 1808**. However, this term
has been obsoleted by **RFC 3986**, which introduced the term
"authority" as its replacement. The use of "netloc" is continued for
backward compatibility.


URL 구문 분석
=============

URL 구문 분석 함수는 URL 문자열을 구성 요소로 분할하거나 URL 구성 요소
를 URL 문자열로 결합하는 데 중점을 둡니다.

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)

   URL을 6개의 구성 요소로 구문 분석하여, 6개 항목 *네임드 튜플*을 반
   환합니다. 이는 URL의 일반적인 구조에 해당합니다:
   "scheme://netloc/path;parameters?query#fragment". 각 튜플 항목은 문
   자열이며 비어있을 수 있습니다. 구성 요소는 더 작은 부분으로 나뉘지
   않으며 (예를 들어 네트워크 위치는 단일 문자열입니다), % 이스케이프
   는 확장되지 않습니다. 위에 표시된 분리 문자는 *path* 구성 요소의 선
   행 슬래시를 제외하고는 결과의 일부가 아니며 존재하면 유지됩니다. 예
   를 들면:

      >>> from urllib.parse import urlparse
      >>> urlparse("scheme://netloc/path;parameters?query#fragment")
      ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
                  query='query', fragment='fragment')
      >>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
      ...              "highlight=params#url-parsing")
      >>> o
      ParseResult(scheme='http', netloc='docs.python.org:80',
                  path='/3/library/urllib.parse.html', params='',
                  query='highlight=params', fragment='url-parsing')
      >>> o.scheme
      'http'
      >>> o.netloc
      'docs.python.org:80'
      >>> o.hostname
      'docs.python.org'
      >>> o.port
      80
      >>> o._replace(fragment="").geturl()
      'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'

   **RFC 1808**의 문법 명세에 따라, urlparse는 '//' 로 올바르게 도입되
   었을 때만 netloc을 인식합니다. 그렇지 않으면 입력은 상대 URL인 것으
   로 간주하고 path 구성 요소로 시작합니다.

      >>> from urllib.parse import urlparse
      >>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
      ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
                  params='', query='', fragment='')
      >>> urlparse('www.cwi.nl/%7Eguido/Python.html')
      ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
                  params='', query='', fragment='')
      >>> urlparse('help/Python.html')
      ParseResult(scheme='', netloc='', path='help/Python.html', params='',
                  query='', fragment='')

   *scheme* 인자는 URL이 지정하지 않은 경우에만 사용될 기본 주소 지정
   체계를 제공합니다. 기본값 "''"가 항상 허용되고 필요하면 자동으로
   "b''"로 변환된다는 점을 제외하고, *urlstring*과 같은 형(텍스트나 바
   이트열)이어야 합니다.

   *allow_fragments* 인자가 거짓이면, 프래그먼트 식별자는 인식되지 않
   습니다. 대신, path, parameters 또는 query 구성 요소의 일부로 구문
   분석되고 "fragment"는 반환 값에서 빈 문자열로 설정됩니다.

   반환 값은 *네임드 튜플*입니다. 즉, 다음과 같은 인덱스나 이름있는 어
   트리뷰트로 해당 항목에 액세스 할 수 있습니다:

   +--------------------+---------+---------------------------+--------------------------+
   | 어트리뷰트         | 인덱스  | 값                        | 존재하지 않을 때의 값    |
   |====================|=========|===========================|==========================|
   | "scheme"           | 0       | URL 스킴 지정자           | *scheme* 매개 변수       |
   +--------------------+---------+---------------------------+--------------------------+
   | "netloc"           | 1       | 네트워크 위치 부분        | 빈 문자열                |
   +--------------------+---------+---------------------------+--------------------------+
   | "path"             | 2       | 계층적 경로               | 빈 문자열                |
   +--------------------+---------+---------------------------+--------------------------+
   | "params"           | 3       | 마지막 경로 요소의 파라미 | 빈 문자열                |
   |                    |         | 터                        |                          |
   +--------------------+---------+---------------------------+--------------------------+
   | "query"            | 4       | 쿼리 구성 요소            | 빈 문자열                |
   +--------------------+---------+---------------------------+--------------------------+
   | "fragment"         | 5       | 프래그먼트 식별자         | 빈 문자열                |
   +--------------------+---------+---------------------------+--------------------------+
   | "username"         |         | 사용자 이름               | "None"                   |
   +--------------------+---------+---------------------------+--------------------------+
   | "password"         |         | 비밀번호                  | "None"                   |
   +--------------------+---------+---------------------------+--------------------------+
   | "hostname"         |         | 호스트 이름 (소문자)      | "None"                   |
   +--------------------+---------+---------------------------+--------------------------+
   | "port"             |         | 존재하면, 정수로 표시되는 | "None"                   |
   |                    |         | 포트 번호                 |                          |
   +--------------------+---------+---------------------------+--------------------------+

   URL에 잘못된 포트가 지정된 경우 "port" 어트리뷰트를 읽으면
   "ValueError"가 발생합니다. 결과 객체에 대한 자세한 내용은 구조화된
   구문 분석 결과 섹션을 참조하십시오.

   "netloc" 어트리뷰트에서 대괄호(square brackets)가 일치하지 않으면
   "ValueError"가 발생합니다.

   (IDNA 인코딩에서 사용되는) NFKC 정규화에서 "/", "?", "#", "@" 또는
   ":" 중 하나로 분해(decompose)되는 "netloc" 어트리뷰트의 문자는
   "ValueError"를 발생시킵니다. 구문 분석하기 전에 URL이 분해
   (decompose)되면, 에러가 발생하지 않습니다.

   모든 네임드 튜플의 경우와 마찬가지로, 서브 클래스는 특히 유용한 몇
   가지 추가 메서드와 어트리뷰트를 갖습니다. 그러한 메서드 중 하나는
   "_replace()"입니다. "_replace()" 메서드는 지정된 필드를 새로운 값으
   로 대체한 새로운 ParseResult 객체를 반환합니다.

      >>> from urllib.parse import urlparse
      >>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
      >>> u
      ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
                  params='', query='', fragment='')
      >>> u._replace(scheme='http')
      ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
                  params='', query='', fragment='')

   경고:

     "urlparse()" does not perform validation.  See URL parsing
     security for details.

   버전 3.2에서 변경: IPv6 URL 구문 분석 기능이 추가되었습니다.

   버전 3.3에서 변경: **RFC 3986**에 따라, 프래그먼트는 이제 모든 URL
   스킴에 대해 구문 분석됩니다 (*allow_fragments*가 거짓이 아니라면).
   이전에는, 프래그먼트를 지원하는 스킴의 수락 목록이 있었습니다.

   버전 3.6에서 변경: 범위를 벗어난 포트 번호는 이제 "None"을 반환하는
   대신 "ValueError"를 발생시킵니다.

   버전 3.8에서 변경: NFKC 정규화에서 netloc 구문 분석에 영향을 주는
   문자는 이제 "ValueError"를 발생시킵니다.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

   문자열 인자(*application/x-www-form-urlencoded* 유형의 데이터)로 제
   공된 쿼리 문자열을 구문 분석합니다. 데이터는 딕셔너리로 반환됩니다.
   딕셔너리 키는 고유한 쿼리 변수 이름이고 값은 각 이름의 값 리스트입
   니다.

   선택적 인자 *keep_blank_values*는 퍼센트 인코딩된 쿼리의 빈 값을 빈
   문자열로 처리해야 하는지를 나타내는 플래그입니다. 참값은 빈 값을 빈
   문자열로 유지해야 함을 나타냅니다. 기본 거짓 값은 빈 값이 무시되고
   포함되지 않은 것처럼 처리됨을 나타냅니다.

   선택적 인자 *strict_parsing*은 구문 분석 에러 시 수행할 작업을 나타
   내는 플래그입니다. 거짓(기본값)이면, 에러가 조용히 무시됩니다. 참이
   면, 에러는 "ValueError" 예외를 발생시킵니다.

   선택적 *encoding*과 *errors* 매개 변수는 "bytes.decode()" 메서드에
   서 받아들이는 것처럼 퍼센트 인코딩된 시퀀스를 유니코드 문자로 디코
   딩하는 방법을 지정합니다.

   선택적 인자 *max_num_fields*는 읽을 최대 필드 수입니다. 설정되면,
   *max_num_fields* 필드보다 많은 것을 읽을 때 "ValueError"가 발생합니
   다.

   선택적 인자 *separator*는 쿼리 인자를 구분하는 데 사용할 기호입니다
   . 기본값은 "&"입니다.

   이러한 딕셔너리를 쿼리 문자열로 변환하려면
   "urllib.parse.urlencode()" 함수를 ("doseq" 매개 변수를 "True"로 설
   정해서) 사용하십시오.

   버전 3.2에서 변경: *encoding*과 *errors* 매개 변수를 추가합니다.

   버전 3.8에서 변경: *max_num_fields* 매개 변수를 추가했습니다.

   버전 3.10에서 변경: 기본값이 "&" 인 *separator* 매개 변수를 추가했
   습니다. 파이썬 3.10 이전의 파이썬 버전에서는 쿼리 매개 변수 구분 기
   호로 ";"와 "&"를 모두 사용할 수 있었습니다. "&"를 기본 구분자 기호
   로 사용하여, 단일 구분자 키만 허용하도록 변경되었습니다.

   버전 3.14부터 폐지됨: Accepting objects with false values (like "0"
   and "[]") except empty strings and byte-like objects and "None" is
   now deprecated.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

   문자열 인자(*application/x-www-form-urlencoded* 유형의 데이터)로 제
   공된 쿼리 문자열을 구문 분석합니다. 데이터는 이름, 값 쌍의 리스트로
   반환됩니다.

   선택적 인자 *keep_blank_values*는 퍼센트 인코딩된 쿼리의 빈 값을 빈
   문자열로 처리해야 하는지를 나타내는 플래그입니다. 참값은 빈 값을 빈
   문자열로 유지해야 함을 나타냅니다. 기본 거짓 값은 빈 값이 무시되고
   포함되지 않은 것처럼 처리됨을 나타냅니다.

   선택적 인자 *strict_parsing*은 구문 분석 에러 시 수행할 작업을 나타
   내는 플래그입니다. 거짓(기본값)이면, 에러가 조용히 무시됩니다. 참이
   면, 에러는 "ValueError" 예외를 발생시킵니다.

   선택적 *encoding*과 *errors* 매개 변수는 "bytes.decode()" 메서드에
   서 받아들이는 것처럼 퍼센트 인코딩된 시퀀스를 유니코드 문자로 디코
   딩하는 방법을 지정합니다.

   선택적 인자 *max_num_fields*는 읽을 최대 필드 수입니다. 설정되면,
   *max_num_fields* 필드보다 많은 것을 읽을 때 "ValueError"가 발생합니
   다.

   선택적 인자 *separator*는 쿼리 인자를 구분하는 데 사용할 기호입니다
   . 기본값은 "&"입니다.

   이러한 쌍의 리스트를 쿼리 문자열로 변환하려면
   "urllib.parse.urlencode()" 함수를 사용하십시오.

   버전 3.2에서 변경: *encoding*과 *errors* 매개 변수를 추가합니다.

   버전 3.8에서 변경: *max_num_fields* 매개 변수를 추가했습니다.

   버전 3.10에서 변경: 기본값이 "&" 인 *separator* 매개 변수를 추가했
   습니다. 파이썬 3.10 이전의 파이썬 버전에서는 쿼리 매개 변수 구분 기
   호로 ";"와 "&"를 모두 사용할 수 있었습니다. "&"를 기본 구분자 기호
   로 사용하여, 단일 구분자 키만 허용하도록 변경되었습니다.

urllib.parse.urlunparse(parts)

   "urlparse()"에 의해 반환된 튜플에서 URL을 구성합니다. *parts* 인자
   는 임의의 6개 항목 이터러블일 수 있습니다. 구문 분석된 원래 URL에
   불필요한 구분자가 있는 경우 (예를 들어 비어있는 쿼리가 있는 "?";
   RFC는 이들이 동등하다고 말합니다) 약간 다르지만 동등한 URL이 만들어
   질 수 있습니다.

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)

   이것은 "urlparse()"와 유사하지만, URL에서 파라미터를 분할하지 않습
   니다. URL의 *path* 부분의 각 세그먼트에 파라미터를 적용할 수 있는
   최신 URL 문법(**RFC 2396**을 참조하십시오)이 필요하면 일반적으로
   "urlparse()" 대신 사용해야 합니다. 경로 세그먼트와 파라미터를 분리
   하려면 별도의 함수가 필요합니다. 이 함수는 5개 항목 *네임드 튜플*을
   반환합니다:

      (addressing scheme, network location, path, query, fragment identifier).

   반환 값은 *네임드 튜플*입니다, 항목은 인덱스나 이름 붙은 어트리뷰트
   로 액세스 할 수 있습니다:

   +--------------------+---------+---------------------------+------------------------+
   | 어트리뷰트         | 인덱스  | 값                        | 존재하지 않을 때의 값  |
   |====================|=========|===========================|========================|
   | "scheme"           | 0       | URL 스킴 지정자           | *scheme* 매개 변수     |
   +--------------------+---------+---------------------------+------------------------+
   | "netloc"           | 1       | 네트워크 위치 부분        | 빈 문자열              |
   +--------------------+---------+---------------------------+------------------------+
   | "path"             | 2       | 계층적 경로               | 빈 문자열              |
   +--------------------+---------+---------------------------+------------------------+
   | "query"            | 3       | 쿼리 구성 요소            | 빈 문자열              |
   +--------------------+---------+---------------------------+------------------------+
   | "fragment"         | 4       | 프래그먼트 식별자         | 빈 문자열              |
   +--------------------+---------+---------------------------+------------------------+
   | "username"         |         | 사용자 이름               | "None"                 |
   +--------------------+---------+---------------------------+------------------------+
   | "password"         |         | 비밀번호                  | "None"                 |
   +--------------------+---------+---------------------------+------------------------+
   | "hostname"         |         | 호스트 이름 (소문자)      | "None"                 |
   +--------------------+---------+---------------------------+------------------------+
   | "port"             |         | 존재하면, 정수로 표시되는 | "None"                 |
   |                    |         | 포트 번호                 |                        |
   +--------------------+---------+---------------------------+------------------------+

   URL에 잘못된 포트가 지정된 경우 "port" 어트리뷰트를 읽으면
   "ValueError"가 발생합니다. 결과 객체에 대한 자세한 내용은 구조화된
   구문 분석 결과 섹션을 참조하십시오.

   "netloc" 어트리뷰트에서 대괄호(square brackets)가 일치하지 않으면
   "ValueError"가 발생합니다.

   (IDNA 인코딩에서 사용되는) NFKC 정규화에서 "/", "?", "#", "@" 또는
   ":" 중 하나로 분해(decompose)되는 "netloc" 어트리뷰트의 문자는
   "ValueError"를 발생시킵니다. 구문 분석하기 전에 URL이 분해
   (decompose)되면, 에러가 발생하지 않습니다.

   Following some of the WHATWG spec that updates RFC 3986, leading C0
   control and space characters are stripped from the URL. "\n", "\r"
   and tab "\t" characters are removed from the URL at any position.

   경고:

     "urlsplit()" does not perform validation.  See URL parsing
     security for details.

   버전 3.6에서 변경: 범위를 벗어난 포트 번호는 이제 "None"을 반환하는
   대신 "ValueError"를 발생시킵니다.

   버전 3.8에서 변경: NFKC 정규화에서 netloc 구문 분석에 영향을 주는
   문자는 이제 "ValueError"를 발생시킵니다.

   버전 3.10에서 변경: ASCII newline and tab characters are stripped
   from the URL.

   버전 3.12에서 변경: Leading WHATWG C0 control and space characters
   are stripped from the URL.

urllib.parse.urlunsplit(parts)

   "urlsplit()"에 의해 반환된 튜플 요소를 완전한 URL 문자열로 결합합니
   다. *parts* 인자는 임의의 5개 항목 이터러블일 수 있습니다. 구문 분
   석된 원래 URL에 불필요한 구분자가 있는 경우 (예를 들어 비어있는 쿼
   리가 있는 ?; RFC는 이들이 동등하다고 말합니다) 약간 다르지만 동등한
   URL이 만들어질 수 있습니다.

urllib.parse.urljoin(base, url, allow_fragments=True)

   "기본 URL"(*base*)을 다른 URL(*url*)과 결합하여 전체 ("절대") URL을
   구성합니다. 비형식적으로, 이것은 기본 URL의 구성 요소, 특히 주소 지
   정 체계, 네트워크 위치 및 경로(의 일부)를 사용하여 상대 URL에 누락
   된 구성 요소를 제공합니다. 예를 들면:

   >>> from urllib.parse import urljoin
   >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
   'http://www.cwi.nl/%7Eguido/FAQ.html'

   *allow_fragments* 인자는 "urlparse()"와 같은 의미와 기본값을 갖습니
   다.

   참고:

     *url*이 절대 URL이면 (즉, "//"나 "scheme://"로 시작하면), *url*의
     호스트명 및/또는 스킴이 결과에 나타납니다. 예를 들면:

        >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
        ...         '//www.python.org/%7Eguido')
        'http://www.python.org/%7Eguido'

     이런 동작을 원하지 않으면, *url*을 "urlsplit()"과 "urlunsplit()"
     으로 사전 처리하여 가능한 *scheme*과 *netloc* 부분을 제거하십시오
     .

   경고:

     Because an absolute URL may be passed as the "url" parameter, it
     is generally **not secure** to use "urljoin" with an attacker-
     controlled "url". For example in,
     "urljoin("https://website.com/users/", username)", if "username"
     can contain an absolute URL, the result of "urljoin" will be the
     absolute URL.

   버전 3.5에서 변경: **RFC 3986**에 정의된 의미론과 일치하도록 동작이
   갱신되었습니다.

urllib.parse.urldefrag(url)

   *url*에 프래그먼트 식별자가 포함되면, 프래그먼트 식별자 없는 *url*
   의 수정된 버전과 프래그먼트 식별자를 별도의 문자열로 반환합니다.
   *url*에 프래그먼트 식별자가 없으면, 수정되지 않은 *url*과 빈 문자열
   을 반환합니다.

   반환 값은 *네임드 튜플*입니다, 항목은 인덱스나 이름 붙은 어트리뷰트
   로 액세스 할 수 있습니다:

   +--------------------+---------+---------------------------+------------------------+
   | 어트리뷰트         | 인덱스  | 값                        | 존재하지 않을 때의 값  |
   |====================|=========|===========================|========================|
   | "url"              | 0       | 프래그먼트 없는 URL       | 빈 문자열              |
   +--------------------+---------+---------------------------+------------------------+
   | "fragment"         | 1       | 프래그먼트 식별자         | 빈 문자열              |
   +--------------------+---------+---------------------------+------------------------+

   결과 객체에 대한 자세한 정보는 섹션 구조화된 구문 분석 결과를 참조
   하십시오.

   버전 3.2에서 변경: 결과는 단순한 2-튜플이 아닌 구조화된 객체입니다.

urllib.parse.unwrap(url)

   래핑 된 URL(즉, "<URL:scheme://host/path>", "<scheme://host/path>",
   "URL:scheme://host/path" 또는 "scheme://host/path" 형식의 문자열)에
   서 URL을 추출합니다. *url*이 래핑 된 URL이 아니면, 변경 없이 반환됩
   니다.


URL 구문 분석 보안
==================

The "urlsplit()" and "urlparse()" APIs do not perform **validation**
of inputs.  They may not raise errors on inputs that other
applications consider invalid.  They may also succeed on some inputs
that might not be considered URLs elsewhere.  Their purpose is for
practical functionality rather than purity.

Instead of raising an exception on unusual input, they may instead
return some component parts as empty strings. Or components may
contain more than perhaps they should.

We recommend that users of these APIs where the values may be used
anywhere with security implications code defensively. Do some
verification within your code before trusting a returned component
part.  Does that "scheme" make sense?  Is that a sensible "path"?  Is
there anything strange about that "hostname"?  etc.

What constitutes a URL is not universally well defined.  Different
applications have different needs and desired constraints.  For
instance the living WHATWG spec describes what user facing web clients
such as a web browser require. While **RFC 3986** is more general.
These functions incorporate some aspects of both, but cannot be
claimed compliant with either.  The APIs and existing user code with
expectations on specific behaviors predate both standards leading us
to be very cautious about making API behavior changes.


ASCII로 인코딩된 바이트열 구문 분석
===================================

URL 구문 분석 함수는 원래 문자열에서만 작동하도록 설계되었습니다. 실제
로는, 적절히 인용되고 인코딩된 URL을 ASCII 바이트 시퀀스로 조작할 수
있으면 유용합니다. 따라서, 이 모듈의 URL 구문 분석 함수는 모두 "str"
객체 외에 "bytes"와 "bytearray" 객체에서 작동합니다.

"str" 데이터가 전달되면, 결과에는 "str" 데이터만 포함됩니다. "bytes"나
"bytearray" 데이터가 전달되면, 결과에는 "bytes" 데이터만 포함됩니다.

단일 함수 호출에서 "str" 데이터를 "bytes"나 "bytearray"와 혼합하려고
시도하면 "TypeError"가 발생하는 반면, 비 ASCII 바이트 값을 전달하면
"UnicodeDecodeError"가 트리거 됩니다.

"str"과 "bytes" 간에 결과 객체를 쉽게 변환 할 수 있도록, URL 구문 분석
함수의 모든 반환 값은 "encode()" 메서드(결과에 "str" 데이터가 포함될
때)나 "decode()" 메서드(결과에 "bytes" 데이터가 포함될 때)를 제공합니
다. 이러한 메서드의 서명은 해당 "str"와 "bytes" 메서드의 서명과 일치합
니다 (기본 인코딩이 "'utf-8'"가 아니라 "'ascii'"라는 점은 예외입니다).
각각은 "bytes" 데이터("encode()" 메서드의 경우)나 "str" 데이터
("decode()" 메서드의 경우)를 포함하는 해당 형의 값을 생성합니다.

ASCII가 아닌 데이터를 포함할 수 있는 잘못 인용된 URL에서 작동할 가능성
이 있는 응용 프로그램은 URL 구문 분석 메서드를 호출하기 전에 바이트열
에서 문자로 자체 디코딩을 수행할 필요가 있습니다.

이 섹션에서 설명하는 동작은 URL 구문 분석 함수에만 적용됩니다. URL 인
용 함수는 개별 URL 인용 함수의 설명서에 기술된 대로 바이트 시퀀스를 생
성하거나 소비할 때 자체 규칙을 사용합니다.

버전 3.2에서 변경: URL 구문 분석 함수는 이제 ASCII 인코딩된 바이트 시
퀀스를 받아들입니다.


구조화된 구문 분석 결과
=======================

"urlparse()", "urlsplit()" 및 "urldefrag()" 함수의 결과 객체는 "tuple"
형의 서브 클래스입니다. 이 서브 클래스는 해당 함수에 대한 설명서에 나
열된 어트리뷰트, 이전 섹션에서 설명한 인코딩과 디코딩 지원 및 추가 메
서드를 추가합니다:

urllib.parse.SplitResult.geturl()

   원래 URL의 재결합된 버전을 문자열로 반환합니다. 스킴이 소문자로 정
   규화되고 빈 구성 요소가 삭제될 수 있다는 점에서 원래 URL과 다를 수
   있습니다. 특히, 빈 파라미터, 쿼리 및 프래그먼트 식별자가 제거됩니다
   .

   "urldefrag()" 결과의 경우, 빈 프래그먼트 식별자만 제거됩니다.
   "urlsplit()"과 "urlparse()" 결과의 경우, 이 메서드가 반환한 URL에
   대해 언급된 모든 변경 사항이 적용됩니다.

   이 메서드의 결과는 원래 구문 분석 함수를 통해 다시 전달될 때 변경되
   지 않은 상태로 유지됩니다:

   >>> from urllib.parse import urlsplit
   >>> url = 'HTTP://www.Python.org/doc/#'
   >>> r1 = urlsplit(url)
   >>> r1.geturl()
   'http://www.Python.org/doc/'
   >>> r2 = urlsplit(r1.geturl())
   >>> r2.geturl()
   'http://www.Python.org/doc/'

다음 클래스는 "str" 객체에서 작동할 때 구조화된 구문 분석 결과의 구현
을 제공합니다:

class urllib.parse.DefragResult(url, fragment)

   "str" 데이터를 포함하는 "urldefrag()" 결과의 구상 클래스.
   "encode()" 메서드는 "DefragResultBytes" 인스턴스를 반환합니다.

   Added in version 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

   "str" 데이터를 포함하는 "urlparse()" 결과의 구상 클래스. "encode()"
   메서드는 "ParseResultBytes" 인스턴스를 반환합니다.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

   "str" 데이터를 포함하는 "urlsplit()" 결과의 구상 클래스. "encode()"
   메서드는 "SplitResultBytes" 인스턴스를 반환합니다.

다음 클래스는 "bytes"나 "bytearray" 객체에서 작동할 때 구문 분석 결과
의 구현을 제공합니다:

class urllib.parse.DefragResultBytes(url, fragment)

   "bytes" 데이터를 포함하는 "urldefrag()" 결과의 구상 클래스.
   "decode()" 메서드는 "DefragResult" 인스턴스를 반환합니다.

   Added in version 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

   "bytes" 데이터를 포함하는 "urlparse()" 결과의 구상 클래스.
   "decode()" 메서드는 "ParseResult" 인스턴스를 반환합니다.

   Added in version 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

   "bytes" 데이터를 포함하는 "urlsplit()" 결과의 구상 클래스.
   "decode()" 메서드는 "SplitResult" 인스턴스를 반환합니다.

   Added in version 3.2.


URL 인용
========

URL 인용(quoting) 함수는 특수 문자를 인용하고 비 ASCII 텍스트를 적절히
인코딩하여 프로그램 데이터를 취해서 URL 구성 요소로 안전하게 사용할 수
있도록 하는 데 중점을 둡니다. 또한 해당 작업이 위의 URL 구문 분석 함수
로 처리되지 않는 경우 URL 구성 요소의 내용에서 원래 데이터를 다시 만들
기 위해 이러한 작업을 뒤집는 것도 지원합니다.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

   "%*xx*" 이스케이프를 사용하여 *string*의 특수 문자를 치환합니다. 글
   자, 숫자 및 문자 "'_.-~'"는 절대 인용되지 않습니다. 기본적으로, 이
   함수는 URL의 경로 섹션을 인용하기 위한 것입니다. 선택적 *safe* 매개
   변수는 인용해서는 안 되는 추가 ASCII 문자를 지정합니다 --- 기본값은
   "'/'"입니다.

   *string*은 "str"이나 "bytes" 객체일 수 있습니다.

   버전 3.7에서 변경: URL 문자열 인용을 **RFC 2396**에서 **RFC 3986**
   으로 옮겼습니다. "~"는 이제 예약되지 않은 문자 집합에 포함됩니다.

   선택적 *encoding*과 *errors* 매개 변수는 "str.encode()" 메서드에서
   받아들이는 것처럼 비 ASCII 문자를 처리하는 방법을 지정합니다.
   *encoding*의 기본값은 "'utf-8'"입니다. *errors*의 기본값은
   "'strict'"로, 지원되지 않는 문자는 "UnicodeEncodeError"를 발생시킴
   을 의미합니다. *string*이 "bytes"이면 *encoding*과 *errors*를 제공
   해서는 안 됩니다, 그렇지 않으면 "TypeError"가 발생합니다.

   "quote(string, safe, encoding, errors)"는
   "quote_from_bytes(string.encode(encoding, errors), safe)"와 동등함
   에 유의하십시오.

   예: "quote('/El Niño/')"는 "'/El%20Ni%C3%B1o/'"를 산출합니다.

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)

   "quote()"와 유사하지만, URL로 이동하기 위한 쿼리 문자열을 만들 때
   HTML 폼값을 인용하는 데 필요한 대로 스페이스를 더하기 부호로 치환하
   기도 합니다. *safe*에 포함되지 않으면 원래 문자열의 더하기 부호가
   이스케이프 됩니다. 또한 *safe*의 기본값은 "'/'"가 아닙니다.

   예: "quote_plus('/El Niño/')"는 "'%2FEl+Ni%C3%B1o%2F'"를 산출합니다
   .

urllib.parse.quote_from_bytes(bytes, safe='/')

   "quote()"와 유사하지만, "str" 대신 "bytes" 객체를 받아들이고, 문자
   열을 바이트열로 인코딩하지 않습니다.

   예: "quote_from_bytes(b'a&\xef')"는 "'a%26%EF'"를 산출합니다.

urllib.parse.unquote(string, encoding='utf-8', errors='replace')

   "%*xx*" 이스케이프를 동등한 단일 문자로 대체합니다. 선택적
   *encoding*과 *errors* 매개 변수는 "bytes.decode()" 메서드에서 받아
   들이는 것처럼 퍼센트 인코딩된 시퀀스를 유니코드 문자로 디코딩하는
   방법을 지정합니다.

   *string*은 "str"이나 "bytes" 객체일 수 있습니다.

   *encoding*의 기본값은 "'utf-8'"입니다. *errors*의 기본값은
   "'replace'"로, 유효하지 않은 시퀀스는 자리 표시자 문자(placeholder
   character)로 대체됩니다.

   예: "unquote('/El%20Ni%C3%B1o/')"는 "'/El Niño/'"를 산출합니다.

   버전 3.9에서 변경: *string* 매개 변수는 바이트열과 문자열 객체를 지
   원합니다 (이전에는 문자열만 지원했습니다).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

   "unquote()"와 유사하지만, HTML 폼값을 인용 해제할 때 요구되는 것처
   럼, 더하기 부호를 스페이스로 치환하기도 합니다.

   *string*은 "str"이어야 합니다.

   예: "unquote_plus('/El+Ni%C3%B1o/')"는 "'/El Niño/'"를 산출합니다.

urllib.parse.unquote_to_bytes(string)

   "%*xx*" 이스케이프를 해당 단일 옥텟(octet)으로 대체하고, "bytes" 객
   체를 반환합니다.

   *string*은 "str"이나 "bytes" 객체일 수 있습니다.

   "str"이면, *string*의 이스케이프 되지 않은 비 ASCII 문자는 UTF-8 바
   이트열로 인코딩됩니다.

   예: "unquote_to_bytes('a%26%EF')"는 "b'a&\xef'"를 산출합니다.

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)

   "str"이나 "bytes" 객체를 포함할 수 있는 매핑 객체나 두 요소 튜플의
   시퀀스를 퍼센트 인코딩된 ASCII 텍스트 문자열로 변환합니다. 결과 문
   자열을 "urlopen()" 함수를 사용하여 POST 연산을 위한 *data*로 사용하
   려면, 바이트열로 인코딩해야 합니다, 그렇지 않으면 "TypeError"가 발
   생합니다.

   결과 문자열은 "'&'" 문자로 구분된 일련의 "key=value" 쌍이고, 여기서
   *key*와 *value*는 *quote_via* 함수를 사용하여 인용됩니다. 기본적으
   로, "quote_plus()"가 값을 인용하는 데 사용되는데, 스페이스는 "'+'"
   문자로 인용되고 '/' 문자는 "%2F"로 인코딩되어 GET 요청 표준
   ("application/x-www-form-urlencoded")을 따름을 뜻합니다.
   *quote_via*로 전달될 수 있는 대체 함수는 "quote()"이며, 스페이스를
   "%20"로 인코딩하고 '/' 문자를 인코딩하지 않습니다. 무엇을 인용할지
   를 최대한 제어하려면, "quote"를 사용하고 *safe*의 값을 지정하십시오
   .

   *query* 인자에 두 요소 튜플의 시퀀스가 사용될 때, 각 튜플의 첫 번째
   요소는 키이고 두 번째 요소는 값입니다. 값 요소 자체는 시퀀스일 수
   있으며, 이 경우 선택적 매개 변수 *doseq*가 "True"로 평가되면, "'&'"
   로 구분된 개별 "key=value" 쌍이 키에 대한 값 시퀀스의 각 요소에 대
   해 생성됩니다. 인코딩된 문자열의 파라미터 순서는 시퀀스의 파라미터
   튜플 순서와 일치합니다.

   *safe*, *encoding* 및 *errors* 매개 변수는 *quote_via*로 전달됩니다
   (*encoding*과 *errors* 매개 변수는 쿼리 요소가 "str"일 때만 전달됩
   니다).

   이 인코딩 프로세스를 뒤집기 위해, 쿼리 문자열을 파이썬 데이터 구조
   로 구문 분석하기 위해 이 모듈에서 "parse_qs()"와 "parse_qsl()"이 제
   공됩니다.

   "urllib.parse.urlencode()" 메서드를 사용하여 URL의 쿼리 문자열이나
   POST 요청의 데이터를 생성하는 방법을 알아보려면 urllib 예제를 참조
   하십시오.

   버전 3.2에서 변경: *query* 매개 변수는 바이트열과 문자열 객체를 지
   원합니다.

   버전 3.5에서 변경: *quote_via* 매개 변수를 추가했습니다.

   버전 3.14부터 폐지됨: Accepting objects with false values (like "0"
   and "[]") except empty strings and byte-like objects and "None" is
   now deprecated.

더 보기:

  WHATWG -  URL Living standard
     Working Group for the URL Standard that defines URLs, domains, IP
     addresses, the application/x-www-form-urlencoded format, and
     their API.

  **RFC 3986** - Uniform Resource Identifiers
     이것이 현재 표준입니다 (STD66). urllib.parse 모듈에 대한 모든 변
     경 사항은 이를 준수해야 합니다. 특정 편차가 관찰될 수 있는데, 이
     는 대부분 이전 버전과의 호환성과 주요 브라우저에서 일반적으로 관
     찰되는 사실상의 구문 분석 요구 사항을 위한 것입니다.

  **RFC 2732** - Format for Literal IPv6 Addresses in URL's.
     IPv6 URL의 구문 분석 요구 사항을 지정합니다.

  **RFC 2396** - Uniform Resource Identifiers (URI): Generic Syntax
     URN(Uniform Resource Names)과 URL(Uniform Resource Locator)에 대
     한 일반적인 문법 요구 사항을 설명하는 문서.

  **RFC 2368** - The mailto URL scheme.
     mailto URL 스킴에 대한 구문 분석 요구 사항.

  **RFC 1808** - Relative Uniform Resource Locators
     이 RFC는 경계 사례의 처리를 정의하는 꽤 많은 수의 "비정상적인 예"
     를 포함하여, 절대와 상대 URL을 결합하는 규칙을 포함합니다.

  **RFC 1738** - Uniform Resource Locators (URL)
     절대 URL의 형식 문법과 의미를 지정합니다.
