DefEssential 0.1.6__tar.gz → 0.1.8__tar.gz

defessential-0.1.8/DefEssential.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: DefEssential
+Version: 0.1.8
+Summary: The Modern Synchronous Python Web Application Framework
+Home-page: https://github.com/yong5eon/DefEssential
+Author: Heo Yongseon
+Project-URL: Source, https://github.com/yong5eon/DefEssential
+Project-URL: Issues, https://github.com/yong5eon/DefEssential/issues
+Project-URL: Releases, https://github.com/yong5eon/DefEssential/releases
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: gunicorn
+Requires-Dist: gunicorn>=23; extra == "gunicorn"
+Provides-Extra: uvicorn
+Requires-Dist: uvicorn>=0.30; extra == "uvicorn"
+Requires-Dist: a2wsgi>=1.10; extra == "uvicorn"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# DefEssential
+
+DefEssential is a synchronous Python web application framework for handling HTTP requests with ordinary Python methods. It provides route declarations, request validation, response helpers, streaming APIs, lifecycle hooks, and optional extensions without requiring `async` / `await`.
+
+## Requirements
+
+- Python 3.9 or later
+
+## Installation
+
+```bash
+pip install DefEssential
+```
+
+The package includes a built-in Python HTTP server. Optional extras provide additional server adapters:
+
+```bash
+pip install "DefEssential[Gunicorn]"
+pip install "DefEssential[Uvicorn]"
+```
+
+## Quick start
+
+```python
+from DefEssential import Application, Request, RequestRunner
+from DefEssential.Adapter.Implements.Python import Server
+from DefEssential.Responses import ResponseText
+
+
+class Hello(RequestRunner, method='GET', url='/hello'):
+  def run(self, request: Request):
+    return ResponseText('Hello, world!')
+
+
+application = Application()
+application.add(Hello)
+Server('127.0.0.1', 8000, application).run()
+```
+
+The handler declares an HTTP method and path on its `RequestRunner` class. The application registers the handler, and the server runs the application. A `GET /hello` request returns a plain-text response.
+
+## Request handling
+
+Define handlers as `RequestRunner` subclasses and implement `run()` with synchronous Python code. Configure path, query, header, and body validation in the class declaration. The framework also provides JSON, text, and file responses, direct streaming, Server-Sent Events, WebSocket support, and extensions for status checks, metrics, OpenAPI specifications, Swagger UI, and file serving.
+
+## License
+
+See the `LICENSE` file included with the source distribution for license terms.

{defessential-0.1.6 → defessential-0.1.8}/DefEssential.egg-info/SOURCES.txt

@@ -1,6 +1,8 @@
 .gitignore
 LICENSE
+README.en.md
 README.md
+README.setup.md
 setup.py
 .github/PULL_REQUEST_TEMPLATE.md
 .github/ISSUE_TEMPLATE/01.feature.yml
@@ -17,6 +19,10 @@ DefEssential.egg-info/top_level.txt
 issues/feature/2/ISSUE.md
 issues/feature/2/README.md
 issues/feature/2/REQUIREMENTS.md
+issues/feature/3/IMPLEMENTS.md
+issues/feature/3/ISSUE.md
+issues/feature/3/README.md
+issues/feature/3/REQUIREMENTS.md
 issues/feature/4/IMPLEMENTS.md
 issues/feature/4/ISSUE.md
 issues/feature/4/PLAN.md
@@ -32,6 +38,11 @@ issues/feature/6/ISSUE.md
 issues/feature/6/PLAN.md
 issues/feature/6/README.md
 issues/feature/6/REQUIREMENTS.md
+issues/task/14/ISSUE.md
+issues/task/14/PLAN.md
+issues/task/14/README.md
+issues/task/14/REQUIREMENTS.md
+issues/task/14/TASK.md
 issues/task/8/IMPLEMENTS.md
 issues/task/8/ISSUE.md
 issues/task/8/PLAN.md
@@ -163,6 +174,7 @@ tests/test_features.py
 tests/test_files.py
 tests/test_independence.py
 tests/test_loading.py
+tests/test_logging.py
 tests/test_request_runner_hooks.py
 tests/test_samples.py
 tests/test_server.py

defessential-0.1.8/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: DefEssential
+Version: 0.1.8
+Summary: The Modern Synchronous Python Web Application Framework
+Home-page: https://github.com/yong5eon/DefEssential
+Author: Heo Yongseon
+Project-URL: Source, https://github.com/yong5eon/DefEssential
+Project-URL: Issues, https://github.com/yong5eon/DefEssential/issues
+Project-URL: Releases, https://github.com/yong5eon/DefEssential/releases
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: gunicorn
+Requires-Dist: gunicorn>=23; extra == "gunicorn"
+Provides-Extra: uvicorn
+Requires-Dist: uvicorn>=0.30; extra == "uvicorn"
+Requires-Dist: a2wsgi>=1.10; extra == "uvicorn"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# DefEssential
+
+DefEssential is a synchronous Python web application framework for handling HTTP requests with ordinary Python methods. It provides route declarations, request validation, response helpers, streaming APIs, lifecycle hooks, and optional extensions without requiring `async` / `await`.
+
+## Requirements
+
+- Python 3.9 or later
+
+## Installation
+
+```bash
+pip install DefEssential
+```
+
+The package includes a built-in Python HTTP server. Optional extras provide additional server adapters:
+
+```bash
+pip install "DefEssential[Gunicorn]"
+pip install "DefEssential[Uvicorn]"
+```
+
+## Quick start
+
+```python
+from DefEssential import Application, Request, RequestRunner
+from DefEssential.Adapter.Implements.Python import Server
+from DefEssential.Responses import ResponseText
+
+
+class Hello(RequestRunner, method='GET', url='/hello'):
+  def run(self, request: Request):
+    return ResponseText('Hello, world!')
+
+
+application = Application()
+application.add(Hello)
+Server('127.0.0.1', 8000, application).run()
+```
+
+The handler declares an HTTP method and path on its `RequestRunner` class. The application registers the handler, and the server runs the application. A `GET /hello` request returns a plain-text response.
+
+## Request handling
+
+Define handlers as `RequestRunner` subclasses and implement `run()` with synchronous Python code. Configure path, query, header, and body validation in the class declaration. The framework also provides JSON, text, and file responses, direct streaming, Server-Sent Events, WebSocket support, and extensions for status checks, metrics, OpenAPI specifications, Swagger UI, and file serving.
+
+## License
+
+See the `LICENSE` file included with the source distribution for license terms.

defessential-0.1.8/README.en.md

@@ -0,0 +1,133 @@
+# DefEssential
+
+The modern synchronous Python web application framework
+
+**Just def.**<br>
+**Let web apps do the work.**<br>
+**You don't need to await this.**
+
+[한국어](./README.md)
+
+DefEssential is a synchronous web framework for handling HTTP requests with ordinary Python methods.
+Configure routes, request validation, responses, and extensions without `async` / `await`.
+
+- **Synchronous request handling**: Declare HTTP methods, paths, and handlers with `RequestRunner` classes.
+- **Request validation**: Apply validators and converters to path, query, header, and body values.
+- **Responses and streaming**: Support JSON, text, and file responses, streaming, Server-Sent Events, and WebSocket.
+- **Extensions**: Combine health status, Ping, Metrics, OpenAPI specifications, Swagger UI, and file-serving features.
+- **Server adapters**: Use the built-in Python server or optionally install the Gunicorn and Uvicorn adapters.
+- **Lifecycle hooks**: Register hooks for application, extension, and request execution lifecycles.
+
+## Requirements and installation
+
+- Python 3.9 or later
+
+```bash
+pip install DefEssential
+```
+
+The built-in Python server requires no additional server dependency. Install an optional extra to use another adapter.
+
+```bash
+pip install "DefEssential[Gunicorn]"
+pip install "DefEssential[Uvicorn]"
+```
+
+## Quick start
+
+```python
+from DefEssential import Application, Request, RequestRunner
+from DefEssential.Adapter.Implements.Python import Server
+from DefEssential.Responses import ResponseText
+
+
+class Hello(RequestRunner, method='GET', url='/hello'):
+  def run(self, request: Request):
+    return ResponseText('Hello, world!')
+
+
+application = Application()
+application.add(Hello)
+
+Server('127.0.0.1', 8000, application).run()
+```
+
+After starting the server, a `GET /hello` request returns `Hello, world!`. Each request is handled by a new handler instance.
+
+## Request handlers and validation
+
+Declare `method` and `url` on a `RequestRunner` subclass and implement synchronous request handling in `run()`. Declare URL path parameters with the `:name` syntax and configure validation rules with `parameters`, `qs`, `headers`, and `body`.
+
+```python
+from DefEssential import (
+  Parameters,
+  Request,
+  RequestRunner,
+)
+from DefEssential.Responses import ResponseJSON
+from DefEssential.Validator.Patterns import (
+  IsGreaterThan,
+  ToInteger,
+)
+
+
+class ReadValue(
+  RequestRunner,
+  method='GET',
+  url='/values/:value',
+  parameters=Parameters({
+    'value': ToInteger(IsGreaterThan(0)),
+  }),
+):
+  def run(self, request: Request):
+    return ResponseJSON({'value': request.parameters['value']})
+```
+
+Validators and converters run before input is passed to the handler. Read request bodies as JSON, text, binary data, or streams through `Body` and content readers.
+
+## Responses, streaming, and protocols
+
+- Create JSON, text, and file responses with `ResponseJSON`, `ResponseText`, and `ResponseFile`.
+- Stream response bodies through `request.writer` and stream writers. In this mode, the handler writes the response directly and returns `None`.
+- Send event streams with the Server-Sent Events writer.
+- Use the `WebSocket` API to exchange text and binary messages after upgrading an HTTP connection.
+
+Direct-output and streaming responses have different processing timing from ordinary returned responses. Configure response handling according to the relevant hook contracts and transport behavior.
+
+## Extensions and servers
+
+Pass extensions to `Application(exts=...)`. Built-in extensions include:
+
+- `Status`: provide a status page
+- `Ping`: report the application's running state
+- `Metrics`: expose request metrics as JSON or Prometheus
+- `Specifications`: generate an OpenAPI 3.1 document from registered routes
+- `Swagger`: provide Swagger UI
+- `File`, `FileSystem`: serve fixed files or file-system content
+
+The built-in server is `DefEssential.Adapter.Implements.Python.Server`. Install the `DefEssential[Gunicorn]` or `DefEssential[Uvicorn]` extra for the corresponding adapter. Supported environments and transport characteristics vary by adapter and worker type.
+
+## Lifecycle hooks and logging
+
+`Application` accepts `on_startup`, `on_cleanup`, `on_request`, `on_request_response`, and `on_request_error` hooks. `Extension` supports startup, cleanup, request, response, and error hooks; `RequestRunner` supports request, response, and error hooks.
+
+DefEssential uses standard `logging` loggers and does not configure application handlers or log levels. Configure the loggers and output policy required by your application.
+
+## Samples and tests
+
+`samples/Sample.py` in the repository demonstrates requests, validation, authentication, files, streaming, WebSocket, and built-in extensions. Run the sample server from the project root:
+
+```bash
+python samples/Sample.py
+```
+
+Install the current checkout in editable mode from the project root, then run the tests:
+
+```bash
+pip install -e .
+python -m unittest discover -s tests
+```
+
+## License
+
+See the `LICENSE` file in the repository for license terms.

defessential-0.1.8/README.md

@@ -0,0 +1,133 @@
+# DefEssential
+
+동기식 Python 웹 애플리케이션 프레임워크
+
+**Just def.**<br>
+**Let web apps do the work.**<br>
+**You don't need to await this.**
+
+[English](./README.en.md)
+
+DefEssential은 일반 Python 메서드로 HTTP 요청을 처리하는 동기식 웹 프레임워크입니다.
+`async` / `await` 없이 라우트, 요청 검증, 응답, 확장 기능을 구성할 수 있습니다.
+
+- **동기식 요청 처리**: `RequestRunner` 클래스로 HTTP 메서드와 경로, 핸들러를 선언합니다.
+- **요청 검증**: 경로·쿼리·헤더·본문 값에 검증기와 변환기를 적용합니다.
+- **응답과 스트리밍**: JSON·텍스트·파일 응답, 스트리밍, Server-Sent Events, WebSocket을 지원합니다.
+- **확장 기능**: 상태 확인, Ping, Metrics, OpenAPI 명세와 Swagger UI, 파일 제공 기능을 조합할 수 있습니다.
+- **서버 어댑터**: 기본 Python 서버를 제공하며 Gunicorn과 Uvicorn 어댑터를 선택적으로 설치할 수 있습니다.
+- **생명주기 훅**: 애플리케이션, 확장, 요청 실행 단계에 훅을 등록할 수 있습니다.
+
+## 요구 사항 및 설치
+
+- Python 3.9 이상
+
+```bash
+pip install DefEssential
+```
+
+기본 Python 서버는 추가 서버 의존성 없이 사용할 수 있습니다. 선택적 어댑터가 필요한 경우 해당 추가 기능을 설치합니다.
+
+```bash
+pip install "DefEssential[Gunicorn]"
+pip install "DefEssential[Uvicorn]"
+```
+
+## 빠른 시작
+
+```python
+from DefEssential import Application, Request, RequestRunner
+from DefEssential.Adapter.Implements.Python import Server
+from DefEssential.Responses import ResponseText
+
+
+class Hello(RequestRunner, method='GET', url='/hello'):
+  def run(self, request: Request):
+    return ResponseText('Hello, world!')
+
+
+application = Application()
+application.add(Hello)
+
+Server('127.0.0.1', 8000, application).run()
+```
+
+서버를 실행한 뒤 `GET /hello` 요청은 `Hello, world!`를 반환합니다. 각 요청은 새로운 핸들러 인스턴스에서 처리됩니다.
+
+## 요청 핸들러와 검증
+
+`RequestRunner` 하위 클래스 선언에서 `method`와 `url`을 지정하고 `run()` 메서드에 동기식 처리 로직을 작성합니다. URL 경로 변수는 `:name` 형식으로 선언하며, `parameters`, `qs`, `headers`, `body` 설정에 검증 규칙을 지정할 수 있습니다.
+
+```python
+from DefEssential import (
+  Parameters,
+  Request,
+  RequestRunner,
+)
+from DefEssential.Responses import ResponseJSON
+from DefEssential.Validator.Patterns import (
+  IsGreaterThan,
+  ToInteger,
+)
+
+
+class ReadValue(
+  RequestRunner,
+  method='GET',
+  url='/values/:value',
+  parameters=Parameters({
+    'value': ToInteger(IsGreaterThan(0)),
+  }),
+):
+  def run(self, request: Request):
+    return ResponseJSON({'value': request.parameters['value']})
+```
+
+검증기와 변환기는 요청 입력을 핸들러에 전달하기 전에 실행됩니다. 본문은 `Body`와 콘텐츠 리더를 통해 JSON, 텍스트, 바이너리 또는 스트리밍 방식으로 읽을 수 있습니다.
+
+## 응답, 스트리밍 및 프로토콜
+
+- `ResponseJSON`, `ResponseText`, `ResponseFile`로 JSON, 텍스트, 파일 응답을 만들 수 있습니다.
+- `request.writer`와 스트림 writer로 응답 본문을 직접 스트리밍할 수 있습니다. 이 방식에서는 핸들러가 응답을 직접 기록하고 `None`을 반환합니다.
+- Server-Sent Events writer로 이벤트 스트림을 전송할 수 있습니다.
+- `WebSocket` API는 HTTP 연결을 업그레이드한 뒤 text 및 binary 메시지를 송수신합니다.
+
+직접 출력 및 스트리밍 응답은 일반 반환 응답과 처리 시점이 다릅니다. 관련 훅 계약과 전송 동작에 맞춰 응답 처리를 구성하세요.
+
+## 확장 기능과 서버
+
+확장 기능은 `Application(exts=...)`에 전달해 사용합니다. 기본 제공 확장은 다음과 같습니다.
+
+- `Status`: 상태 페이지 제공
+- `Ping`: 애플리케이션 실행 상태 응답
+- `Metrics`: JSON 또는 Prometheus 형식의 요청 통계 제공
+- `Specifications`: 등록된 라우트로부터 OpenAPI 3.1 문서 생성
+- `Swagger`: Swagger UI 제공
+- `File`, `FileSystem`: 고정 파일 또는 파일 시스템 콘텐츠 제공
+
+기본 서버는 `DefEssential.Adapter.Implements.Python.Server`입니다. Gunicorn과 Uvicorn 어댑터는 각각 `DefEssential[Gunicorn]`, `DefEssential[Uvicorn]` 추가 기능으로 설치합니다. 어댑터와 worker 방식에 따라 지원 환경과 전송 특성이 다를 수 있습니다.
+
+## 생명주기 훅과 로깅
+
+`Application`은 `on_startup`, `on_cleanup`, `on_request`, `on_request_response`, `on_request_error` 훅을 받을 수 있습니다. `Extension`은 시작·정리·요청·응답·오류 훅을, `RequestRunner`는 요청·응답·오류 훅을 지원합니다.
+
+DefEssential은 표준 `logging` 로거를 사용하며 애플리케이션의 핸들러나 로그 레벨을 대신 설정하지 않습니다. 애플리케이션에서 필요한 로거와 출력 정책을 구성하세요.
+
+## 샘플 및 테스트
+
+저장소의 `samples/Sample.py`에는 요청, 검증, 인증, 파일, 스트리밍, WebSocket 및 기본 제공 확장을 포함한 실행 예제가 있습니다. 프로젝트 루트에서 다음 명령으로 샘플 서버를 실행할 수 있습니다.
+
+```bash
+python samples/Sample.py
+```
+
+저장소 코드를 테스트하려면 프로젝트 루트에서 editable 설치를 한 뒤 다음 명령을 실행합니다.
+
+```bash
+pip install -e .
+python -m unittest discover -s tests
+```
+
+## 라이선스
+
+라이선스 조건은 저장소의 `LICENSE` 파일을 확인하세요.

defessential-0.1.8/README.setup.md

@@ -0,0 +1,48 @@
+# DefEssential
+
+DefEssential is a synchronous Python web application framework for handling HTTP requests with ordinary Python methods. It provides route declarations, request validation, response helpers, streaming APIs, lifecycle hooks, and optional extensions without requiring `async` / `await`.
+
+## Requirements
+
+- Python 3.9 or later
+
+## Installation
+
+```bash
+pip install DefEssential
+```
+
+The package includes a built-in Python HTTP server. Optional extras provide additional server adapters:
+
+```bash
+pip install "DefEssential[Gunicorn]"
+pip install "DefEssential[Uvicorn]"
+```
+
+## Quick start
+
+```python
+from DefEssential import Application, Request, RequestRunner
+from DefEssential.Adapter.Implements.Python import Server
+from DefEssential.Responses import ResponseText
+
+
+class Hello(RequestRunner, method='GET', url='/hello'):
+  def run(self, request: Request):
+    return ResponseText('Hello, world!')
+
+
+application = Application()
+application.add(Hello)
+Server('127.0.0.1', 8000, application).run()
+```
+
+The handler declares an HTTP method and path on its `RequestRunner` class. The application registers the handler, and the server runs the application. A `GET /hello` request returns a plain-text response.
+
+## Request handling
+
+Define handlers as `RequestRunner` subclasses and implement `run()` with synchronous Python code. Configure path, query, header, and body validation in the class declaration. The framework also provides JSON, text, and file responses, direct streaming, Server-Sent Events, WebSocket support, and extensions for status checks, metrics, OpenAPI specifications, Swagger UI, and file serving.
+
+## License
+
+See the `LICENSE` file included with the source distribution for license terms.

defessential-0.1.8/issues/feature/3/IMPLEMENTS.md

@@ -0,0 +1,118 @@
+# 로깅 지원 구현 기록
+
+## 1. 개요
+
+[로깅 지원 이슈](./ISSUE.md)와 [요구사항 명세서](./REQUIREMENTS.md)에 따라 프레임워크 로그를 `DefEssential` 계층으로 정리하고 주요 실행 경로의 로그를 보강했다.
+
+DefStream처럼 Python 표준 `logging`으로 로그를 기록하며, 출력 설정은 샘플의 Application 시작 훅에서 담당한다. 이 문서는 2026-10-25 기준 최종 구현과 앞선 구현 작업에서 확인한 검증 결과를 기록한다.
+
+## 2. 최종 구현 방식
+
+- 클래스는 `logger = getLogger('DefEssential.…')`로 고정 이름을 선언하고 메서드에서 직접 사용한다.
+- 공통 함수는 담당 경계의 모듈 로거를 사용한다. 로거를 전달하기 위한 공개 인자는 추가하지 않았다.
+- 사용자 하위 클래스는 기존 로거를 상속하며 필요하면 명시적으로 재정의할 수 있다.
+- 라이브러리는 핸들러·포매터·필터·레벨을 설정하거나 기존 사용자 설정을 제거하지 않는다. `basicConfig()`와 `NullHandler`도 추가하지 않았다.
+- 로깅 때문에 공개 훅 계약이나 요청·응답 처리 순서를 바꾸지 않는다.
+
+### 2.1. 후속 검토에 따른 단순화
+
+초기 구현의 로깅 전용 구조를 다음과 같이 제거했다.
+
+- 단계 로그용 `stage()` context manager와 자동 단계별 타이머를 제거하고 처리 지점의 직접 logger 호출로 바꿨다.
+- 라우트·어댑터 전달용 `REQUEST_ROUTE`, `SERVER_ADAPTER` ContextVar와 설정·해제 코드를 제거했다.
+- 클래스명·문자열 처리 함수도 표준 Python 속성과 표현으로 대체하고 별도 로깅 유틸 파일을 삭제했다.
+
+라우트는 Application의 등록·선택 지점에서, 어댑터는 각 서버의 생명주기 지점에서 기록한다. 요청 실행 단계와 HTTP 전송 결과는 지역 변수로 관리하며 로깅용 공유 상태를 두지 않는다.
+
+## 3. 기록 범위와 레벨
+
+| 대상 | 로거 | 구현 내용 |
+| --- | --- | --- |
+| [Application](../../../src/Application.py) | `DefEssential.Application` | 시작·종료, 확장 연결·롤백·정리, 라우트 등록·선택, 훅 실행과 디스패치 |
+| [요청 실행기](../../../src/Runners/RunRequest.py) | `DefEssential.RequestRunner` | 인증·검증·본문 처리·핸들러 생성·실행, 요청·응답·오류 훅과 직접 출력 단계 |
+| [확장 실행기](../../../src/Runners/RunExtension.py) | `DefEssential.Extension` | 확장 호출과 요청·응답·오류 훅 |
+| [공통 요청 처리기](../../../src/Adapter/RequestHandler.py) | `DefEssential.Server` | HTTP 수신, 오류 응답 선택, 최종 전송 결과와 본문 정리 실패 |
+| [Python](../../../src/Adapter/Implements/Python/Server.py)·[Gunicorn](../../../src/Adapter/Implements/Gunicorn/Server.py)·[Uvicorn](../../../src/Adapter/Implements/Uvicorn/Server.py) 서버 | `DefEssential.Server` | 어댑터 식별, 실제 바인딩 후 준비 완료, 시작·종료·실패 |
+| [WebSocket](../../../src/IO/WebSocket/WebSocket.py) | `DefEssential.IO.WebSocket` | 연결 상태, 종료 코드, 프로토콜 위반과 내부 실패 |
+| [내장 확장](../../../src/Extensions) | `DefEssential.Extensions.*` | File·FileSystem·Ping·Metrics·Status·Specifications·Swagger의 주요 처리와 실패 |
+
+| 레벨 | 기록 기준 |
+| --- | --- |
+| DEBUG | 등록·선택, 검증·실행·훅의 진입과 완료, 정상 분기 및 관찰 정보 |
+| INFO | 애플리케이션·서버 생명주기, HTTP 전송 결과 요약 |
+| WARNING | 클라이언트 연결 단절, WebSocket 프로토콜 위반 |
+| ERROR | 예상하지 못한 내부 오류, 시작·전송·정리 실패 |
+
+일반적인 4xx 응답이라는 이유만으로 WARNING이나 ERROR로 승격하지 않는다. 실패한 단계 뒤에 정상 완료 로그를 남기지 않으며, 샘플의 훅 관찰 로그는 DEBUG로 구분한다.
+
+## 4. 요청 처리와 오류 경계
+
+### 4.1. 단계 로그
+
+[RunRequest](../../../src/Runners/RunRequest.py)는 기존 실행 흐름 안에서 직접 로그를 기록한다. 지역 `phase` 값으로 실패 단계를 식별하고, 실제 호출이 끝난 뒤에만 완료를 기록한다. 로깅만을 위한 별도 실행 래퍼는 두지 않았다.
+
+### 4.2. HTTP 전송 결과
+
+[공통 요청 처리기](../../../src/Adapter/RequestHandler.py)는 요청별 전송 요약을 INFO로 한 번 기록한다.
+
+| 항목 | 의미 |
+| --- | --- |
+| `request_id` | 서버 경계에서 생성한 최초 요청의 ID. 생성 전 실패하면 `None` |
+| `method` | 앞 32자를 `ascii()`로 이스케이프한 메서드. 요청 생성 전에는 `None` |
+| `status` | writer가 실제 응답을 시작한 경우의 상태. 시작 전에는 `None` |
+| `outcome` | `completed`, `failed`, `disconnected` |
+| `duration` | 공통 처리 진입부터 전송 결과 기록 직전까지 `monotonic()`으로 측정한 초 단위 시간 |
+
+요약에는 원시 요청 경로·쿼리, 라우트나 어댑터 전달용 상태를 추가하지 않았다.
+
+- 반환 응답 전송 또는 직접 출력 종료를 확인한 경우에만 `completed`로 기록한다.
+- 쓰기·flush·iterable 소비 실패는 성공으로 처리하지 않는다. 연결 단절은 `disconnected`로 구분한다.
+- 핸들러·응답 훅 완료는 실제 전송 완료가 아니다. 101 업그레이드 역시 WebSocket 세션 전체의 성공을 뜻하지 않는다.
+- 전송 요약 뒤의 본문 정리 실패는 별도 ERROR로 기록한다. 전송 시간에는 이 후속 정리 시간이 포함되지 않는다.
+- Python 기본 HTTP 처리기의 헤더 생성 시점 접근 로그는 DEBUG로 구분해 INFO 요약과 중복되지 않게 했다.
+
+### 4.3. 예외 처리
+
+- 프레임워크의 HTTP 오류는 기존 오류 응답으로 변환한다.
+- 응답 시작 전 예상하지 못한 예외는 최종 서버 경계에서 ERROR와 traceback을 기록하고 기존 500 응답으로 처리한다.
+- 응답 시작 후 실패는 두 번째 오류 응답을 보내지 않고 기록 후 전파한다.
+- 연결 단절은 WARNING으로 기록하며 예외 문자열과 traceback을 반복 출력하지 않는다.
+- 중간 실행 계층과 샘플 훅은 같은 전파 예외의 traceback을 중복 기록하지 않는다. 독립적인 정리 실패는 별개 사건으로 기록한다.
+
+## 5. 샘플 출력 설정과 기록 제한
+
+[샘플](../../../samples/Sample.py)의 `LoggingSetup`을 첫 Application 시작 훅으로 등록했다.
+
+- 루트 레벨을 DEBUG로 설정하고 이름이 `Sample`인 콘솔 핸들러를 추가한다.
+- 핸들러의 출처 필터로 `Sample`·`Sample.*`, `DefEssential`·`DefEssential.*`만 선택한다. 유사 접두 이름과 외부 서버 로거는 제외한다.
+- 같은 이름의 핸들러는 재시작 시 중복 추가하지 않으며 기존 사용자 핸들러는 제거하지 않는다. 다른 핸들러의 출력까지 제한하지는 않는다.
+- 현재 포맷은 `%(asctime)s %(levelname)-8s %(name)s %(message)s`이며 밀리초와 레벨별 색상을 표시한다. 색상 포매터는 LogRecord 복사본을 사용한다.
+- 시작 훅 이전의 구성·등록 로그를 소급 출력하지 않으며 기존 시작 배너는 유지한다.
+- [일반 요청](../../../samples/runners/Requests.py)·[스트리밍](../../../samples/runners/Streaming.py) 샘플의 훅 로그는 DEBUG로 기록한다.
+
+기본 문맥에서 원시 URI·경로·query, 인증정보, 요청·응답 본문, WebSocket payload·close reason을 제외했다. Application은 선택된 등록 라우트의 앞 256자를 `ascii()`로 이스케이프해 기록한다. 이 길이는 이스케이프 전 문자 수 기준이다.
+
+traceback에는 예외 메시지와 소스 줄이 포함될 수 있으므로 완전한 비밀정보 차단을 보장하지 않는다. 사용자 예외 메시지와 등록 라우트에 민감정보를 넣지 않아야 하며, 추가 필터링은 애플리케이션 설정의 책임이다.
+
+## 6. 검증 기록
+
+아래는 최종 코드 단순화 후 수행한 검증 결과다. 이번 문서 작성 중 테스트를 다시 실행한 결과는 아니다.
+
+- Windows의 Python 3.12에서 작업 트리 소스를 직접 로드해 전체 `unittest` 발견 테스트를 실행했다.
+- 총 **243개 중 238개 통과, 5개 건너뜀**을 확인했다. 설치된 별도 패키지를 대상으로 한 결과가 아니다.
+- [로깅 전용 테스트](../../../tests/test_logging.py) 21개로 로거 상속·재정의, 설정 비간섭, 단계·레벨, 전송 요약, 실패·단절·정리, 병렬·중첩 요청, 민감정보 제외, 샘플 설정의 중복 방지를 검증했다.
+- 기존 훅·writer·스트리밍·SSE·WebSocket 회귀와 Python·Uvicorn의 실제 HTTP 전송을 포함했다.
+- 포트 0의 실제 준비 완료 로그, Uvicorn의 실제 바인딩 실패, Python 바인딩 실패의 테스트 더블 검증을 포함했다.
+- 소스·샘플·테스트의 Python 3.9 구문 분석과 `git diff --check`를 통과했다. 주요 변경 파일의 Pylance 타입 오류도 확인했다.
+- 로깅 유틸 파일 삭제와 잔여 import·호출 제거를 확인했다.
+
+### 환경 제약
+
+- 건너뛴 5개는 POSIX가 필요한 Gunicorn 실행·전송 적합성 테스트다. 실제 Gunicorn 실행은 Linux·WSL 또는 CI에서 추가 확인해야 한다.
+- Python 3.9는 구문 분석만 수행했다. 해당 버전의 실제 런타임 테스트를 통과한 것으로 간주하지 않는다.
+- 라이브러리 미설정 시 표준 `logging.lastResort` 동작을 유지한다. Gunicorn·Uvicorn 자체 로깅 설정과 외부 접근 로그의 출력 정책은 별도로 관리해야 한다.
+
+## 7. 관련 문서
+
+- [요구사항 명세서](./REQUIREMENTS.md)
+- [변경 로그](./README.md)

defessential-0.1.8/issues/feature/3/ISSUE.md

@@ -0,0 +1,9 @@
+# 로깅 지원
+
+### 해결하려는 문제
+
+파편화된 로깅 정리
+
+### 제안하는 해결 방법
+
+DefEssential 을 Master 키 로 하여 로그 이름을 설정하고, 부족한 로깅들을 풍부하게 추가