[CIVIS-11467] civis-python: add support to civis.utils.run_template for passing remote_host_id and credential_id arguments

[gkcivis]

The function run_template in _jobs.py has been updated:

• It now accepts **kwargs to be passed to post_custom.
• Added a new argument return_as (str) with options: "files" (default for <v3.0.0), "JSONValue", and "future".
• The legacy JSONValue argument is still supported for backward compatibility.
• Added a deprecation warning for the JSONValue parameter.
• To use run_template for SQL template scripts (BigQuery), pass remote_host_id and credential_id as kwargs, and set return_as="future" to get the CivisFuture object.

---

• (For Civis employees only) Reference to a relevant ticket in the pull request title
• Changelog entry added to CHANGELOG.md at the repo's root level
• Description of change in the pull request description
• If applicable, unit tests have been added and/or updated
• The CircleCI builds have all passed

[Copilot]

Pull Request Overview

This PR adds support for passing additional arguments to civis.utils.run_template and introduces a new return_as parameter to control the return type. The legacy JSONValue boolean parameter is deprecated in favor of the more flexible return_as string parameter, which supports three options: "files" (default), "JSONValue", and "future". This enables using run_template with SQL template scripts that require remote_host_id and credential_id arguments.

Key Changes:

• Added **kwargs parameter to run_template to pass additional arguments to post_custom
• Introduced return_as parameter with three options: "files", "JSONValue", and "future"
• Deprecated the JSONValue boolean parameter with backward compatibility support
• Added comprehensive test coverage for the new functionality

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/civis/utils/_jobs.py	Added return_as parameter, **kwargs support, and deprecation handling for JSONValue
tests/test_jobs.py	Added tests for return_as parameter options, kwargs passing, and deprecation warnings
CHANGELOG.md	Documented the changes to run_template

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jacksonlee-civis]

This is looking great! Once the way we handle the deprecated JSONValue kwarg and the validation of return_as is updated, this should be good to go.

[jacksonlee-civis]

Trying to clarify a bit more since we're making a potentially confusing change (deprecating an argument named JSONValue, while we expect the string "JSONValue" to be one of the allowed values for the new arg return_as),

Suggested change

	"As of civis-python v2.8.0, civis.utils.run_template can return three "
	"types of values, so 'JSONValue' is deprecated "
	"As of civis-python v2.8.0, the boolean argument 'JSONValue' of "
	civis.utils.run_template is deprecated "

[jacksonlee-civis]

LGTM!