[CIVIS-8695] ENH SQL I/O functions accept SQL parameters and arguments (#493)

* ENH civis.io* exposes params and args for client.scripts.post_sql

* REF switch to sql_params_arguments

* DOC update docs

* MAINT update changelog

* MAINT update changelog

* MAINT update changelog

* FIX response eq and repr; resource type hints for 'List'

* VER bump to v2.3.0 and update docs

* FIX real imports for static type hints

* MAINT update changelog

* MAINT update changelog

Author: jacksonlee-civis

CHANGELOG.md

@@ -6,8 +6,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+## 2.3.0 - 2024-06-14
+
 ### Added
 - Added a script for checking if the Civis API spec is up-to-date. (#489)
+- Added a new keyword argument `sql_params_arguments` to the `civis.io.*` functions that
+  accept a SQL query, so that the user can run a parameterized SQL script. (#493)
 
 ### Changed
 - Refactored the `civis.parallel` module and related unit tests due to major changes
@@ -17,19 +28,21 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Bumped the minimum required version of `joblib` to v1.3.0,
   which is the version where `joblib.parallel_config` was introduced and
   `joblib.parallel_backend` was deprecated. (#488)
-- Improved the startup time of `import civis` with a 5x speed boost. (#490)
+- Improved the startup time of `import civis` with a 5x speed boost. (#490, #493)
 - The downloaded API spec due to the `civis.APIClient` instantiation is now
   a time-to-live cache in memory (15 minutes for interactive Python, or 24 hours in scripts). (#491)
 - Polling at `PollableResult` (and consequently its subclasses as well: `CivisFuture`,
   `ContainerFuture`, and `ModelFuture`) now defaults to geometrically increased polling
   intervals. Short-running jobs' `future.result()` can now return faster, while
   longer-running jobs have a capped polling interval of 15 seconds. (#492)
+- Comparing a `Response` object with a non-`Response` object returns `False` now
+  (this previously raised a `TypeError`). (#493)
 
-### Deprecated
-### Removed
 ### Fixed
 - Fixed `civis.parallel.make_backend_template_factory` so that
   keyword arguments are now accepted and passed to `client.scripts.post_custom`. (#488)
+- For `Response` objects, their "repr" form shows the class name "Response" for both
+  top-level and nested response objects. (#493)
 
 ### Security
 - Bumped the minimum required version of `requests` to the latest v2.32.3, 

docs/source/cli.rst

@@ -20,10 +20,6 @@ data types (e.g., arrays, objects/dictionaries) as input. However,
 functionality is available for getting information about scripts, logs, etc.,
 as well as executing already created scripts.
 
-There are a few extra, CLI-only commands that wrap the Files API
-endpoints to make uploading and downloading files easier:
-``civis files upload $PATH`` and ``civis files download $FILEID $PATH``.
-
 The default output format is YAML, but the ``--json-output`` allows you to
 get output in JSON.
 
@@ -33,6 +29,16 @@ like ``civis scripts list --help``.
 The logging level of the CLI can be configured by setting the ``CIVIS_LOG_LEVEL``
 environment variable, e.g., ``CIVIS_LOG_LEVEL=DEBUG civis users list-me``.
 
+Files
+-----
+
+There are a few extra, CLI-only commands that wrap the Files API
+endpoints to make uploading and downloading files easier:
+
+- ``civis files upload $PATH``
+
+- ``civis files download $FILEID $PATH``
+
 Job Logs
 --------
 

docs/source/index.rst

@@ -36,8 +36,8 @@ For a more detailed walkthrough, see the :ref:`user_guide`.
   :end-before: end-include-marker-retires-section
 
 
-Client API Reference
---------------------
+Table of Contents
+-----------------
 
 .. toctree::
    :maxdepth: 1
@@ -55,5 +55,4 @@ Indices and tables
 ------------------
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`

docs/source/responses.rst

@@ -14,11 +14,11 @@ A Civis API call from ``client.<endpoint>.<method>`` returns a :class:`civis.res
             name='some script name',
             created_at='2018-06-11T20:43:07.000Z',
             updated_at='2018-06-11T20:43:19.000Z',
-            author=(id=67890,
-                    name='Platform User Name',
-                    username='platformusername',
-                    initials='PUN',
-                    online=False),
+            author=Response(id=67890,
+                            name='Platform User Name',
+                            username='platformusername',
+                            initials='PUN',
+                            online=False),
             ...
 
 To retrieve information from a :class:`civis.response.Response` object,

docs/source/user_guide.rst

@@ -123,15 +123,15 @@ your user information:
 .. code:: python
 
    >>> client.users.list_me()
-   {'email': '[email protected]',
-    'feature_flags': {'left_nav_basic': True,
-                      'results': True,
-                      'scripts_notify': True,
-                      'table_person_matching': True},
-    'id': 1,
-    'initials': 'UN',
-    'name': 'User Name',
-    'username': 'uname'}
+   Response(email='[email protected]',
+            feature_flags=Response(left_nav_basic=True,
+                                   results=True,
+                                   scripts_notify=True,
+                                   table_person_matching=True),
+            id=1,
+            initials='UN',
+            name='User Name',
+            username='uname')
 
 For a complete list of the API endpoints and their methods,
 check out :ref:`api_resources`.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "civis"
-version = "2.2.0"
+version = "2.3.0"
 description = "Civis API Python Client"
 readme = "README.rst"
 requires-python = ">= 3.9"
@@ -48,7 +48,7 @@ dev-core = [
     "flake8 == 7.0.0",
     "pandas == 2.2.2",
     "pip-audit",  # Install the latest version.
-    "pytest == 8.2.1",
+    "pytest == 8.2.2",
     "pytest-cov == 5.0.0",
     "twine == 5.1.0",
 ]

src/civis/__init__.py

@@ -1,6 +1,7 @@
 import importlib
 import sys
 from importlib.metadata import version
+from typing import TYPE_CHECKING
 
 from civis.client import APIClient
 from civis.loggers import civis_logger
@@ -19,18 +20,22 @@ def _lazy_import(name):
     return module
 
 
-futures = _lazy_import("civis.futures")
-io = _lazy_import("civis.io")
-ml = _lazy_import("civis.ml")
-parallel = _lazy_import("civis.parallel")
-utils = _lazy_import("civis.utils")
+if TYPE_CHECKING:
+    from civis import futures, io, ml, parallel, utils
+else:
+    futures = _lazy_import("civis.futures")
+    io = _lazy_import("civis.io")
+    ml = _lazy_import("civis.ml")
+    parallel = _lazy_import("civis.parallel")
+    utils = _lazy_import("civis.utils")
 
 __version__ = version("civis")
 __all__ = [
     "__version__",
     "APIClient",
     "find",
     "find_one",
+    "futures",
     "io",
     "civis_logger",
     "ml",