"webbrowser" --- 편리한 웹 브라우저 제어기
******************************************

**소스 코드:** Lib/webbrowser.py

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

The "webbrowser" module provides a high-level interface to allow
displaying web-based documents to users. Under most circumstances,
simply calling the "open()" function from this module will do the
right thing.

유닉스에서, X11에서는 그래픽 브라우저가 선호되지만, 그래픽 브라우저를
사용할 수 없거나 X11 디스플레이를 사용할 수 없으면 텍스트 모드 브라우
저가 사용됩니다. 텍스트 모드 브라우저가 사용되면, 사용자가 브라우저를
종료할 때까지 호출하는 프로세스가 블록 됩니다.

If the environment variable "BROWSER" exists, it is interpreted as the
"os.pathsep"-separated list of browsers to try ahead of the platform
defaults.  When the value of a list part contains the string "%s",
then it is interpreted as a literal browser command line to be used
with the argument URL substituted for "%s"; if the value is a single
word that refers to one of the already registered browsers this
browser is added to the front of the search list; if the part does not
contain "%s", it is simply interpreted as the name of the browser to
launch. [1]

버전 3.14에서 변경: The "BROWSER" variable can now also be used to
reorder the list of platform defaults. This is particularly useful on
macOS where the platform defaults do not refer to command-line tools
on "PATH".

유닉스가 아닌 플랫폼에서, 또는 유닉스에서 원격 브라우저를 사용할 수 있
을 때, 제어하는 프로세스는 사용자가 브라우저를 완료할 때까지 기다리지
않고, 원격 브라우저가 디스플레이에 자체 창을 유지하도록 허용합니다. 유
닉스에서 원격 브라우저를 사용할 수 없으면, 제어하는 프로세스가 새 브라
우저를 시작하고 기다랍니다.

On iOS, the "BROWSER" environment variable, as well as any arguments
controlling autoraise, browser preference, and new tab/window creation
will be ignored. Web pages will *always* be opened in the user's
preferred browser, in a new tab, with the browser being brought to the
foreground. The use of the "webbrowser" module on iOS requires the
"ctypes" module. If "ctypes" isn't available, calls to "open()" will
fail.


Command-line interface
======================

스크립트 **webbrowser**는 모듈의 명령 줄 인터페이스로 사용될 수 있습니
다. 인자로 URL을 받아들입니다. 다음과 같은 선택적 매개 변수를 받아들입
니다:

-n, --new-window

   가능하다면 새 브라우저 창에서 URL을 엽니다.

-t, --new-tab

   새 브라우저 탭에서 URL을 엽니다.

당연히, 이 옵션들은 상호 배타적입니다. 사용 예:

   python -m webbrowser -t "https://www.python.org"

가용성: not WASI, not Android.

다음 예외가 정의됩니다:

exception webbrowser.Error

   브라우저 제어 에러가 일어날 때 발생하는 예외.

다음 함수가 정의됩니다:

webbrowser.open(url, new=0, autoraise=True)

   기본 브라우저를 사용하여 *url*을 표시합니다. *new*가 0이면, 가능하
   다면 같은 브라우저 창에서 *url*이 열립니다. *new*가 1이면, 가능하다
   면 새 브라우저 창이 열립니다. *new*가 2이면, 가능하다면 새 브라우저
   페이지("탭")가 열립니다. *autoraise*가 "True"이면, 가능하다면 창을
   올립니다(raise) (이것은 많은 창 관리자에서 이 변수의 설정과 관계없
   이 일어납니다).

   Returns "True" if a browser was successfully launched, "False"
   otherwise.

   일부 플랫폼에서, 이 함수를 사용하여 파일명을 여는 것은 동작하고 운
   영 체제의 연결된 프로그램이 시작될 수 있습니다. 하지만, 이것은 지원
   되지도 이식성 있지도 않습니다.

   인자 "url"로 감사 이벤트(auditing event) "webbrowser.open"을 발생시
   킵니다.

webbrowser.open_new(url)

   가능하다면, 기본 브라우저의 새 창에서 *url*을 엽니다, 그렇지 않으면
   , 유일한 브라우저 창에서 *url*을 엽니다.

   Returns "True" if a browser was successfully launched, "False"
   otherwise.

webbrowser.open_new_tab(url)

   가능하다면, 기본 브라우저의 새 페이지("탭")에서 *url*을 엽니다, 그
   렇지 않으면 "open_new()"와 동등합니다.

   Returns "True" if a browser was successfully launched, "False"
   otherwise.

webbrowser.get(using=None)

   브라우저 유형 *using*에 대한 제어기 객체를 반환합니다. *using*이
   "None"이면, 호출자의 환경에 적합한 기본 브라우저을 위한 제어기 객체
   를 반환합니다.

webbrowser.register(name, constructor, instance=None, *, preferred=False)

   브라우저 유형 *name*을 등록합니다. 일단 브라우저 유형이 등록되면,
   "get()" 함수는 해당 브라우저 유형에 대한 제어기를 반환할 수 있습니
   다. *instance*가 제공되지 않거나, "None"이면, 필요할 때
   *constructor*가 매개 변수 없이 호출되어 인스턴스를 만듭니다.
   *instance*가 제공되면, *constructor*는 절대로 호출되지 않으며,
   "None"일 수 있습니다.

   *preferred*를 "True"로 설정하면 이 브라우저를 인자 없이 "get()"을
   호출할 때 선호되는 결과가 되도록 합니다. 그렇지 않으면, 이 엔트리
   포인트는 "BROWSER" 변수를 설정하거나 선언한 처리기의 이름과 일치하
   는 비어 있지 않은 인자로 "get()"을 호출하려는 경우에만 유용합니다.

   버전 3.7에서 변경: *preferred* 키워드 전용 매개 변수가 추가되었습니
   다.

여러 가지 브라우저 유형이 미리 정의되어 있습니다. 이 표는 "get()" 함수
로 전달될 수 있는 유형 이름과 제어기 클래스의 해당 인스턴스 화를 제공
합니다, 모두 이 모듈에서 정의됩니다.

+--------------------------+-------------------------------------------+---------+
| 유형 이름                | 클래스 이름                               | 노트    |
|==========================|===========================================|=========|
| "'mozilla'"              | "Mozilla('mozilla')"                      |         |
+--------------------------+-------------------------------------------+---------+
| "'firefox'"              | "Mozilla('mozilla')"                      |         |
+--------------------------+-------------------------------------------+---------+
| "'epiphany'"             | "Epiphany('epiphany')"                    |         |
+--------------------------+-------------------------------------------+---------+
| "'kfmclient'"            | "Konqueror()"                             | (1)     |
+--------------------------+-------------------------------------------+---------+
| "'konqueror'"            | "Konqueror()"                             | (1)     |
+--------------------------+-------------------------------------------+---------+
| "'kfm'"                  | "Konqueror()"                             | (1)     |
+--------------------------+-------------------------------------------+---------+
| "'opera'"                | "Opera()"                                 |         |
+--------------------------+-------------------------------------------+---------+
| "'links'"                | "GenericBrowser('links')"                 |         |
+--------------------------+-------------------------------------------+---------+
| "'elinks'"               | "Elinks('elinks')"                        |         |
+--------------------------+-------------------------------------------+---------+
| "'lynx'"                 | "GenericBrowser('lynx')"                  |         |
+--------------------------+-------------------------------------------+---------+
| "'w3m'"                  | "GenericBrowser('w3m')"                   |         |
+--------------------------+-------------------------------------------+---------+
| "'windows-default'"      | "WindowsDefault"                          | (2)     |
+--------------------------+-------------------------------------------+---------+
| "'macos'"                | "MacOS('default')"                        | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'safari'"               | "MacOS('safari')"                         | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'chrome'"               | "MacOS('google chrome')"                  | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'firefox'"              | "MacOS('firefox')"                        | (3)     |
+--------------------------+-------------------------------------------+---------+
| "'google-chrome'"        | "Chrome('google-chrome')"                 |         |
+--------------------------+-------------------------------------------+---------+
| "'chromium'"             | "Chromium('chromium')"                    |         |
+--------------------------+-------------------------------------------+---------+
| "'chromium-browser'"     | "Chromium('chromium-browser')"            |         |
+--------------------------+-------------------------------------------+---------+
| "'iosbrowser'"           | "IOSBrowser"                              | (4)     |
+--------------------------+-------------------------------------------+---------+

노트:

1. "Konqueror"는 유닉스용 KDE 데스크톱 환경의 파일 관리자이며, KDE가
   실행 중일 때만 의미가 있습니다. 신뢰성 있게 KDE를 탐지하는 방법이
   있다면 좋을 것입니다; "KDEDIR" 변수로는 충분하지 않습니다. KDE 2에
   서 **konqueror** 명령을 사용할 때조차도 "kfm"이라는 이름이 사용됨에
   유의하십시오 --- 구현이 Konqueror를 실행하기 위한 최상의 전략을 선
   택합니다.

2. 윈도우 플랫폼에서만.

3. 맥 OS 에서만.

4. iOS 에서만.

Added in version 3.2: A new "MacOSXOSAScript" class has been added and
is used on Mac instead of the previous "MacOSX" class. This adds
support for opening browsers not currently set as the OS default.

Added in version 3.3: Chrome/Chromium에 대한 지원이 추가되었습니다.

버전 3.12에서 변경: Support for several obsolete browsers has been
removed. Removed browsers include Grail, Mosaic, Netscape, Galeon,
Skipstone, Iceape, and Firefox versions 35 and below.

버전 3.13에서 변경: iOS에 대한 지원이 추가되었습니다.

Added in version 3.15: "MacOS" has been added as a replacement for
"MacOSXOSAScript", opening browsers via **/usr/bin/open** instead of
**osascript**.

Deprecated since version 3.15, will be removed in version 3.17:
"MacOSXOSAScript" is deprecated in favour of "MacOS". Using
**/usr/bin/open** instead of **osascript** is a security and usability
improvement: **osascript** may be blocked on managed systems due to
its abuse potential as a general-purpose scripting interpreter.

여기 몇 가지 간단한 예제가 있습니다:

   url = 'https://docs.python.org/'

   # 브라우저 창이 이미 열려 있으면, 새 탭에 URL을 엽니다.
   webbrowser.open_new_tab(url)

   # 새 창에 URL을 엽니다, 가능하다면 창을 올립니다.
   webbrowser.open_new(url)


Browser controller objects
==========================

Browser controllers provide the "name" attribute, and the following
three methods which parallel module-level convenience functions:

controller.name

   System-dependent name for the browser.

controller.open(url, new=0, autoraise=True)

   이 제어기가 처리하는 브라우저를 사용하여 *url*을 표시합니다. *new*
   가 1이면, 가능하다면 새 브라우저 창이 열립니다. *new*가 2이면, 가능
   하다면 새 브라우저 페이지("탭")가 열립니다.

controller.open_new(url)

   가능하다면, 이 제어기가 처리하는 브라우저의 새 창에 *url*을 엽니다,
   그렇지 않으면, 유일한 브라우저 창에 *url*을 엽니다. 별칭
   "open_new()".

controller.open_new_tab(url)

   가능하다면, 이 제어기가 처리하는 브라우저의 새 페이지("탭")에 *url*
   을 엽니다, 그렇지 않으면 "open_new()"와 동등합니다.

-[ 각주 ]-

[1] 전체 경로 없이 여기에서 명명된 실행 파일은 "PATH" 환경 변수에 지정
    된 디렉터리에서 검색됩니다.
