[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
    """