kpubdata 0.7.0__tar.gz → 0.9.0__tar.gz

kpubdata-0.9.0/.github/CODEOWNERS

@@ -0,0 +1,29 @@
+# R3 paths — changes here require CODEOWNER review (#520)
+/.github/                         @yeongseon
+/src/kpubdata/config.py           @yeongseon
+/src/kpubdata/transport/          @yeongseon
+/src/kpubdata/specs/              @yeongseon
+/docs/governance/                 @yeongseon
+# Credential host allowlist (#519, #629)
+/src/kpubdata/_hosts.py           @yeongseon
+# Evidence creation and judgement (#714) — the recorder, the verifier, the
+# authorship gate, and the evidence files themselves. A dataset is "verified"
+# by these paths; whoever changes them changes what verified means.
+/scripts/record.py                @yeongseon
+/scripts/verify_spec.py           @yeongseon
+/scripts/check_fixture_authorship.py @yeongseon
+/scripts/*_baseline.txt          @yeongseon
+/tests/fixtures/**/*.raw.json     @yeongseon
+/tests/fixtures/**/*.meta.json    @yeongseon
+/tests/fixtures/**/*.expected.json @yeongseon
+# Run by jobs holding `contents: write` — release notes, version, titles, window (#629, #685)
+/scripts/release_notes.py         @yeongseon
+/scripts/set_version.py           @yeongseon
+/scripts/next_version.py          @yeongseon
+/scripts/conventional_title.py    @yeongseon
+/scripts/release_window.py        @yeongseon
+# The R3 gate (#722): whoever changes it changes what an R3 approval means
+/scripts/r3_review.py             @yeongseon
+# Dependencies (#629)
+/pyproject.toml                   @yeongseon
+/uv.lock                          @yeongseon

kpubdata-0.9.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: 버그 리포트
+description: 예상과 다르게 동작하는 문제를 신고합니다
+title: "fix: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        버그를 신고해 주셔서 감사합니다. 재현에 필요한 정보를 최대한 채워주세요.
+  - type: textarea
+    id: summary
+    attributes:
+      label: 문제 요약
+      description: 무엇이 잘못되었나요?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 재현 절차
+      description: 문제를 재현하는 최소 코드 예시 또는 단계별 절차
+      placeholder: |
+        ```python
+        from kpubdata import Client
+        client = Client.from_env()
+        ...
+        ```
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 기대 동작
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: 실제 동작 / 오류 로그(traceback)
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: provider
+    attributes:
+      label: 관련 provider (해당 시)
+      placeholder: "예) datago, kosis, seoul"
+    validations:
+      required: false
+  - type: textarea
+    id: environment
+    attributes:
+      label: 실행 환경
+      description: OS, Python 버전, kpubdata 버전
+      placeholder: |
+        - OS: Ubuntu 24.04
+        - Python: 3.12
+        - kpubdata: x.y.z
+    validations:
+      required: false

kpubdata-0.9.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 질문 / 토론
+    url: https://github.com/kpubdata-lab/kpubdata/discussions
+    about: 버그·기능 제안이 아닌 사용법 질문이나 아이디어 토론은 여기서 나눠주세요.

kpubdata-0.9.0/.github/ISSUE_TEMPLATE/dataset-request.yml

@@ -0,0 +1,58 @@
+name: 데이터셋 추가 요청
+description: spec 기반으로 추가할 공공데이터셋을 요청한다
+title: "feat(datasets): "
+labels: [dataset-request]
+body:
+  - type: input
+    id: portal_url
+    attributes:
+      label: data.go.kr 데이터셋 URL
+      description: 활용가이드를 확인할 수 있는 공공데이터포털 페이지 URL
+    validations:
+      required: true
+  - type: input
+    id: dataset_id
+    attributes:
+      label: 제안 데이터셋 id
+      description: "{provider}.{dataset_key} 형식 (예: datago.air_quality)"
+      placeholder: datago.air_quality
+    validations:
+      required: true
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Provider
+      options:
+        - datago
+        - localdata
+        - semas
+        - lofin
+        - seoul
+        - neis
+        - kipris
+        - korean
+        - fds
+        - bok
+        - kosis
+        - law
+        - sgis
+        - krx
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: 우선순위
+      options:
+        - p0 (지금 필요)
+        - p1 (가까운 미래)
+        - p2 (여유 있을 때)
+    validations:
+      required: true
+  - type: textarea
+    id: reason
+    attributes:
+      label: 필요한 이유
+      description: 어떤 분석/서비스에 쓰이는지 간단히
+    validations:
+      required: true

kpubdata-0.9.0/.github/ISSUE_TEMPLATE/docs.yml

@@ -0,0 +1,19 @@
+name: 문서 개선
+description: 문서 오류, 누락, 개선 사항을 신고합니다
+title: "docs: "
+body:
+  - type: input
+    id: location
+    attributes:
+      label: 문서 위치
+      description: 파일 경로 또는 URL
+      placeholder: "예) README.md, docs/product-family-architecture.md"
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: 문제 / 개선 제안
+      description: 무엇이 부정확하거나 부족한가요? 어떻게 바뀌면 좋을까요?
+    validations:
+      required: true

kpubdata-0.9.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+name: 기능 제안
+description: 새로운 기능이나 개선을 제안합니다 (신규 provider는 별도 템플릿 사용)
+title: "feat: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        > 새로운 공공데이터 provider adapter 제안은 **New Provider Adapter** 템플릿을 사용해주세요.
+  - type: textarea
+    id: problem
+    attributes:
+      label: 해결하려는 문제
+      description: 어떤 불편이나 한계를 해결하려는 건가요?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: 제안 내용
+      description: 원하는 동작이나 API를 설명하세요.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 대안 검토
+      description: 고려한 다른 방법이 있다면 적어주세요.
+    validations:
+      required: false

kpubdata-0.9.0/.github/ISSUE_TEMPLATE/new-provider-adapter.yml

@@ -0,0 +1,104 @@
+name: New Provider Adapter
+description: Propose or track a new Korean public data provider adapter
+title: "feat(providers): "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## New Provider Adapter Request
+
+        Use this template to propose adding a new Korean public data provider.
+
+  - type: input
+    id: provider-name
+    attributes:
+      label: Provider Name
+      description: The official name of the data provider (Korean and English)
+      placeholder: "e.g., 서울열린데이터광장 (Seoul Open Data)"
+    validations:
+      required: true
+
+  - type: input
+    id: base-url
+    attributes:
+      label: API Base URL
+      description: The base URL for the provider's API
+      placeholder: "e.g., http://openapi.seoul.go.kr:8088"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: auth-type
+    attributes:
+      label: Authentication Type
+      options:
+        - API Key (query parameter)
+        - API Key (header)
+        - OAuth 2.0
+        - No auth
+        - Other (describe below)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: response-format
+    attributes:
+      label: Response Format
+      multiple: true
+      options:
+        - JSON
+        - XML
+        - CSV
+        - Excel
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: datasets
+    attributes:
+      label: Key Datasets
+      description: List the most important datasets this provider offers
+      placeholder: |
+        - 서울시 실시간 대기환경 (Real-time air quality)
+        - 서울시 공공자전거 대여소 (Public bike stations)
+    validations:
+      required: true
+
+  - type: textarea
+    id: api-docs
+    attributes:
+      label: API Documentation Links
+      description: Links to official API documentation
+      placeholder: "https://..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional Notes
+      description: Any quirks, rate limits, or special considerations
+      placeholder: |
+        - Rate limit: 1000 calls/day
+        - Requires registration at data.go.kr
+        - Some endpoints return EUC-KR encoding
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Implementation Checklist
+      description: Track progress (maintainer use)
+      options:
+        - label: "API research and documentation"
+        - label: "Adapter class with `name` property"
+        - label: "`list_datasets()` implementation"
+        - label: "`query_records()` with pagination"
+        - label: "`get_schema()` implementation"
+        - label: "`call_raw()` escape hatch"
+        - label: "Fixture responses captured"
+        - label: "Unit tests with fixtures"
+        - label: "Contract tests passing"
+        - label: "Capabilities documented honestly"

kpubdata-0.9.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+<!--
+PR 제목은 Conventional Commits 형식이어야 합니다 — `PR title` 체크가 검사합니다(POLICY 2.1.3).
+type: feat fix docs test perf refactor ci build chore style revert — 규칙 정본: docs/governance/POLICY.md 2.1.3
+이슈 번호는 제목이 아니라 본문에 적습니다 (Closes #123). squash 병합이 PR 번호를 붙입니다.
+예) feat: add KOSIS provider adapter
+-->
+
+Closes #<이슈 번호>
+<!-- 이슈 없는 PR(의존성 갱신 등)은 이 줄을 지우고, 참조만 남길 땐 Refs #N. -->
+
+## 문제
+<!-- 무엇이 잘못됐거나 무엇이 필요한지 — 대부분의 PR은 한두 문장이면 충분하다. -->
+
+## 변경 내용
+<!-- 무엇을 어떻게 바꿨는지 -->
+
+## 검증
+<!-- 돌린 게이트·테스트와 결과. ruff·mypy·pytest·docs strict 는 CI가 같은 걸 다시 돌리므로, 여기에는 로컬에서만 볼 수 있는 것(실측·재현·스크린샷)을 적는다. -->

kpubdata-0.9.0/.github/actions/conventional-title/action.yml

@@ -0,0 +1,56 @@
+name: Conventional title
+description: >
+  Parse an issue or pull request title as `type(scope): description` and say which
+  `type:*` label it implies (POLICY 2.1.3). Wraps scripts/conventional_title.py so the
+  three repositories use one parser. Never fails the step — callers decide what an
+  invalid title means, because a pull request should go red and an issue should not.
+
+inputs:
+  title:
+    description: "The title to check. Pass it from the event payload, never through `run:`"
+    required: true
+  pull-request:
+    description: >
+      "true" for a pull request title: it becomes the commit title on main, so it must
+      also be English, carry no issue reference and fit in 100 characters (POLICY 2.1.3,
+      #742). Issue titles leave it "false" — they may be Korean.
+    required: false
+    default: "false"
+
+outputs:
+  valid:
+    description: "true or false"
+    value: ${{ steps.run.outputs.valid }}
+  type:
+    description: "The Conventional Commits type, when valid"
+    value: ${{ steps.run.outputs.type }}
+  label:
+    description: "The type:* label the title implies, when valid"
+    value: ${{ steps.run.outputs.label }}
+  error:
+    description: "What is wrong with the title, when invalid"
+    value: ${{ steps.run.outputs.error }}
+
+runs:
+  using: composite
+  steps:
+    # The title is attacker-controlled text. It reaches the script through an
+    # environment variable, not by expansion into the shell line.
+    - id: run
+      shell: bash
+      env:
+        TITLE: ${{ inputs.title }}
+        PULL_REQUEST: ${{ inputs.pull-request }}
+      run: |
+        script="${{ github.action_path }}/../../../scripts/conventional_title.py"
+        args=()
+        if [ "${PULL_REQUEST}" = "true" ]; then
+          args+=(--pull-request)
+        fi
+        if out=$(python3 "${script}" "${args[@]}" "${TITLE}" 2>/tmp/title-error); then
+          echo "valid=true" >> "$GITHUB_OUTPUT"
+          echo "${out}" >> "$GITHUB_OUTPUT"
+        else
+          echo "valid=false" >> "$GITHUB_OUTPUT"
+          echo "error=$(sed 's/^::error:://' /tmp/title-error | head -1)" >> "$GITHUB_OUTPUT"
+        fi

kpubdata-0.9.0/.github/actions/r3-review/action.yml

@@ -0,0 +1,58 @@
+name: R3 review
+description: >
+  Fail a pull request labelled `review:R3` until a person other than its author, with
+  write access, currently approves it (#722, kpubdata-builder#905, POLICY 14). Passes
+  every other pull request, so the check can be required without leaving any pull
+  request waiting for it. Wraps scripts/r3_review.py so the four repositories run one
+  rule. Needs only `pull-requests: read`, so it works on fork pull requests too.
+
+inputs:
+  pr-number:
+    description: "The pull request to check; defaults to the event's"
+    required: false
+    default: ${{ github.event.pull_request.number }}
+  label:
+    description: "The label that requires a non-author approval"
+    required: false
+    default: "review:R3"
+
+outputs:
+  passed:
+    description: "true or false"
+    value: ${{ steps.run.outputs.passed }}
+  reason:
+    description: "Why"
+    value: ${{ steps.run.outputs.reason }}
+
+runs:
+  using: composite
+  steps:
+    # Labels and reviews are read live rather than from the event payload: a re-run
+    # replays the old payload, and a run triggered by a review must see the labels as
+    # they are now. A failed lookup fails the step — it must never read as "no label".
+    - id: run
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        REPO: ${{ github.repository }}
+        NUMBER: ${{ inputs.pr-number }}
+        LABEL: ${{ inputs.label }}
+      run: |
+        set -euo pipefail
+        if ! [[ "${NUMBER}" =~ ^[0-9]+$ ]]; then
+          echo "::error::no pull request number (got '${NUMBER}')"
+          exit 2
+        fi
+        dir="${RUNNER_TEMP}/r3-review"
+        mkdir -p "${dir}"
+        gh api "repos/${REPO}/pulls/${NUMBER}" > "${dir}/pull.json"
+        gh api --paginate "repos/${REPO}/pulls/${NUMBER}/reviews?per_page=100" --jq '.[]' \
+          > "${dir}/reviews.jsonl"
+        status=0
+        python3 "${{ github.action_path }}/../../../scripts/r3_review.py" \
+          --pull "${dir}/pull.json" --reviews "${dir}/reviews.jsonl" --label "${LABEL}" \
+          > "${dir}/out" || status=$?
+        cat "${dir}/out" >> "$GITHUB_OUTPUT"
+        sed -n 's/^reason=//p' "${dir}/out" >> "$GITHUB_STEP_SUMMARY"
+        sed -n 's/^reason=//p' "${dir}/out"
+        exit "${status}"

kpubdata-0.9.0/.github/actions/release-freeze/action.yml

@@ -0,0 +1,106 @@
+name: Release freeze
+description: >
+  Refuse pull requests that are not release pull requests while Builder or Studio
+  `main` is frozen (#701, docs/compatibility.md §5.1). The freeze starts on the
+  release week's Monday and ends when Studio ships in that week; a release pull
+  request is a `release/*` branch, a pull request touching only release files
+  (version, CHANGELOG, dependency pins, compatibility documents), or a body line
+  `Critical-Patch: #N`. Not applicable — not a pull request, or not targeting
+  `main` — exits 0, so the calling job is never skipped and the CI gate that needs
+  it keeps its meaning. Wraps scripts/release_freeze.py so the two repositories run
+  one rule.
+
+inputs:
+  github_token:
+    description: "A token with pull-request read access; the default works in the calling repository"
+    required: false
+    default: ${{ github.token }}
+  studio_repo:
+    description: "The repository whose shipping ends the freeze"
+    required: false
+    default: "kpubdata-lab/kpubdata-studio"
+  report_only:
+    description: "true to warn instead of failing — for dry runs"
+    required: false
+    default: "false"
+
+outputs:
+  frozen:
+    description: "true or false — whether main is frozen for this pull request"
+    value: ${{ steps.run.outputs.frozen }}
+  allowed:
+    description: "true or false"
+    value: ${{ steps.run.outputs.allowed }}
+  reason:
+    description: "Why"
+    value: ${{ steps.run.outputs.reason }}
+
+runs:
+  using: composite
+  steps:
+    # Every fact reaches the script through files or the environment, never by
+    # expansion into the shell line — a pull request body can contain anything
+    # (#628). Studio's releases are read cross-repository; both repositories are
+    # public, so the calling token can read them.
+    - id: run
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github_token }}
+        PR_URL: ${{ github.event.pull_request.html_url }}
+        BASE_REF: ${{ github.event.pull_request.base.ref }}
+        STUDIO_REPO: ${{ inputs.studio_repo }}
+        REPORT_ONLY: ${{ inputs.report_only }}
+      run: |
+        not_applicable() {
+          echo "frozen=false" >> "$GITHUB_OUTPUT"
+          echo "allowed=true" >> "$GITHUB_OUTPUT"
+          echo "reason=$1" >> "$GITHUB_OUTPUT"
+          echo "::notice::$1"
+          exit 0
+        }
+
+        if [ -z "${PR_URL}" ]; then
+          not_applicable "not a pull request event — the freeze does not apply"
+        fi
+        if [ "${BASE_REF}" != "main" ]; then
+          not_applicable "targets '${BASE_REF}', not main — the freeze does not apply"
+        fi
+
+        pr_json=$(mktemp)
+        branch_file=$(mktemp)
+        body_file=$(mktemp)
+        files_file=$(mktemp)
+        gh pr view "${PR_URL}" --json headRefName,body,files > "${pr_json}" \
+          || { echo "::error::could not read the pull request"; exit 1; }
+
+        python3 - "${pr_json}" "${branch_file}" "${body_file}" "${files_file}" <<'PY'
+        import json
+        import sys
+
+        pr = json.load(open(sys.argv[1], encoding="utf-8"))
+        with open(sys.argv[2], "w", encoding="utf-8") as out:
+            out.write(pr["headRefName"])
+        with open(sys.argv[3], "w", encoding="utf-8") as out:
+            out.write(pr["body"] or "")
+        with open(sys.argv[4], "w", encoding="utf-8") as out:
+            out.write("\n".join(f["path"] for f in pr["files"]))
+        PY
+        head_branch=$(cat "${branch_file}")
+
+        # Studio's final releases: a publish inside this window ends the freeze.
+        studio_times=$(gh release list --repo "${STUDIO_REPO}" \
+          --exclude-drafts --exclude-pre-releases --limit 100 \
+          --json publishedAt --jq '.[].publishedAt' | tr '\n' ' ')
+
+        args=(--head-branch "${head_branch}"
+              --body-file "${body_file}"
+              --files-from "${files_file}"
+              --studio-release-times "${studio_times}")
+        if [ "${REPORT_ONLY}" = "true" ]; then args+=(--report-only); fi
+
+        python3 "${{ github.action_path }}/../../../scripts/release_freeze.py" \
+          "${args[@]}" >> "$GITHUB_OUTPUT"
+        freeze_status=$?
+
+        rm -f "${pr_json}" "${branch_file}" "${body_file}" "${files_file}"
+        exit "${freeze_status}"

kpubdata-0.9.0/.github/actions/release-notes/action.yml

@@ -0,0 +1,72 @@
+name: Release notes
+description: >
+  Take a release's notes from its CHANGELOG section, or put that section in place.
+  Wraps scripts/release_notes.py so the three repositories call one implementation.
+  `extract` fails when the section is missing or empty, so a release without notes
+  stops before a tag exists.
+
+inputs:
+  command:
+    description: "promote (prepare job) or extract (release job)"
+    required: true
+  version:
+    description: "The version being released, with or without the leading v"
+    required: true
+  changelog:
+    description: "Path to the CHANGELOG"
+    required: false
+    default: CHANGELOG.md
+  output:
+    description: "Where extract writes the notes (default: the runner's temp directory)"
+    required: false
+    default: ""
+
+outputs:
+  file:
+    description: "The notes file (extract only)"
+    value: ${{ steps.run.outputs.file }}
+  prerelease:
+    description: "true when the version is a pre-release (aN, bN, rcN) — pass --prerelease to gh release create (#622)"
+    value: ${{ steps.run.outputs.prerelease }}
+
+runs:
+  using: composite
+  steps:
+    # The link at the bottom compares against the previous release tag. A first
+    # release has none, so it links the history up to the new tag instead — the tag
+    # does not exist yet while this runs, but will by the time anyone clicks.
+    - id: run
+      shell: bash
+      env:
+        COMMAND: ${{ inputs.command }}
+        VERSION: ${{ inputs.version }}
+        CHANGELOG: ${{ inputs.changelog }}
+        OUTPUT: ${{ inputs.output }}
+        REPO: ${{ github.repository }}
+      run: |
+        script="${{ github.action_path }}/../../../scripts/release_notes.py"
+        if [ "${COMMAND}" = "promote" ]; then
+          python3 "${script}" promote "${VERSION}" --changelog "${CHANGELOG}"
+          exit $?
+        fi
+        OUTPUT="${OUTPUT:-${RUNNER_TEMP}/release-notes.md}"
+        tag="v${VERSION#v}"
+        prerelease=$(python3 "${script}" prerelease "${VERSION}")
+        echo "prerelease=${prerelease}" >> "$GITHUB_OUTPUT"
+        # A final release's notes fold in its pre-releases (#622), so its link
+        # compares against the previous final release, not the last pre-release.
+        exclude=()
+        if [ "${prerelease}" = "false" ]; then
+          exclude=(--exclude 'v*[a-z]*')
+        fi
+        previous=$(git describe --tags --abbrev=0 --match 'v[0-9]*' "${exclude[@]}" HEAD 2>/dev/null || true)
+        if [ -n "${previous}" ] && [ "${previous}" != "${tag}" ]; then
+          compare="https://github.com/${REPO}/compare/${previous}...${tag}"
+        else
+          compare="https://github.com/${REPO}/commits/${tag}"
+        fi
+        python3 "${script}" extract "${VERSION}" --changelog "${CHANGELOG}" \
+          --compare-url "${compare}" --output "${OUTPUT}"
+        echo "file=${OUTPUT}" >> "$GITHUB_OUTPUT"
+        echo "notes for ${tag}:"
+        cat "${OUTPUT}"