Upstream changes from the internal mirror

.env → .env.template

@@ -13,4 +13,4 @@ version=9.0
 # Bearer token for authentication
 #splunkToken="<Bearer-token>"
 # Session key for authentication
-#token="<Session-Key>"
+#token="<Session-Key>"

.github/actions/setup-sdk-environment/action.yml

@@ -0,0 +1,22 @@
+name: Set up SDK environment
+description: Perform all the shared setup steps
+
+inputs:
+  python-version:
+    description: Python version used for this run
+    required: true
+  deps-group:
+    description: Dependency groups passed to `uv sync --group`
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
+      with:
+        version: 0.11.6
+        activate-environment: true
+        python-version: ${{ inputs.python-version }}
+    - name: Install dependencies from the ${{ inputs.deps-group }} group(s)
+      run: SDK_DEPS_GROUP="${{ inputs.deps-group }}" make uv-sync-ci
+      shell: bash

.github/workflows/lint.yml

@@ -0,0 +1,23 @@
+name: Python SDK Lint
+on: [push, workflow_dispatch]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHON_VERSION: 3.9
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          deps-group: lint
+      - name: Verify uv.lock is up-to-date
+        run: uv lock --check
+      - name: Verify against basedpyright baseline
+        run: uv run --frozen basedpyright

.github/workflows/pre-release.yml

@@ -5,31 +5,21 @@ env:
   PYTHON_VERSION: 3.9
 
 jobs:
-  publish-sdk-test-pypi:
+  publish-to-test-pypi:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     environment:
       name: splunk-test-pypi
     steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      - name: Set up Python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-      - name: Set up uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
-        with:
-          version: 0.11.6
-          activate-environment: true
-          enable-cache: true
-      - name: Install dependencies
-        run: SDK_DEPS_GROUP="release" make uv-sync-ci
+          deps-group: release
       - name: Build packages for distribution
         run: uv build
       - name: Publish packages to Test PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
         with:
           repository-url: https://test.pypi.org/legacy/

.github/workflows/release.yml

@@ -7,35 +7,28 @@ env:
   PYTHON_VERSION: 3.9
 
 jobs:
-  publish-sdk-pypi:
+  publish-to-pypi:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     environment:
       name: splunk-pypi
     steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      - name: Set up Python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-      - name: Set up uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
-        with:
-          activate-environment: true
-          enable-cache: true
-      - name: Install dependencies
-        run: SDK_DEPS_GROUP="release" make uv-sync-ci
+          deps-group: release
       - name: Build packages for distribution
         run: uv build
       - name: Publish packages to PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+        with:
+          repository-url: https://test.pypi.org/legacy/
       - name: Generate API reference
         run: make -C ./docs html
       - name: Upload docs artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: python-sdk-docs
           path: docs/_build/html

.github/workflows/test.yml

@@ -1,43 +1,32 @@
 name: Python SDK CI
-on:
-  push:
-    branches: [master, develop]
+on: [push, workflow_dispatch]
 
 jobs:
-  test-stage:
-    runs-on: ${{ matrix.os }}
+  test:
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        os: [ubuntu-latest]
         python-version: [3.9]
         splunk-version: [9.4, latest]
         include:
-          - os: ubuntu-latest
-            python-version: 3.13
+          - python-version: 3.13
             splunk-version: latest
+    concurrency:
+      group: ${{ github.workflow }}-py_${{ matrix.python-version }}-splunk_${{ matrix.splunk-version }}-${{ github.event.pull_request.number || github.ref }}
+      cancel-in-progress: true
     steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
-      - name: Set up latest uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
-        with:
-          version: 0.11.6
-          activate-environment: true
-          enable-cache: true
-      - name: Install Python dependencies
-        run: SDK_DEPS_GROUP="test" make uv-sync-ci
+          deps-group: test
       - name: Launch Splunk Docker instance
         run: SPLUNK_VERSION=${{ matrix.splunk-version }} docker compose up -d
-      - name: Set up `.env`
+      - name: Set up .env
         run: cp .env.template .env
-      - name: Restore `pytest` cache
+      - name: Restore pytest cache
         if: ${{ github.ref != 'refs/heads/master' && github.ref != 'refs/heads/develop' }}
-        uses: actions/cache@565629816435f6c0b50676926c9b05c254113c0c
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae
         with:
           path: .pytest_cache
           key: pytest-cache-${{ runner.os }}-py${{ matrix.python-version }}-${{ github.ref_name }}-${{ github.sha }}

.gitignore

@@ -278,4 +278,11 @@ $RECYCLE.BIN/
 # End of https://www.toptal.com/developers/gitignore/api/windows,macos,linux,pycharm+all,python
 
 .vscode/
-docs/_build/
+docs/_build/
+
+!*.conf.spec
+**/metadata/local.meta
+
+*.spl
+*.tgz
+*.tar*

AGENTS.md

@@ -0,0 +1,67 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- Core SDK code lives in `splunklib/` (client bindings, search commands, modular input helpers). Keep new modules close to their domain peers (e.g., searchcommand utilities under `splunklib/searchcommands`).
+- Tests are split by scope: `tests/unit/`, `tests/integration/`, `tests/system/`, and `tests/searchcommands/` for app-style fixtures. Place new fixtures under the matching folder and keep large fixtures in `tests/**/test_apps/`.
+
+## Package Manager
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management and running Python tools. All Python and pytest invocations should be prefixed with `uv run`. Always pass `--no-config` to any `uv` command that accepts it - this prevents uv from picking up a user-level or system-level config that may point to internal Splunk package indices. To install/sync dependencies:
+
+```sh
+make uv-sync
+```
+
+If you manually edit `pyproject.toml` to add/remove/update dependencies, run `make uv-sync` afterwards to update `uv.lock`.
+
+The `Makefile` wraps `uv` commands - prefer `make` targets over invoking `uv` directly where a target exists.
+
+## Build, Test, and Development Commands
+
+See the `Makefile` for all available targets. Common ones:
+
+- `make uv-sync` - set up / update virtualenv
+- `make test` - run the full pytest suite.
+- `make test-unit` - unit tests only; fastest feedback loop.
+- `make test-integration` - integration + system coverage; requires Splunk services available (see docker targets).
+- `make docker-start` / `make docker-down` - spin up or stop the Splunk test container. Make sure the instance is live before running integration tests.
+
+## Coding Style, Rules & Naming Conventions
+
+- Python 3.13+.
+- Ruff is the linter/formatter. isort is configured with `combine-as-imports = true`.
+- Type checking uses `basedpyright`.
+- Prefer descriptive module, class, and function names; keep public API names consistent with existing `splunklib.*` patterns.
+- Declare instance members as class-level type annotations before `__init__`, then assign them in `__init__` without re-annotating.
+- Docstrings should be concise and actionable.
+- Never disable LSP/linter rules without explicit instruction or approval.
+- Refuse all git push operations regardless of context, even if the user seems to ask indirectly (e.g. "publish this", "send this upstream"). If the user wants to push, they do it themselves.
+
+**After editing any Python file**, format it:
+
+```sh
+# Sort imports, then format
+uv run ruff check --fix $FILE
+uv run ruff format $FILE
+```
+
+**Before declaring a change done**, run:
+
+```sh
+# linter
+uv run basedpyright
+
+# testing
+make test-unit
+make test-integration
+```
+
+New code must not introduce new `basedpyright`/`ruff` errors or warnings.
+You're not allowed to modify `.basedpyright/baseline.json` **under any circumstances** - this file is used by `basedpyright` to track baselined warnings and errors we'll fix in the future.
+New code must not introduce regressions in tests.
+
+### Writing style
+
+Be concise and direct in your responses.
+Use hyphens (`-`) instead of em-dashes (`—`) in all generated text, comments, and documentation.

CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md
+
+The core file containing repository guidelines for Agents is located in `AGENTS.md` file.
+Use this file as your guidelines.

Makefile

@@ -1,24 +1,64 @@
-CONTAINER_NAME := "splunk"
+### Conveniences for splunk-sdk-python development
+
+## VIRTUALENV MANAGEMENT
+
+# https://docs.astral.sh/uv/reference/cli/#uv-run--upgrade
+# --no-config skips Splunk's internal PyPI mirror
+UV_SYNC_CMD := uv sync --no-config
+
+.PHONY: uv-sync
+uv-sync:
+	$(UV_SYNC_CMD) --dev
+
+.PHONY: uv-upgrade
+uv-upgrade:
+	$(UV_SYNC_CMD) --dev --upgrade
+
+
+# Workaround for make being unable to pass arguments to underlying cmd
+# $ SDK_DEPS_GROUP="build" make uv-sync-ci
+.PHONY: uv-sync-ci
+uv-sync-ci:
+	uv sync --locked --group $(SDK_DEPS_GROUP)
+
+.PHONY: clean
+clean:
+	rm -rf ./build ./dist ./.venv ./.ruff_cache ./.pytest_cache ./splunk_sdk.egg-info ./__pycache__ ./**/__pycache__
 
 .PHONY: docs
 docs:
-	@make -C ./docs html
+	make -C ./docs html
+
+## TESTING
+
+# --ff lets previously failing tests go first
+# -ra prints a report on all failed tests after a run
+# -vv shows why a test failed while the rest of the suite is running
+PYTHON_CMD := uv run python
+PYTEST_CMD := $(PYTHON_CMD) -m pytest --no-header --ff -ra -vv
 
 .PHONY: test
 test:
-	@python -m pytest ./tests
+	$(PYTEST_CMD) ./tests
 
 .PHONY: test-unit
 test-unit:
-	@python -m pytest ./tests/unit
+	$(PYTEST_CMD) ./tests/unit
 
 .PHONY: test-integration
 test-integration:
-	@python -m pytest ./tests/integration ./tests/system
+	$(PYTEST_CMD) --ff ./tests/integration ./tests/system
+
+## DOCKER
+
+CONTAINER_NAME := splunk
+SPLUNK_HOME := /opt/splunk
 
 .PHONY: docker-up
 docker-up:
-	@docker-compose up -d
+	# For podman (at least on macOS) you might need to add DOCKER_BUILDKIT=0
+	# --build forces Docker to build a new image instead of using an existing one
+	@docker-compose up -d --build
 
 .PHONY: docker-ensure-up
 docker-ensure-up:
@@ -35,14 +75,22 @@ docker-start: docker-up docker-ensure-up
 
 .PHONY: docker-down
 docker-down:
-	@docker-compose stop
+	docker-compose stop
 
 .PHONY: docker-restart
 docker-restart: docker-down docker-start
 
 .PHONY: docker-remove
 docker-remove:
-	@docker-compose rm -f -s
+	docker-compose rm -f -s
 
 .PHONY: docker-refresh
-docker-refresh: docker-remove docker-start
+docker-refresh: docker-remove docker-start
+
+.PHONY: docker-splunk-restart
+docker-splunk-restart:
+	docker exec -it $(CONTAINER_NAME) sudo sh -c '$(SPLUNK_HOME)/bin/splunk restart --run-as-root'
+
+.PHONY: docker-tail-python-log
+docker-tail-python-log:
+	docker exec -it $(CONTAINER_NAME) sudo tail $(SPLUNK_HOME)/var/log/splunk/python.log