[FEATURE] Enhance `StackQL` Constructor for Improved Usability

[jeffreyaven]

Description

The StackQL class requires a refactor to separate read-only parameters and constructor arguments, as well as update and enhance its functionality regarding output formatting and argument handling, particularly when server_mode is set to False.

Detailed Changes

1. Changes to Read-Only Parameters

• Ensure the following parameters are only valid when server_mode=False:
  • version
  • params
  • bin_path
  • sha
  • auth

2. Removal and Replacement of Arguments

• Remove parse_json and replace it with output which accepts the following options:
  • dict (default)
  • pandas
  • csv (only if server_mode=False)

3. Additional Argument Handling

When output='csv', introduce additional parameters:

• delimiter: Defaults to ,.
• hide_headers: Defaults to False.

If server_mode=False, allow additional configuration through the following arguments:

• api_timeout: Default 45, 0 for no timeout
• proxy_host: HTTP proxy host, default None
• proxy_password: HTTP proxy password, default None
• proxy_port: Int, HTTP proxy port, default -1
• proxy_scheme: HTTP proxy scheme, default "http"
• proxy_user: Default None
• max_results: Max results per HTTP request, default -1
• page_limit: Max pages of results per resource, default 20
• max_depth: Max depth for indirect queries, default 5

Proposed Docstring Update

class StackQL:
 """
 A class representing an instance of the StackQL query engine.

 download_dir: The download directory for the StackQL executable.
 :type download_dir: str
 :default: site.getuserbase()

 server_mode: Connect to a StackQL server.
 :type server_mode: bool
 :default: False
 
 server_address: The address of the StackQL server.
 :type server_address: str
 :default: '0.0.0.0'
 
 server_port: The port of the StackQL server.
 :type server_port: int
 :default: 5466
 
 output: Determines the format of the output, options are 'dict', 'pandas', and 'csv'.
 :type output: str
 :default: 'dict'
 :options: ['dict', 'pandas', 'csv']
 
 delimiter: (Only if output='csv') Delimiter character for CSV output.
 :type delimiter: str
 :default: ','

 hide_headers: (Only if output='csv') Whether to hide headers in CSV output.
 :type hide_headers: bool
 :default: False

 api_timeout: (server_mode=False only) API timeout.
 :type api_timeout: int
 :default: 45
 
 proxy_host: (server_mode=False only) HTTP proxy host.
 :type proxy_host: str
 :default: None
 
 proxy_password: (server_mode=False only) HTTP proxy password.
 :type proxy_password: str
 :default: None

 proxy_port: (server_mode=False only) HTTP proxy port.
 :type proxy_port: int
 :default: -1
 
 proxy_scheme: (server_mode=False only) HTTP proxy scheme.
 :type proxy_scheme: str
 :default: 'http'
 
 proxy_user: (server_mode=False only) HTTP proxy user.
 :type proxy_user: str
 :default: None
 
 max_results: (server_mode=False only) Max results per HTTP request.
 :type max_results: int
 :default: -1
 
 page_limit: (server_mode=False only) Max pages of results that will be returned per resource.
 :type page_limit: int
 :default: 20
 
 max_depth: (server_mode=False only) Max depth for indirect queries: views and subqueries.
 :type max_depth: int
 :default: 5
 
 --- Read-Only Attributes ---
 
 platform: The operating system platform.
 :type platform: str
 
 package_version: The version number of the pystackql Python package.
 :type package_version: str
 
 version: (server_mode=False only) The version number of the StackQL executable.
 :type version: str
 
 params: (server_mode=False only) A list of command-line parameters passed to the StackQL executable.
 :type params: list
 
 bin_path: (server_mode=False only) The full path of the StackQL executable.
 :type bin_path: str
 
 sha: (server_mode=False only) The commit (short) sha for the installed `stackql` binary build.
 :type sha: str
 
 auth: (server_mode=False only) StackQL provider authentication object supplied using the class constructor.
 :type auth: dict
 """

[jeffreyaven]

implemented