DefEssential 0.1.7__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.7 → 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
@@ -36,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

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/task/14/ISSUE.md

@@ -0,0 +1,30 @@
+# DefEssential 문서 현지화 및 Python 설명 문구 영어화
+
+## 작업 목적
+
+공개 프로젝트의 사용자 문서를 한국어와 영어로 제공하고, 배포되는 Python 코드의 설명 및 예외 문구를 영어로 통일한다. 문서와 문구의 언어만 변경하며 기존 API와 실행 동작은 유지한다.
+
+## 작업 범위
+
+### 문서
+
+- `README.md`: 설치, 빠른 시작, 주요 기능과 사용 방법을 포함하는 한국어 사용자 매뉴얼로 작성한다.
+- `README.en.md`: `README.md`와 같은 범위와 구조를 갖는 영어 매뉴얼을 새로 작성한다.
+- `README.setup.md`: PyPI 패키지 설명에 사용할 영어 문서를 새로 작성한다. PyPI 사용자에게 필요한 프로젝트 소개, 설치 방법, 빠른 시작을 포함하며 외부 링크를 넣지 않는다.
+- `setup.py`: 패키지 메타데이터의 `long_description`이 `README.setup.md`를 읽도록 변경한다. PyPI 설명에 한국어 문서가 노출되지 않아야 한다.
+
+### Python 문구
+
+- 대상은 DefEssential 프로젝트의 관리 대상 Python 파일이다: `src/`, `samples/`, `tests/` 아래의 `.py` 파일과 루트 `setup.py`.
+- 대상 파일의 독스트링, 주석, `raise` 문에서 사용자에게 노출되는 예외 메시지를 자연스러운 영어로 작성한다.
+- 식별자, API 이름, 예외 유형, 조건 및 처리 로직은 변경하지 않는다. 번역에 수반되는 메시지 문자열 변경 외의 동작 변경은 이 작업 범위에 포함하지 않는다.
+
+## 완료 기준
+
+- `README.md`는 한국어 매뉴얼이며, `README.en.md`는 이에 대응하는 영어 매뉴얼이다.
+- `README.setup.md`는 영어로 작성되고, `setup.py`가 이 문서를 패키지의 PyPI 설명으로 사용한다.
+- `README.setup.md`에는 외부 URL 또는 외부 페이지로 연결되는 링크가 없다.
+- 지정한 Python 파일의 독스트링과 주석에 한국어 설명 문구가 남아 있지 않다.
+- `raise` 문에서 사용자에게 노출되는 예외 메시지가 영어이며, 메시지 변경으로 영향을 받는 테스트도 갱신되어 통과한다.
+- 변경은 문서와 설명 문구에 한정되고, 공개 API와 기존 실행 동작이 유지된다.
+- Python 파일의 한글 검색 결과를 검토하여 남은 한글이 있다면 대상 범위의 문구인지 확인한다. 테스트 데이터 등 번역 대상이 아닌 문자열은 불필요하게 변경하지 않는다.

defessential-0.1.8/issues/task/14/PLAN.md

@@ -0,0 +1,35 @@
+# DefEssential 문서 현지화 및 Python 설명 문구 영어화 작업 계획
+
+## 목표
+
+[요구사항 명세서](./REQUIREMENTS.md)에 따라 사용자 문서와 Python 설명 문구를 현지화하고, PyPI 패키지 설명이 독립적인 영어 문서로 제공되도록 한다. 기존 공개 API와 실행 동작은 유지한다.
+
+## 작업 단계
+
+1. **현행 문서와 기능 확인**
+   - `README.md`, 샘플, 공개 API 및 패키지 설정을 확인해 현재 사용법과 공개 기능을 정리한다.
+   - 기존 `README.md`가 한국어 매뉴얼 요구사항을 충족하는지 검토하고, 누락된 설치·빠른 시작·기능 설명을 식별한다.
+2. **사용자 문서 작성**
+   - `README.md`를 요구사항에 맞는 한국어 매뉴얼로 정리한다.
+   - `README.en.md`를 작성하고 한국어 매뉴얼과 주요 주제 및 기능 범위를 맞춘다.
+   - PyPI에서 독립적으로 읽을 수 있는 `README.setup.md`를 영어로 작성한다. 외부 링크와 일반 텍스트 URL이 포함되지 않도록 확인한다.
+3. **PyPI 설명 연결**
+   - `setup.py`가 `README.setup.md`를 `long_description` 원본으로 읽도록 변경한다.
+   - 마크다운 콘텐츠 형식 및 패키지 메타데이터에 설명 본문이 포함되는지 확인한다.
+4. **Python 문구 조사 및 번역**
+   - 대상 Python 파일에서 한글이 포함된 독스트링, 주석, `raise` 예외 메시지를 분류한다.
+   - 테스트 데이터, 사용자 입력 예시 등 번역 제외 항목은 보존하고, 해당 문구만 의미를 유지해 영어로 바꾼다.
+   - 번역된 예외 메시지를 검증하는 테스트가 있다면 새 메시지에 맞춰 기대값을 갱신한다.
+5. **검증 및 회귀 확인**
+   - 대상 Python 파일의 한글 검색 결과를 검토해 남은 항목이 요구사항의 제외 범위에 해당하는지 확인한다.
+   - `README.setup.md`의 URL 및 링크를 검사하고, 패키지 메타데이터가 이 문서를 사용하고 있는지 확인한다.
+   - 관련 테스트를 실행하고 공개 API, 예외 유형, 프로토콜 계약 및 런타임 동작에 변경이 없는지 확인한다.
+
+## 검증 기준
+
+- `README.md`는 한국어, `README.en.md`와 `README.setup.md`는 영어로 작성되어 있다.
+- 두 사용자 매뉴얼은 주요 주제와 기능 범위가 대응하며, 문서의 설명과 예제가 실제 구현과 일치한다.
+- `README.setup.md`에 외부 URL이나 외부 페이지 링크가 없고, PyPI 설명 본문으로 사용된다.
+- 대상 Python 파일의 독스트링과 주석에 한국어 설명 문구가 남아 있지 않다. 발견된 잔여 한글은 번역 제외 대상임을 확인한다.
+- 대상 Python 파일의 사용자 노출 예외 메시지가 영어이며, 관련 테스트가 갱신되어 통과한다.
+- 관련 테스트가 통과하고, 변경 범위 밖의 API와 런타임 동작에 회귀가 없다.

defessential-0.1.8/issues/task/14/README.md

@@ -0,0 +1,7 @@
+# DefEssential 문서 현지화
+
+이전에는 저장소에서 한국어 사용자 안내가 제한적이었고, PyPI 패키지 설명은 저장소 README를 그대로 사용했습니다. 이제 한국어 매뉴얼과 이에 대응하는 영어 매뉴얼을 제공하며, 패키지 설치 페이지에는 별도의 간결한 영어 안내가 표시됩니다.
+
+Python 코드 설명도 영어로 통일했습니다. 공개 API와 애플리케이션의 실행 동작은 변경되지 않았으므로 기존 코드를 수정하거나 마이그레이션할 필요가 없습니다.
+
+설치와 빠른 시작은 PyPI 설명에서 바로 확인할 수 있습니다. 저장소의 전체 사용 안내는 한국어 [사용자 매뉴얼](../../../README.md)과 [영어 매뉴얼](../../../README.en.md)을 참고하세요.

defessential-0.1.8/issues/task/14/REQUIREMENTS.md

@@ -0,0 +1,84 @@
+# DefEssential 문서 현지화 및 Python 설명 문구 영어화 요구사항
+
+## 목적
+
+DefEssential 사용자 문서를 한국어와 영어로 제공하고, 프로젝트의 관리 대상 Python 파일에서 독스트링, 주석, 사용자에게 노출되는 예외 메시지를 영어로 통일한다. PyPI에는 별도의 영어 설명 문서를 게시해 패키지 소개가 영어로 표시되도록 한다.
+
+## 범위
+
+### 대상
+
+- `README.md`: 저장소의 한국어 사용자 매뉴얼
+- `README.en.md`: 저장소의 영어 사용자 매뉴얼
+- `README.setup.md`: PyPI 패키지 설명에 사용하는 영어 문서
+- `setup.py`: PyPI 설명 문서의 경로를 지정하는 패키지 설정
+- Python 문구 변경 대상:
+  - `src/`, `samples/`, `tests/` 아래의 Python 파일
+  - 프로젝트 루트의 `setup.py`
+
+### 제외
+
+- 공개 API, 식별자, 예외 유형, 제어 흐름, 데이터 형식 및 런타임 동작 변경
+- 독스트링·주석·예외 메시지 외의 사용자 인터페이스, 로그, 프로토콜 값, 테스트 입력 데이터 번역
+- 명시된 대상 경로 밖의 프로젝트와 Python 파일 변경
+
+## 기능 요구사항
+
+### DOC-01: 한국어 사용자 매뉴얼
+
+- `README.md`는 한국어로 작성한다.
+- 설치 방법, 빠른 시작, 주요 기능과 사용 방법을 포함한다.
+- 실제 프로젝트의 공개 기능 및 사용 방법과 일치해야 한다.
+
+### DOC-02: 영어 사용자 매뉴얼
+
+- `README.en.md`를 새로 작성한다.
+- `README.md`와 같은 주요 주제와 기능 범위를 다루는 영어 문서로 제공한다.
+- 설명과 예제가 실제 프로젝트의 API 및 동작과 일치해야 한다.
+
+### DOC-03: PyPI 패키지 설명
+
+- `README.setup.md`를 PyPI 패키지 페이지에 적합한 영어 문서로 새로 작성한다.
+- 프로젝트 소개, 설치 방법, 빠른 시작을 포함한다.
+- 문서에 외부 URL 또는 외부 웹 페이지로 연결되는 링크를 포함하지 않는다. 링크 형태의 외부 참조뿐 아니라 일반 텍스트로 표기한 외부 URL도 금지한다.
+- PyPI에서 독립적으로 표시되어도 목적과 설치·시작 방법을 이해할 수 있도록 작성한다.
+
+### PKG-01: PyPI 설명 문서 연결
+
+- `setup.py`의 `long_description`은 `README.setup.md` 내용을 읽어야 한다.
+- `long_description_content_type`은 마크다운 형식을 유지한다.
+- 패키지를 빌드했을 때 메타데이터의 설명 본문에 `README.setup.md` 내용이 포함되어야 한다.
+
+### PY-01: 독스트링과 주석
+
+- 범위에 포함된 Python 파일에서 한국어로 작성된 독스트링과 주석을 영어로 작성한다.
+- 문맥에 맞는 자연스러운 영어로 번역하되, 문서화 대상의 의미와 제약을 보존한다.
+- 기존에 이미 영어인 문구는 불필요하게 다시 작성하지 않는다.
+
+### PY-02: 예외 메시지
+
+- 범위에 포함된 Python 파일의 `raise` 문에서 사용자에게 노출되는 예외 메시지를 영어로 작성한다.
+- 메시지의 의미, 오류 상황, 사용자에게 필요한 조치 정보가 있다면 이를 보존한다.
+- 예외 유형, 발생 조건, 예외 체인 및 처리 동작은 변경하지 않는다.
+- 메시지가 테스트에서 검증되는 경우 기대 문자열도 새 메시지에 맞춰 갱신한다.
+
+## 제약 및 호환성
+
+- 변경은 문서 및 지정한 설명 문구에 한정한다.
+- 공개 API, 함수 인자와 반환값, 예외 유형, 프로토콜 계약, 실행 결과는 기존과 동일해야 한다.
+- 한국어가 포함된 테스트 데이터, 입력값, 임의의 사용자 콘텐츠는 번역 대상이 아니다. 검색 결과만을 기준으로 일괄 치환하지 않는다.
+- `README.setup.md`의 외부 링크 금지는 이 문서에만 적용한다. `README.md`와 `README.en.md`의 링크 정책은 이 요구사항에서 변경하지 않는다.
+
+## 수용 기준
+
+| ID | 기준 |
+| --- | --- |
+| AC-01 | `README.md`가 한국어로 설치, 빠른 시작, 주요 기능과 사용 방법을 설명한다. |
+| AC-02 | `README.en.md`가 `README.md`와 같은 주요 주제 및 기능 범위를 영어로 설명한다. |
+| AC-03 | `README.setup.md`가 영어로 프로젝트 소개, 설치 방법, 빠른 시작을 포함한다. |
+| AC-04 | `README.setup.md`에 외부 URL 및 외부 웹 페이지 링크가 없다. |
+| AC-05 | 패키지 설정이 `README.setup.md`를 마크다운 형식의 `long_description` 원본으로 사용한다. |
+| AC-06 | 대상 Python 파일의 독스트링과 주석에 한국어 설명 문구가 남아 있지 않다. |
+| AC-07 | 대상 Python 파일의 사용자 노출 예외 메시지가 영어이며, 변경한 메시지에 맞춰 관련 테스트가 갱신된다. |
+| AC-08 | 변경 후 관련 테스트가 통과하고 공개 API, 예외 유형, 프로토콜 계약 및 런타임 동작에 회귀가 없다. |
+| AC-09 | Python 파일의 한글 검색 결과를 검토해 남은 한글이 번역 제외 대상인지 확인한다. |