Repository navigation
docs(python): help()·IDE 호버에 뜨는 공개 API 독스트링과 예제 주석을 영문으로 — 아홉 SDK 번역 끝 (korean-api-docs-in-published-packages 판정) - #898
Merged
Merged
Conversation
…c·exceptions (korean-api-docs-in-published-packages) `pydoc.render_doc` 이 그리는 독스트링만 옮겼다 — 공개 모듈(`_public_module`)의 모듈 독스트링, `__all__` 의 객체와 그 공개 멤버·dunder. 대상: `keycloak_sdk/__init__.py` · `aio/__init__.py` · `client.py` · `aio/client.py` · `config.py` · `tokens.py` · `oidc.py` · `exceptions.py`. 비공개 `_of` 의 독스트링, `#` 주석(설정 필드 설명 포함 — pydoc 이 그리지 않는다), `KeycloakConfigError` 의 한글 메시지(런타임 문구 — 별건)는 그대로 둔다. 코드는 바꾸지 않았다(독스트링을 자리표시자로 바꾼 AST 가 main 과 같다). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp
…cs-in-published-packages) `AuthClient`·`AsyncAuthClient`·`AuthorizationUrl` 의 클래스 독스트링, 공개 메서드(인가 URL·세 그랜트· introspect·validate·close/aclose)의 독스트링과 두 모듈 독스트링만 옮겼다. 비공개 `_wrap`·`_awrap`· `_validate_for`·`_load_jwks`·`_refetch_jwks`·`_refetch_done`·`_fetch_jwks`·`_afetch_jwks`· `_generate_pkce_pair` 의 독스트링과 `#` 구현 주석은 그려지지 않아 그대로 둔다. 코드는 바꾸지 않았다(AST 동일). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp
…api-docs-in-published-packages) `admin/`·`aio/admin/` 의 공개 모듈 열 둘 — `AdminClient`·`AsyncAdminClient` 와 리소스 다섯 쌍의 모듈·클래스 독스트링, 공개 메서드(`raw`·`get`·`list`·`update`·`find_by_client_id`·`close`/`aclose`)의 독스트링만 옮겼다. 비공개 `_translate` 모듈, `#` 구현 주석, `KeycloakConfigError` 의 한글 메시지(런타임 문구 — 별건)는 그대로 둔다. 범위 표기 `4.2~4.4` 는 "4.2 through 4.4" 로 옮겼다(en dash 는 ruff RUF002 가 막는다). 코드는 바꾸지 않았다(AST 동일). 이것으로 pydoc 덤프의 한글 줄이 358 → 0 이다. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp
…i-docs-in-published-packages) 루트 README 표와 python/README 의 「Full examples」가 `examples/quickstart.py` · `examples/async_quickstart.py` 로 보내고 소비자가 그대로 베낀다. 모듈 독스트링과 `#` 주석만 옮겼다 — 긴 줄 끝 주석 하나는 줄 길이 100 을 지키려고 "env vars" 로 줄였다. 코드는 바꾸지 않았다(AST 동일) · examples 한글 28 → 0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp
…d` 를 가리키게 읽혔다 원문 둘째 문장은 주어가 없어 클래스를 가리키는데, 영문 "It" 은 바로 앞 문장의 주어 `openid` 로 읽혔다 → "This client has …". 검토 지적 중 기각 둘: 「권한 role」 → "permission roles"(한국어는 수를 표시하지 않는다) · 「`&`가 뒤따르는 값」 → "the value following a `&`"(쿼리 파라미터로 주입되는 것은 실제로 `&` 뒤의 값이다). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp
- 등록부 `korean-api-docs-in-published-packages`: 번역 끝(#890–#898) · 표제를 남은 것으로 — 다시 들어오지 않게 하는 CI 가드(오라클을 레인에 걸지 않으면 새 한글 문서 주석이 들어온다 · pydoc 이 독스트링 없는 def 위의 # 주석을 그리는 함정) · 런타임 오류 문구(node 하나 · python KeycloakConfigError 넷 · ruby·php·go·kotlin 0 · rust·java·.NET 미측정). 언어별 수와 덤프 스크립트는 각 PR 본문으로 보내 줄을 줄였다 — 원본 199954 앵커 아래 161B · 모양 28/0. - CHANGELOG [Unreleased] Changed: (Python) 한 줄 — 아홉 SDK 의 그려지는 문서가 모두 영문(착지 16/0). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp
|
Owner
Author
|
통합 시험 잡의 첫 실패는 이 PR 과 무관한 testcontainers Keycloak 준비 탐침의 경합이었다 — 관리 포트(9000)가 연결 오류면 주 포트(8080)의 🤖 Generated with Claude Code |
This was referenced Oct 29, 2026
xzawed
added a commit
that referenced
this pull request
Oct 29, 2026
…션 전체가 setup 오류였다 (#899) testcontainers 의 `_readiness_probe` 는 관리 포트(9000)가 연결 오류면 주 포트(8080)의 `/health/ready` 로 넘어가는데, Keycloak 25+ 의 주 포트에는 health 가 없어 404 이고 `raise_for_status` 의 HTTPError 는 데코레이터가 재시도하지 않는다 (ConnectionError·ReadTimeout 만). 기동 중 주 포트가 먼저 열리면 그 순간 실패해 통합 시험 31 개가 setup 오류였다 (#898 의 CI 2026-10-29 — 실패 URL 이 주 포트 `localhost:32769/health/ready` · 같은 코드로 실패 잡만 다시 돌리니 통과). `KeycloakContainer` 를 상속해 404 면 관리 포트가 열릴 때까지(180 초 한도) 다시 묻는다 — 부모 탐침을 그대로 부르므로 testcontainers 4.14·4.15 어느 구조에도 맞는다. 로컬 Docker 로 통합 시험 31 개 통과(rc 0). ruff · format 깨끗. Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
xzawed
added a commit
that referenced
this pull request
Oct 29, 2026
…I 하위 판 함정 - 진입점 1번: 판정 수행이 끝났다 — 남은 칸은 각 항목이 적는다(응답 기한 · 번역 가드 · php (6) · framing node 상류 보고). - 지금 상태: `[Unreleased]` 에 아홉 언어 다 변화가 있다 — 다음 물결은 사람 몫. - 함정 3번: CI 의 하위 판(urllib3 2.8 · CPython 트레일러 상한)이 대조군을 뒤집었다(#893) — 대조군은 동작으로 가른다 · 충돌한 PR 에는 실행이 안 생긴다. 옛 예시 셋(jwks 600 초 경계 · node·.NET · probe.sh 정규식)은 git 이력이 소유한다. - 판정 문단: 라운드 2(#892) 포인터. 적재 174781 이하 · 원본 199954 앵커 아래 48B · 모양 28/0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp
xzawed
added a commit
that referenced
this pull request
Oct 29, 2026
…I 하위 판 함정 (#900) - 진입점 1번: 판정 수행이 끝났다 — 남은 칸은 각 항목이 적는다(응답 기한 · 번역 가드 · php (6) · framing node 상류 보고). - 지금 상태: `[Unreleased]` 에 아홉 언어 다 변화가 있다 — 다음 물결은 사람 몫. - 함정 3번: CI 의 하위 판(urllib3 2.8 · CPython 트레일러 상한)이 대조군을 뒤집었다(#893) — 대조군은 동작으로 가른다 · 충돌한 PR 에는 실행이 안 생긴다. 옛 예시 셋(jwks 600 초 경계 · node·.NET · probe.sh 정규식)은 git 이력이 소유한다. - 판정 문단: 라운드 2(#892) 포인터. 적재 174781 이하 · 원본 199954 앵커 아래 48B · 모양 28/0. Claude-Session: https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
xzawed
added a commit
that referenced
this pull request
Oct 30, 2026
…ean-api-docs-in-published-packages) (#908) * fix(node·python): 런타임 오류 메시지 다섯을 영문으로 — 재유입은 레인 단위 시험이 AST 로 잡는다 (korean-api-docs-in-published-packages) 그려지는 문서 주석은 #890–#898 이 아홉 다 영문으로 옮겼고, 등록부가 별건으로 남긴 칸이 소비자에게 닿는 런타임 문구였다(등록부 637행). 그 칸을 닫는다. 바뀐 문구(예외 타입·원인 사슬은 그대로): - node `KeycloakTokenValidationError`: `JWT 검증 실패: …` → `JWT validation failed: …` (src/jwt.ts) - python `KeycloakConfigError` 넷: client.py · aio/client.py · admin/__init__.py · aio/admin/__init__.py 전수 측정(주석이 아니라 값만): - python: ast — 독스트링이 아닌 문자열 상수의 한글 4(이 넷). 독스트링 117 은 범위 밖. - node: TS 컴파일러 API — 문자열·템플릿 리터럴의 한글 1(jwt.ts:362). - 나머지 일곱: 같은 줄 따옴표 안 한글(주석 줄 제외) — java·kotlin·go·.NET·php 0 · ruby 1(줄 끝 주석) · rust 43(전부 각 파일 `#[cfg(test)]` 줄 뒤의 시험 문구). java·kotlin·.NET 여러 줄 리터럴 (`"""`·`@"`) 0 · 리소스 파일 한글 0. → 소비자에게 닿는 것은 이 다섯이 전부였다. 가드: 두 레인에 단위 시험 `runtime-strings-english` — node 는 문자열·템플릿 리터럴, python 은 독스트링이 아닌 상수에서 한글 0 을 단언한다. 대조군 셋: 양성(메시지 안의 한글을 잡는다) · 음성(주석·독스트링만 있으면 0) · 공허 방지(훑은 파일 > 10). 한글 범위는 이스케이프 대신 `String.fromCharCode`·`chr` 로 쓴다(Edit 툴이 `\u` 를 글자로 푸는 함정 (aa)). 옛 문구를 대조하던 node 시험 넷을 새 문구로 옮겼다. python 시험은 이 문구를 대조하지 않았다. 검증: npx vitest run(해당 4 파일 54 통과) · npm run typecheck · eslint · prettier --check · ruff check/format(src tests examples) · mypy src · check-docs rc=0 · test-remaining-work-shape 28/0 · 등록부 raw 199,906 → 199,831 · CHANGELOG 항목 643 B. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS4tpj7usahf8MK5dXo * test(node·python): 런타임 한글 검출기를 식별자까지 넓힌다 — Grok 적대 레그 QN 채택 Grok 적대 레그(검출기 두 개의 코드만 · 닫힌 질문 셋)의 답을 하나씩 가렸다: - QN 채택 — TS 객체 키 `{ 대기: 1 }` 은 문자열 리터럴이 아니라 Identifier 라 놓쳤는데 `Object.keys` 로 런타임 문자열이 된다. node 는 Identifier·PrivateIdentifier 를, python 은 같은 축(Name.id · Attribute.attr · def/class 이름 · arg · keyword · import 별칭)을 더 본다. 지금 src 는 둘 다 0. - QP 기각 — `raise RuntimeError(chr(0xAC00))` 은 실행 중 조립이다. 소스의 값이 아니라 데이터 흐름을 봐야 하고, 사보타주 꼴이다(계약 밖). - QF 의도 — `type Code = "대기"` 는 런타임에 지워지지만 방출 `.d.ts` 로 소비자 IDE 에 보인다. 걸리는 것이 맞다 — 대조군으로 고정했다. 대조군 추가: node `{ 대기: 1 }` → 1 · `type Code = "대기"` → 1 / python `class 오류(Exception)` → 1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS4tpj7usahf8MK5dXo --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
xzawed
added a commit
that referenced
this pull request
Oct 30, 2026
… java 를 빠뜨렸다 (korean-api-docs-in-published-packages) (#913) * docs(java): Maven Central 에 게시되는 javadoc 과 QuickStart 예제 주석을 영문으로 — 번역 판정이 java 를 빠뜨렸다 (korean-api-docs-in-published-packages) 판정 2026-10-29 「번역 — 언어당 PR」은 일곱 언어(#890–#898)만 옮겼고, CHANGELOG 는 「아홉 SDK 의 그려지는 문서가 모두 영문」이라 적었다. 그려지는 문서 가드를 레인마다 걸려고 재다가 java 가 0 이 아님을 찾았다 — 게시용 `-javadoc.jar`(`-Prelease package`, reactor 안) 122 HTML 에 한글 221 줄: facade 20 · admin 138 · auth 5 · core 50 · examples 8. (.NET 은 XML 문서 파일이 이미 0 줄이다.) 범위: 그 221 줄을 낳는 11 파일의 javadoc(공개·protected 요소)과, README 가 링크하는 QuickStart.java 의 주석. 비공개·package-private 의 javadoc 과 그 밖의 `//` 주석(66 줄)은 그려지지 않아 그대로 뒀다. 정정 하나: QuickStart 의 「모듈 POM 의 `maven.deploy.skip=true` 로 배포되지 않는다」는 원문부터 거짓이었다 — 그 속성은 무효였고(examples 모듈 POM 의 주석), 제외 장치는 부모 POM 의 `<excludeArtifacts>` 다. 구현은 에이전트(지정 11 파일 · 금지 목록 · 검증 명령)가 했고, PM 이 다른 계측기로 다시 쟀다: - 오라클: 같은 `package` → 122 파일 · 한글 0(양성 대조: core 의 영문 요약이 index 에 있다) - 코드 불변: `javap -v -p`(상수 풀 · 부트스트랩 메서드 포함 — 줄 번호 표 · 체크섬 · 시각만 거름)를 main 빌드와 비교 — 59 클래스 22,687 줄 동일. 대조: 필터 뒤 남은 상수 풀 · 부트스트랩 줄 4,755. - 에이전트의 `javap -c -p -constants` 도 동일(8,431 줄, SHA-256 같음). - 번역 충실도: ResponseLimits · KeycloakConfig · AdminClient · QuickStart 를 원문과 나란히 읽었다 — 수치(65,459 B · 32 MiB/170 MB/17.2 GB · 85 B · 9)와 조건·인과가 그대로다. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS4tpj7usahf8MK5dXo * ci(java) · docs: java 레인이 번들의 -javadoc.jar 를 센다 · CHANGELOG · 등록부 항목을 닫는다 (korean-api-docs-in-published-packages) java 레인 가드 — `release-bundle` 잡이 만드는 Central 번들(게시되는 그대로, examples 는 부모 POM 의 <excludeArtifacts> 로 빠진다)에서 `*-javadoc.jar` 를 꺼내 풀고 #911 의 계수기로 센다. 번들에 javadoc 이 없으면 읽은 파일 0 으로 실패한다(exit 2). `paths:` 에 계수기를 더했다. 로컬 실측 — CI 와 같은 명령(versions:set 0.0.0-bundle-check → -Prelease deploy -DskipUpload)으로 번들을 만들어: 번역 뒤: javadoc jar 4 · 110 HTML · 한글 0 ResponseLimits 의 공개 javadoc 에 한글 한 줄을 심어 다시 만들면: `ResponseLimits.html:97` 한 줄을 잡는다 (그 실행의 「rc=0」은 내 검증 스크립트가 `| head` 로 계수기의 종료코드를 가린 탓이다 — CI 단계는 파이프 없이 `set -euo pipefail` 아래에서 돌고, 계수기가 발견 시 1 을 내는 것은 자가테스트가 고정한다). CHANGELOG — python 항목 끝의 「이로써 아홉 SDK 의 그려지는 문서가 모두 영문입니다」는 그때 거짓이었다(java). 그 문장을 떼고 java 항목에 붙였다 — 이 PR 이 들어가면 참이다. 등록부 — 항목을 닫는다(표제 한 줄): 그려지는 문서는 아홉 레인 가드(#911 · #912 · 이 PR), 런타임 문구는 #908. 진입점을 2026-10-30 으로 고치고 남은 칸 목록에서 이 항목을 뺐다. 함정 한 줄: 측정이 도는 워크트리를 지우지 않는다 — 옛 오탐 측정기가 `|| true` 로 git 실패를 삼켜 거짓 수(존재 408 · 불일치 1)를 냈다. D 절 머리 열림 51 → 50 · 「규모」의 날짜 붙은 수 → 2026-10-30 기준 열림 130 · 닫힘 154. 예산 래칫(검사 8e)대로 앵커를 내렸다: 적재 174,781 → 173,995 · raw 199,954 → 199,140. 검증(main d5d7789 위): test-remaining-work-shape 28/0 · test-selftest-hygiene 241/0 · check-ci-permissions rc=0 · check-docs rc=0 · test-changelog-landing 16/0 · test-changelog-ledger 68/0 · CHANGELOG java 항목 468 B. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R4jYS4tpj7usahf8MK5dXo --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



무엇
판정 2026-10-29
korean-api-docs-in-published-packages「번역 — 언어당 PR」의 마지막, Python 다(rust #890 · node #891 · ruby #894 · php #895 · go #896 · kotlin #897 — java·.NET 은 원래 0). 이로써 아홉 SDK 의 그려지는 문서가 모두 영문이다. 옮긴 것은 둘이다:help()·IDE 호버에 뜨는 공개 API 의 독스트링.examples/quickstart.py·examples/async_quickstart.py의 독스트링·주석.판정 기준(기계 — 소유자 출력)
레그의 오라클 스크립트(커밋 안 함)가
keycloak_sdk.__all__·keycloak_sdk.aio.__all__의 export 19 개와 공개 모듈 22 개에pydoc.render_doc(…, renderer=pydoc.plaintext)를 돌린다. 타입 힌트로 닿는 SDK 클래스도 대상이다(추가분 0).tests/unit/test_hostile_path_matrix.py의_public_module·_members_of·_is_own이다.Python Library Documentation40 줄.코드 불변 — AST
독스트링을 지우지 않고 자리표시(
"<doc>")로 바꾼 뒤ast.dump(include_attributes=False)를 비교했다. 독스트링이 다른 객체로 옮겨 붙거나, 생기거나, 사라져도 잡힌다.files=24 diff=0).30.0→31.0이 DIFF 로 잡힌다.client_secret=…두 줄뿐이다.게이트(레그 — 전 → 후 같음)
not integration·--cov)mypy src(strict)test_facade_dump등)--against py-v1.0.6)py-v0.1.0은 rc 1test-security-defaultscheck-docsconfig.py:24는#주석이라 그려지지 않는다.독립 검토(Grok — 커밋별 다섯 파일, 「뜻이 움직인 자리」만)
AuthClient와 동일한 …」의 영문 "It" 이 바로 앞 문장의openid로 읽혔다 → 받음. "This client has …" 로 고쳤다.&가 뒤따르는 값」은 문법상 「&앞의 값」이라는 지적 → 기각. 쿼리 파라미터로 주입되는 것은 실제로&뒤의 값이고, 영문이 기술적으로 맞다.레그가 확신하지 못한 문장(사람이 보면 좋은 자리)
TokenSignatureError「재조회해도 소용없는 실패」.KeycloakAdminError「되울릴 수 있다」 → "can echo back".ClientsResource「python-keycloakclient_id파라미터명과 동일하나 실제로는 UUID」.authorization_url「…최상위 쿼리 파라미터로 주입했고」.AsyncAdminClient.aclose「둘 다」를 복수로 읽었다.원문 내용의 의문(그대로 옮김)
authorization_url의 「sync 는openid.auth_url()을 쓰지만」은 낡은 문장이다. 「sync 와 달리async def가 아니다」도 sync 역시 async 가 아니라 원문부터 어색하다.AdminClient모듈의 「WBS 4.2~4.4 에서 단계적으로 추가된다」는 계획 시절 문장이다._internal/…· 비공개 이름).소비자에게 보이는 한글 런타임 문구(바꾸지 않음 — 등록부 항목의 남은 칸)
KeycloakConfigError메시지 넷이다(고정한 시험 없음):admin/__init__.py:48aio/admin/__init__.py:52client.py:68aio/client.py:74AsyncKeycloakClient.create(config)판찾았지만 안 바꾼 것
config.py:21–30: 공개 필드signature_algorithms·jwks_min_refetch_seconds·expected_audience를 설명하는 유일한 글이#주석이라 pydoc 이 그리지 않는다. 그려지게 하려면 구조 변경이다(별건 — 문서 부재).mask:__all__에 있지만 독스트링이 없다. 독스트링 없이 시그니처만 그려지는 공개 객체가 49 개다.#주석 블록을 대신 그린다(inspect.getcomments). 등록부 가드 칸에 적었다.등록부 — 항목을 남은 것으로 좁혔다
번역은 끝났다. 그래서 표제를 「남은 것: 다시 들어오지 않게 하는 CI 가드 · 런타임 오류 문구」로 바꿨다.
함께 실은 것
CHANGELOG
[Unreleased]### Changed한 줄.🤖 Generated with Claude Code
https://claude.ai/code/session_01R4jYS5GwFA8V5oAqjw8pMp