wsgiref — WSGI 유틸리티와 참조 구현

wsgiref — WSGI 유틸리티와 참조 구현

경고: wsgiref는 참조 구현(reference implementation)이며 프로덕션용으로는 권장되지 않아요. 이 모듈은 기본 보안 검사만 구현해요.

WSGI(Web Server Gateway Interface)는 웹 서버 소프트웨어와 Python으로 작성된 웹 애플리케이션 사이의 표준 인터페이스예요. 표준 인터페이스가 있으면 WSGI를 지원하는 애플리케이션을 다양한 웹 서버와 함께 쉽게 사용할 수 있어요.

출처: Python documentation

본문

웹 서버와 프로그래밍 프레임워크 작성자만 WSGI 설계의 모든 세부 사항과 예외적인 경우를 알 필요가 있어요. WSGI 애플리케이션을 설치하거나 기존 프레임워크로 웹 애플리케이션을 작성하려면 WSGI의 모든 세부 사항을 이해할 필요는 없어요.

wsgiref는 웹 서버나 프레임워크에 WSGI 지원을 추가하는 데 사용할 수 있는 WSGI 사양의 참조 구현이에요. WSGI 환경 변수와 응답 헤더를 조작하는 유틸리티, WSGI 서버를 구현하는 기본 클래스, WSGI 애플리케이션을 제공하는 데모 HTTP 서버, 정적 타입 검사를 위한 타입, WSGI 서버와 애플리케이션이 WSGI 사양(PEP 3333)에 부합하는지 확인하는 검증 도구를 제공해요.

wsgiref 패키지는 다음 하위 모듈로 구성돼요.

wsgiref.util — WSGI 환경 유틸리티

이 모듈은 WSGI 환경 작업을 위한 다양한 유틸리티 함수를 제공해요. WSGI 환경은 PEP 3333에 설명된 HTTP 요청 변수를 포함하는 사전이에요.

• wsgiref.util.guess_scheme(environ) — environ 사전의 HTTPS 환경 변수를 확인해 wsgi.url_scheme이 "http"인지 "https"인지 추측해요. CGI나 FastCGI 같은 CGI 유사 프로토콜을 래핑하는 게이트웨이를 만들 때 유용해요.
• wsgiref.util.request_uri(environ, include_query=True) — PEP 3333의 "URL Reconstruction" 섹션에 있는 알고리즘을 사용해 전체 요청 URI를 반환해요.
• wsgiref.util.application_uri(environ) — request_uri()와 비슷하지만 PATH_INFO와 QUERY_STRING 변수를 무시해요.
• wsgiref.util.shift_path_info(environ) — PATH_INFO에서 SCRIPT_NAME으로 이름 하나를 이동하고 그 이름을 반환해요. PATH_INFO의 경로 세그먼트가 남지 않으면 None을 반환해요.
• wsgiref.util.setup_testing_defaults(environ) — 테스트 목적으로 사소한 기본값으로 environ을 업데이트해요. WSGI 서버와 애플리케이션의 단위 테스트에서 더미 환경을 설정하기 쉽게 만들기 위한 것이며, 실제 WSGI 서버나 애플리케이션에서는 사용하면 안 돼요(데이터가 가짜이기 때문).
• wsgiref.util.is_hop_by_hop(header_name) — header_name이 RFC 2616이 정의한 HTTP/1.1 "Hop-by-Hop" 헤더이면 True 반환
• classwsgiref.util.FileWrapper(filelike, blksize=8192) — 파일류 객체를 iterator로 변환하는 데 사용되는 wsgiref.types.FileWrapper 프로토콜의 구체적 구현. 결과 객체는 iterable이에요.

wsgiref.headers — WSGI 응답 헤더 도구

이 모듈은 매핑 유사 인터페이스를 사용해 WSGI 응답 헤더를 편리하게 조작하는 Headers 단일 클래스를 제공해요.

• classwsgiref.headers.Headers([headers]) — headers(PEP 3333의 헤더 이름/값 튜플 목록)를 래핑하는 매핑 유사 객체를 만들어요. 사전과 달리 Headers 객체는 래핑된 헤더 목록에 없는 키를 얻거나 삭제하려 해도 오류를 발생시키지 않아요. bytes() 호출은 HTTP 응답 헤더로 전송하기 적합한 형식화된 바이트 문자열을 반환해요.
• get_all(name) — 지정된 헤더의 모든 값 목록을 반환해요.
• add_header(name, value, **_params) — 선택적 MIME 매개변수가 지정된 (아마도 다중 값)헤더를 추가해요.

wsgiref.simple_server — 간단한 WSGI HTTP 서버

이 모듈은 WSGI 애플리케이션을 제공하는 간단한 HTTP 서버(http.server 기반)를 구현해요. 각 서버 인스턴스는 주어진 호스트와 포트에서 단일 WSGI 애플리케이션을 제공해요.

• wsgiref.simple_server.make_server(host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler) — host와 port에서 수신 대기하는 새 WSGI 서버를 만들어요.

from wsgiref.simple_server import make_server, demo_app

with make_server('', 8000, demo_app) as httpd:
    print("Serving HTTP on port 8000...")
    httpd.serve_forever()

• wsgiref.simple_server.demo_app(environ, start_response) — "Hello world!" 메시지와 environ 매개변수의 키/값 쌍 목록을 포함하는 텍스트 페이지를 반환하는 작지만 완전한 WSGI 애플리케이션.
• classwsgiref.simple_server.WSGIServer(server_address, RequestHandlerClass) — WSGIServer 인스턴스 생성. http.server.HTTPServer의 하위 클래스이며, set_app()과 get_app() 메서드를 추가로 제공해요.
• classwsgiref.simple_server.WSGIRequestHandler(request, client_address, server) — get_environ(), get_stderr(), handle() 메서드를 제공하는 HTTP 핸들러.

wsgiref.validate — WSGI 적합성 검사기

새 WSGI 애플리케이션 객체, 프레임워크, 서버, 미들웨어를 만들 때 wsgiref.validate로 새 코드의 적합성을 검증하는 것이 유용할 수 있어요.

• wsgiref.validate.validator(application) — application을 래핑하고 새 WSGI 애플리케이션 객체를 반환해요. 감지된 모든 비적합성은 AssertionError를 발생시켜요.

이 유틸리티는 완전한 PEP 3333 준수를 보장하지는 않아요. 하지만 오류를 생성하면 서버나 애플리케이션이 100% 호환되지 않는다는 것이 거의 확실해요.

wsgiref.handlers — 서버/게이트웨이 기본 클래스

이 모듈은 WSGI 서버와 게이트웨이를 구현하기 위한 기본 핸들러 클래스를 제공해요.

• classwsgiref.handlers.CGIHandler — sys.stdin, sys.stdout, sys.stderr, os.environ을 통한 CGI 기반 호출. WSGI 애플리케이션을 CGI 스크립트로 실행하려면 CGIHandler().run(app)을 호출해요.
• classwsgiref.handlers.IISCGIHandler — allowPathInfo 옵션을 설정하지 않고 Microsoft IIS 웹 서버에 배포할 때 사용하는 CGIHandler의 특수 대안.
• classwsgiref.handlers.BaseCGIHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False) — CGIHandler와 비슷하지만 sys와 os 모듈 대신 CGI 환경과 I/O 스트림을 명시적으로 지정.
• classwsgiref.handlers.SimpleHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False) — BaseCGIHandler와 비슷하지만 HTTP origin 서버와 함께 사용하도록 설계.
• classwsgiref.handlers.BaseHandler — WSGI 애플리케이션을 실행하기 위한 추상 기본 클래스. 각 인스턴스는 단일 HTTP 요청을 처리해요. run(app) 메서드가 유일하게 외부 사용을 위한 메서드예요.

BaseHandler는 여러 속성과 메서드를 제공해요(wsgi_multithread, wsgi_multiprocess, wsgi_run_once, os_environ, server_software, get_scheme(), setup_environ(), log_exception(), error_output(), wsgi_file_wrapper, origin_server, http_version 등).

• wsgiref.handlers.read_environ() — CGI 변수를 os.environ에서 PEP 3333 "bytes in unicode" 문자열로 트랜스코딩해 새 사전을 반환해요.

wsgiref.types — 정적 타입 검사를 위한 WSGI 타입

이 모듈은 PEP 3333에 설명된 정적 타입 검사를 위한 다양한 타입을 제공해요.

• classwsgiref.types.StartResponse — start_response() 호출 가능을 설명하는 typing.Protocol
• wsgiref.types.WSGIEnvironment — WSGI 환경 사전을 설명하는 타입 별칭
• wsgiref.types.WSGIApplication — WSGI 애플리케이션 호출 가능을 설명하는 타입 별칭
• classwsgiref.types.InputStream — WSGI 입력 스트림을 설명하는 typing.Protocol
• classwsgiref.types.ErrorStream — WSGI 오류 스트림을 설명하는 typing.Protocol
• classwsgiref.types.FileWrapper — 파일 래퍼를 설명하는 typing.Protocol

예제 (Examples)

동작하는 "Hello World" WSGI 애플리케이션:

from wsgiref.simple_server import make_server

def hello_world_app(environ, start_response):
    status = "200 OK"
    headers = [("Content-type", "text/plain; charset=utf-8")]
    start_response(status, headers)
    return [b"Hello World"]

with make_server("", 8000, hello_world_app) as httpd:
    print("Serving on port 8000...")
    httpd.serve_forever()

더 알아보기 (Learn more)

• Python 공식 문서