[TEST] Bartek's Lab

.env → .env.test

@@ -1,16 +1,14 @@
+# Your version of Splunk (default: latest)
+version=latest
+
+# Access scheme (default: https)
+scheme=https
 # Splunk host (default: localhost)
 host=localhost
 # Splunk admin port (default: 8089)
 port=8089
+
 # Splunk username
 username=admin
 # Splunk password
 password=changed!
-# Access scheme (default: https)
-scheme=https
-# Your version of Splunk (default: 6.2)
-version=9.0
-# Bearer token for authentication
-#splunkToken="<Bearer-token>"
-# Session key for authentication
-#token="<Session-Key>"

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,17 +1,17 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
 ---
 
 **Describe the bug**
 A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -24,14 +24,16 @@ A clear and concise description of what you expected to happen.
 If applicable, add logs or screenshots to help explain your problem.
 
 **Splunk (please complete the following information):**
+
 - Version: [e.g. 8.0.5]
 - OS: [e.g. Ubuntu 20.04.1]
 - Deployment: [e.g. single-instance]
 
 **SDK (please complete the following information):**
- - Version: [e.g. 1.6.14]
- - Language Runtime Version: [e.g. Python 3.7]
- - OS: [e.g. MacOS 10.15.7]
+
+- Version: [e.g. 1.6.14]
+- Language Runtime Version: [e.g. Python 3.7]
+- OS: [e.g. MacOS 10.15.7]
 
 **Additional context**
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/custom.md

@@ -1,10 +1,7 @@
 ---
 name: Custom issue template
 about: Describe this issue template's purpose here.
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
 ---
-
-

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,10 +1,9 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
 ---
 
 **Is your feature request related to a problem? Please describe.**

.github/PULL_REQUEST_TEMPLATE/pr_template.md

@@ -1,15 +1,14 @@
 ---
 name: Pull Request Template
 about: Create a Pull Request to contribute to the SDK
-title: ''
-labels: ''
-assignees: ''
-
+title: ""
+labels: ""
+assignees: ""
 ---
 
 ## Description of PR
 
-Provide the **context and motivation** for this PR. 
+Provide the **context and motivation** for this PR.
 Briefly explain the **type of changes** (bug fix, feature request, doc update, etc.) made in this PR. Provide reference to issue # fixed, if applicable.
 
 Describe the approach to the solution, the changes made, and any resulting change in behavior or impact to the user.

.github/copilot-instructions.md

@@ -0,0 +1,112 @@
+# Splunk SDK Python - AI Assistant Guide
+
+This guide helps AI coding assistants understand the key patterns and practices of the Splunk SDK for Python codebase.
+
+## Architecture Overview
+
+The SDK is organized into several key modules:
+
+- `splunklib.client`: Main interface for interacting with Splunk's REST API
+- `splunklib.binding`: Low-level HTTP and authentication handling
+- `splunklib.data`: XML/Atom feed parsing utilities
+- `splunklib.modularinput`: Framework for creating Splunk modular inputs
+- `splunklib.searchcommands`: Framework for custom search commands
+
+### Core Patterns
+
+1. Service Connection:
+
+```python
+import splunklib.client as client
+service = client.connect(
+    host='localhost',
+    port=8089,
+    username='admin',
+    password='changeme'
+    # OR splunkToken=<bearer_token>
+    # OR token=<session_key>
+)
+```
+
+2. Resource Collections Pattern:
+
+- All Splunk resources (apps, jobs, searches etc.) are accessed via collections
+- Collections return Entity objects with attribute access
+- Example:
+
+```python
+apps = service.apps
+my_app = apps.create('my_app')
+print(my_app['author'])  # Or: my_app.author
+```
+
+3. XML Data Handling:
+
+- Use `splunklib.data.load()` for parsing Splunk's XML responses
+- Include proper XML namespace handling as shown in `data.py`
+
+## Development Workflows
+
+1. Testing:
+
+```bash
+# Run all tests with Docker
+make up SPLUNK_VERSION=9.2
+make wait_up
+make test
+make down
+
+# Run specific test
+make test_specific TEST=tests/test_binding.py
+```
+
+2. Environment Setup:
+
+- Required: Python 3.7, 3.9, or 3.13
+- Create `.env` file for test credentials (see README template)
+- Set `PYTHONPATH` to include SDK root
+
+## Project-Specific Conventions
+
+1. Search Command Development:
+
+- Use `self.add_field(record, fieldname, value)` to modify records
+- Never modify record dictionaries directly
+- Example:
+
+```python
+class CustomStreamingCommand(StreamingCommand):
+    def stream(self, records):
+        for record in records:
+            self.add_field(record, "new_field", "value")
+            yield record
+```
+
+2. Modular Input Development:
+
+- Access metadata via InputDefinition in stream_events()
+- Use `gen_record()` for generating events in custom commands
+
+## Key Integration Points
+
+1. Authentication Methods:
+
+- Username/password
+- Bearer token
+- Session key
+- See connection examples in README
+
+2. Test Dependencies:
+
+- Requires [SDK App Collection](https://github.com/splunk/sdk-app-collection)
+- Clean Splunk instance recommended (disable \*NIX/Windows apps)
+- Never test against production instances
+
+## Reference Files
+
+- `splunklib/client.py`: Core service and entity implementations
+- `splunklib/data.py`: XML parsing patterns
+- `tests/README.md`: Testing configuration and practices
+- `.env.template`: Environment variable template
+
+For more details, consult the [Developer Portal Reference](https://dev.splunk.com/enterprise/docs/devtools/python/sdk-python/).

.github/workflows/release.yml

@@ -1,43 +1,45 @@
-name: Release
+name: Publish release to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        type: boolean
+        required: true
+        default: true
 
 jobs:
-  publish:
-    name: Deploy Release to PyPI
-    runs-on: ubuntu-latest
+  release:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: [3.9]
     steps:
-      - name: Checkout source
-        uses: actions/checkout@v3
-      - name: Set up Python
-        uses: actions/setup-python@v4
+      - name: Checkout repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
-          python-version: 3.7
+          python-version: ${{ matrix.python-version }}
       - name: Install dependencies
-        run: pip install twine
+        run: pip install . --group build
       - name: Build package
-        run: python setup.py sdist
+        run: python -m build
       - name: Publish package to PyPI
-        uses: pypa/[email protected]
+        if: ${{ inputs.dry-run == 'false' }}
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc
         with:
           user: __token__
-          password: ${{ secrets.pypi_password }}
-      - name: Install tox
-        run: pip install tox
-      - name: Generate API docs
+          password: ${{ secrets.PYPI_PASSWORD }}
+      - name: Generate API reference docs
         run: |
           rm -rf ./docs/_build
-          tox -e docs
-      - name : Docs Upload
-        uses: actions/upload-artifact@v3
+          python -m tox -e docs
+      - name: Upload API reference docs
+        if: ${{ inputs.dry-run == 'false' }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
         with:
           name: python_sdk_docs
           path: docs/_build/html
-      # Test upload
-      # - name: Publish package to TestPyPI
-      #   uses: pypa/gh-action-pypi-publish@master
-      #   with:
-      #     user: __token__
-      #     password: ${{ secrets.test_pypi_password }}
-      #     repository_url: https://test.pypi.org/legacy/

.github/workflows/test.yml

@@ -1,51 +1,50 @@
 name: Python CI
 
-on:
-  [ push, workflow_dispatch ]
+on: [push, workflow_dispatch]
 
 jobs:
-  build:
-
+  test:
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
-        os:
-          - ubuntu-latest
-        python: [ 3.9, 3.13 ]
-        splunk-version:
-          - "8.1"
-          - "8.2"
-          - "latest"
+        os: [ubuntu-latest]
+        python-version: [3.9, 3.13]
+        splunk-version: [9.3, 9.4, latest]
         include:
+          # Ubuntu 22.04 is the last version we can get pre-built Python 3.7 binaries for
           - os: ubuntu-22.04
-            python: 3.7
-            splunk-version: "8.1"
-          - os: ubuntu-22.04
-            python: 3.7
-            splunk-version: "8.2"
+            python-version: 3.7
+            splunk-version: 9.3
           - os: ubuntu-22.04
-            python: 3.7
-            splunk-version: "latest"
-
-      fail-fast: false
-
+            python-version: 3.7
+            splunk-version: 9.4
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-
-      - name: Run docker compose
-        run: SPLUNK_VERSION=${{matrix.splunk-version}} docker compose up -d
-
-      - name: Setup Python
-        uses: actions/setup-python@v4
+      - name: Checkout repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - name: Set up environment variables
+        run: cp ./.env.test ./.env
+      - name: Launch Splunk ${{ matrix.splunk-version }}
+        run: SPLUNK_VERSION=${{ matrix.splunk-version }} docker compose up -d
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
-          python-version: ${{ matrix.python }}
-
-      - name: Install tox
-        run: pip install tox
-
-      - name: Test Execution
-        run: tox -e py
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: python --version && python -m pip --version && python -m pip install tox
+      - name: Run Docker health check
+        # Probably solves nothing, worth trying regardless
+        run: |
+          timeout 30s make wait_up
+          if [ $? -eq 124 ]; then
+            echo "Splunk failed to start within 30 seconds."
+            docker compose logs
+            exit 1
+          fi
+      - name: Run test suite
+        run: python -m tox -e py
+      - name: Print docker logs for optional inspection
+        run: docker compose logs
   fossa-scan:
     uses: splunk/oss-scanning-public/.github/workflows/oss-scan.yml@main
-    secrets: inherit
+    secrets: inherit