pykosis 0.1.0__tar.gz

pykosis-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "pykosis",
+  "interface": {
+    "displayName": "kosis"
+  },
+  "plugins": [
+    {
+      "name": "kosis",
+      "source": {
+        "source": "local",
+        "path": "./plugins/kosis"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

pykosis-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "name": "pykosis",
+  "owner": {
+    "name": "seokhoonj"
+  },
+  "description": "Read KOSIS (Statistics Korea) national statistics",
+  "plugins": [
+    {
+      "name": "kosis",
+      "displayName": "kosis",
+      "source": "./plugins/kosis",
+      "description": "Read KOSIS (Statistics Korea) national statistics",
+      "author": {
+        "name": "seokhoonj"
+      },
+      "homepage": "https://github.com/seokhoonj/pykosis",
+      "category": "Productivity",
+      "keywords": [
+        "kosis",
+        "statistics korea",
+        "korea",
+        "official statistics",
+        "census"
+      ]
+    }
+  ]
+}

pykosis-0.1.0/.github/workflows/check.yml

@@ -0,0 +1,25 @@
+name: check
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+
+# A newer push to the same branch or PR makes the older run's result obsolete,
+# so cancel it rather than let both run to completion. The event name is in the
+# key so a push never cancels a pull-request run, or vice versa.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# The check only reads the code to lint, type, and test it -- it never writes to the
+# repo -- so it runs with the least privilege that still allows a checkout.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    # The full check lives in reusable-check.yml so the release gate in
+    # publish.yml runs the identical job on the release commit.
+    uses: ./.github/workflows/reusable-check.yml

pykosis-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: publish
+
+# Publish to PyPI on a GitHub Release, via PyPI Trusted Publishing (OIDC): no API
+# token or password is stored anywhere -- GitHub mints a short-lived identity token
+# that PyPI verifies against the publisher registered for this repo (owner seokhoonj
+# / repo pykosis / this workflow / environment "pypi").
+#
+# Three jobs. `gate` runs the same reusable check that check.yml runs, on the
+# release commit, so a red build (a lint/type error, a broken test, a lost py.typed
+# or console script) cannot reach an upload. `build` builds the sdist and wheel and
+# hands them to `publish` as an artifact. `publish` -- the only job holding the OIDC
+# token -- downloads that artifact and uploads it, and checks out no source, so the
+# privileged step runs the least code.
+
+on:
+  release:
+    types: [published]
+
+# Workflow-level floor: any job without its own `permissions:` block still gets a
+# read-only token, so a job added later cannot silently inherit a write-capable
+# default. The build and publish jobs narrow it further below.
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    uses: ./.github/workflows/reusable-check.yml
+
+  build:
+    needs: gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: Build sdist and wheel, then check the metadata
+        run: |
+          uv build
+          uvx twine check dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC; this is what replaces a stored token
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1

pykosis-0.1.0/.github/workflows/reusable-check.yml

@@ -0,0 +1,98 @@
+name: reusable check
+
+# The full check -- tests, lint, types, and the packaging assertions -- factored
+# into one reusable job so both `check.yml` (on push / PR) and the release gate in
+# `publish.yml` run the *identical* thing. One definition is what makes "publish
+# gates on the full check" true; a second hand-maintained copy would drift, and a
+# check added here silently would not gate releases.
+
+on:
+  workflow_call:
+
+# The floor lives on the shared body, not only on `check.yml`: `publish.yml`'s gate
+# calls this same workflow, and if the floor were only on `check.yml` the gate would
+# run this check with the repo-default (possibly write) token. Declared here, the
+# check is read-only from every caller. A reusable workflow can only downscope from
+# the caller, so this never widens anyone's token.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # Every minor release from the requires-python floor (>=3.11) through the
+        # current stable CPython -- the same set the trove classifiers advertise, so
+        # each is an audit of the other (no version claimed but untested).
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+
+      - name: Install
+        # A venv per matrix version, not `uv pip --system`: the runner's system
+        # Python is externally managed and is one fixed version whatever the matrix
+        # says. This is also what the README tells a person to run.
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e ".[dev]"
+          .venv/bin/python -c "import sys; print('testing on', sys.version)"
+
+      - name: Test
+        run: .venv/bin/pytest -q
+
+      - name: Lint
+        run: .venv/bin/ruff check src tests
+
+      - name: Types
+        run: .venv/bin/mypy src
+
+      - name: Confirm the only runtime dependency is httpx
+        # A bare install must pull in nothing but httpx; a second runtime dependency
+        # creeping into `dependencies` is caught here rather than in a user's
+        # environment.
+        run: |
+          uv venv /tmp/bare --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/bare/bin/python .
+          /tmp/bare/bin/python -c "
+          import re
+          import importlib.metadata as md
+          requires = md.requires('pykosis') or []
+          runtime = [r for r in requires if 'extra ==' not in r]
+          # Each requirement's bare name (before any version/marker/extra), PEP 503
+          # normalized; the runtime set must be exactly httpx.
+          names = sorted(re.split(r'[<>=!~;\[\s]', r, maxsplit=1)[0].replace('_', '-').lower() for r in runtime)
+          assert names == ['httpx'], f'unexpected runtime dependencies: {runtime}'
+          import pykosis
+          print('pykosis imports with only httpx')
+          "
+          # The console script runs, and its top-level --version prints (not shoved
+          # into a required subcommand).
+          /tmp/bare/bin/kosis --version
+
+      - name: Confirm a user's type checker can see the hints
+        # Every hint in this package is invisible to a user unless py.typed ships
+        # alongside it (PEP 561), and the source cannot answer whether it did:
+        # src/pykosis/py.typed can sit in git while the built wheel omits it. So ask
+        # it the way a user does -- install the built package into a clean
+        # environment and run their checker over their code.
+        run: |
+          uv venv /tmp/typed --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/typed/bin/python . mypy
+          cat > /tmp/user_code.py <<'PY'
+          from pykosis import KOSIS
+
+          # start_period takes str | None; an int is neither, so a checker that can see
+          # the shipped hints must reject it. If py.typed is missing from the wheel,
+          # mypy skips pykosis instead and emits no such error.
+          KOSIS(api_key="k").fetch_data(org_id="101", tbl_id="DT_1B42", start_period=123)
+          PY
+          /tmp/typed/bin/mypy /tmp/user_code.py > /tmp/mypy_out 2>&1 || true
+          cat /tmp/mypy_out
+          grep -q 'incompatible type' /tmp/mypy_out

pykosis-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# uv
+uv.lock
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local scratch (never tracked)
+dev/
+refs/
+
+# AI coding agents
+CLAUDE.md
+.claude/
+AGENTS.md
+AGENT.md
+.codex/
+GEMINI.md
+.gemini/

pykosis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seokhoon Joo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.