diff --git a/docs/requirements.txt b/docs/requirements.txt index 92dc06a59a7..716eb2f6c1a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,9 @@ -pydantic -httpx +pydantic[dotenv] +httpx[http2] aiorwlock -async_property +async-property readerwriterlock -sqlparse \ No newline at end of file +sqlparse +appdirs +appdirs-stubs +cryptography \ No newline at end of file diff --git a/docsrc/Connecting_and_queries.rst b/docsrc/Connecting_and_queries.rst new file mode 100644 index 00000000000..b465352fcb2 --- /dev/null +++ b/docsrc/Connecting_and_queries.rst @@ -0,0 +1,277 @@ + +############################### +Connecting and running queries +############################### + +This topic provides a walkthrough and examples for how to use the Firebolt Python SDK to connect to Firebolt resources to run commands and query data. + + +Setting up a connection +========================= + +To connect to a Firebolt database to run queries or command, you must provide your account credentials through a connection request. + +To get started, follow the steps below: + +**1. Import modules** + + The Firebolt Python SDK requires you to import the following modules before making any command or query requests to your Firebolt database. + +.. _required_connection_imports: + + :: + + from firebolt.db import connect + from firebolt.client import DEFAULT_API_URL + + +.. _connecting_with_credentials_example: + +**2. Connect to your database and engine** + + + Your account information can be provided as parameters in a ``connection()`` function. + + A connection requires the following parameters: + + +------------------------------------+-------------------------------------------------------------------+ + | ``username`` | The email address associated with your Firebolt user. | + +------------------------------------+-------------------------------------------------------------------+ + | ``password`` | The password used for connecting to Firebolt. | + +------------------------------------+-------------------------------------------------------------------+ + | ``database`` | The name of the database you would like to connect to. | + +------------------------------------+-------------------------------------------------------------------+ + | ``engine_name`` or ``engine_url`` | The name or URL of the engine to use for SQL queries. | + | | | + | | If the engine is not specified, your default engine is used. | + +------------------------------------+-------------------------------------------------------------------+ + + This information can be provided in multiple ways. + + * **Set credentials manually** + + You can manually include your account information in a connection object in your code for any queries you want to request. + + Replace the values in the example code below with your Firebolt account credentials as appropriate. + + :: + + username = "your_username" + password = "your_password" + engine_name = "your_engine" + database_name = "your_database" + + connection = connect( + engine_name=engine_name, + database=database_name, + username=username, + password=password, + ) + + cursor = connection.cursor() + + + * **Use an .env file** + + Consolidating all of your Firebolt credentials into a ``.env`` file can help protect sensitive information from exposure. Create an ``.env`` file with the following key-value pairs, and replace the values with your information. + + :: + + FIREBOLT_USER="your_username" + FIREBOLT_PASSWORD="your_password" + FIREBOLT_ENGINE="your_engine" + FIREBOLT_DB="your_database" + + Be sure to place this ``.env`` file into your root directory. + + Your connection script can load these environmental variables from the ``.env`` file by using the `python-dotenv `_ package. Note that the example below imports the ``os`` and ``dotenv`` modules in order to load the environmental variables. + + :: + + import os + from dotenv import load_dotenv + + load_dotenv() + + connection = connect( + username=os.getenv('FIREBOLT_USER'), + password=os.getenv('FIREBOLT_PASSWORD'), + engine_name=os.getenv('FIREBOLT_ENGINE'), + database=os.getenv('FIREBOLT_DB') + ) + + cursor = connection.cursor() + + +**3. Execute commands using the cursor** + + The ``cursor`` object can be used to send queries and commands to your Firebolt database and engine. See below for examples of functions using the ``cursor`` object. + +Command and query examples +============================ + +This section includes Python examples of various SQL commands and queries. + + +Inserting and selecting data +----------------------------- + +.. _basic_execute_example: + +The example below uses ``cursor`` to create a new table called ``test_table``, insert rows into it, and then select the table's contents. + +The engine attached to your specified database must be started before executing any queries. For help, see :ref:`starting an engine`. + +:: + + cursor.execute( + '''CREATE FACT TABLE IF NOT EXISTS test_table ( + id INT, + name TEXT + ) + PRIMARY INDEX id;''' + ) + + cursor.execute( + '''INSERT INTO test_table VALUES + (1, 'hello'), + (2, 'world'), + (3, '!');''' + ) + + cursor.execute( + '''SELECT * FROM test_table;''' + ) + + cursor.close() + +.. note:: + + For reference documentation on ``cursor`` functions, see :ref:`Db.cursor` + + +Fetching query results +----------------------- + +After running a query, you can fetch the results using a ``cursor`` object. The examples below use the data queried from ``test_table`` created in the :ref:`Inserting and selecting data`. + +.. _fetch_example: + +:: + + print(cursor.fetchone()) + +**Returns**: ``[2, 'world']`` + +:: + + print(cursor.fetchmany(2)) + +**Returns**: ``[[1, 'hello'], [3, '!']]`` + +:: + + print(cursor.fetchall()) + +**Returns**: ``[[2, 'world'], [1, 'hello'], [3, '!']]`` + + +Executing parameterized queries +--------------------------------- + +.. _parameterized_query_execute_example: + +Parameterized queries (also known as “prepared statements”) format a SQL query with placeholders and then pass values into those placeholders when the query is run. This protects against SQL injection attacks and also helps manage dynamic queries that are likely to change, such as filter UIs or access control. + +To run a parameterized query, use the ``execute()`` cursor method. Add placeholders to your statement using question marks ``?``, and in the second argument pass a tuple of parameters equal in length to the number of ``?`` in the statement. + + +:: + + cursor.execute( + '''CREATE FACT TABLE IF NOT EXISTS test_table2 ( + id INT, + name TEXT, + date_value DATE + ) + PRIMARY INDEX id;''' + ) + + +:: + + cursor.execute( + "INSERT INTO test_table2 VALUES (?, ?, ?)", + (1, "apple", "2018-01-01"), + ) + + cursor.close() + +.. _parameterized_query_executemany_example: + +If you need to run the same statement multiple times with different parameter inputs, you can use the ``executemany()`` cursor method. This allows multiple tuples to be passed as values in the second argument. + +:: + + cursor.executemany( + "INSERT INTO test_table2 VALUES (?, ?, ?)", + ( + (2, "banana", "2019-01-01"), + (3, "carrot", "2020-01-01"), + (4, "donut", "2021-01-01") + ) + ) + + cursor.close() + + + +Executing multiple-statement queries +-------------------------------------- + +Multiple-statement queries allow you to run a series of SQL statements sequentially with just one method call. Statements are separated using a semicolon ``;``, similar to making SQL statements in the Firebolt UI. + +:: + + cursor.execute( + """ + SELECT * FROM test_table WHERE id < 4; + SELECT * FROM test_table WHERE id > 2; + """ + ) + print("First query: ", cursor.fetchall()) + assert cursor.nextset() + print("Second query: ", cursor.fetchall()) + assert cursor.nextset() is None + + cursor.close() + +**Returns**: + +:: + + First query: [[2, 'banana', datetime.date(2019, 1, 1)], [3, 'carrot', datetime.date(2020, 1, 1)], [1, 'apple', datetime.date(2018, 1, 1)]] + Second query: [[3, 'carrot', datetime.date(2020, 1, 1)], [4, 'donut', datetime.date(2021, 1, 1)]] + +.. note:: + + Multiple statement queries are not able to use placeholder values for parameterized queries. + + +Using DATE and DATETIME values +--------------------------------- + +DATE, DATETIME and TIMESTAMP values used in SQL insertion statements must be provided in a specific format; otherwise they could be read incorrectly. + +* DATE values should be formatted as **YYYY-MM-DD** + +* DATETIME and TIMESTAMP values should be formatted as **YYYY-MM-DD HH:MM:SS.SSSSSS** + +The `datetime `_ module from the Python standard library contains various classes and methods to format DATE, TIMESTAMP and DATETIME data types. + +You can import this module as follows: + +:: + + from datetime import datetime + diff --git a/docsrc/Managing_resources.rst b/docsrc/Managing_resources.rst new file mode 100644 index 00000000000..4e2e9051b8f --- /dev/null +++ b/docsrc/Managing_resources.rst @@ -0,0 +1,326 @@ +##################################### +Managing engines and databases +##################################### + +This topic provides a walkthrough and examples for using the Firebolt Python SDK to create and modify Firebolt databases and engines. + + +Setting up a ResourceManager object +==================================== + +You can perform various functions on Firebolt databases and engines by calling a ``ResourceManager`` object, which must be configured with its own user credentials through the imported ``Settings`` class. + +To get started, follow the steps below: + +**1. Import modules** + + To initialize a ``ResourceManager`` object, import the modules shown below. + +.. _required_resourcemanager_imports: + + :: + + from firebolt.service.manager import ResourceManager + from firebolt.common import Settings + + +**2. Initialize a Settings object** + + A Settings object contains the user credentials and other information needed to manage Firebolt databases and engines. + + The Settings object uses the following parameters: + + +---------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | ``user`` | The email address associated with your Firebolt user profile. | + +---------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | ``password`` | The password used for connecting to Firebolt. | + +---------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | ``server`` | The API hostname for logging in. Defaults to ``api.app.firebolt.io`` if not included. | + +---------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | ``default_region`` | The default region for creating new databases and engines. | + | | | + | | For more information, see `Available AWS Regions `_. | + +---------------------+-----------------------------------------------------------------------------------------------------------------------------+ + + + + A ``Settings`` object can be configured with parameters by multiple methods. + + * Add the parameters manually in your command script: + + :: + + settings = Settings( + user="your_username", + password="your_password", + server="api.app.firebolt.io" + default_region="your_region" + ) + + * Use a ``.env`` file located in your root directory containing the following parameters: + + :: + + FIREBOLT_USER="your_username", + FIREBOLT_PASSWORD="your_password", + FIREBOLT_SERVER="api.app.firebolt.io" + FIREBOLT_DEFAULT_REGION="your_region" + + In your application file, the ``Settings`` object can read the values from the ``.env`` file if it is set to ``None`` instead of having values, as shown below: + + :: + + settings = None + + +**3. Initialize a ResourceManager object** + + + After the ``Settings`` are configured, create a ``ResourceManager`` object, which is given the variable name ``rm`` in the example below. + + :: + + rm = ResourceManager(settings=settings) + + .. note:: + + Subsequent examples on this page use the ``rm`` object for database and engine functions. + + +Database function examples +==================================== + +This section includes Python examples of various common functions for creating and managing Firebolt resources. + +Listing out databases +------------------------ + +List out the names of all databases under your account by using the ``get_many`` function. + + + + **List out all databases and their metadata** + + This produces an inventory of all databases and their metadata from your account. The Python `devtools `_ module used in the example below helps format the metadata to be more readable. + + :: + + from devtools import debug + + debug(rm.databases.get_many()) + + + **Listing out databases by name** + + This function call lists out the names of your databases, but it can be modified to list out other attributes. This is helpful for tracking down a particular database in your account. + + :: + + all_dbs = rm.databases.get_many() + all_db_names = [d.name for d in all_dbs] + for db in db_names: + print(db) + + .. note:: + + For a list of all database attributes, see :ref:`model.database`. + + +Creating a new database +------------------------- + +Launch a new database and use it to create a ``database`` object. + +A newly created database uses the default region from your Settings unless you specify a different region as a parameter. + + :: + + database = rm.databases.create(name="database_name", region="us-east-1") + + + .. note:: + + For a list of all database parameters, see :ref:`Service.database` + + +Locating a database +--------------------- + +Find a specific Firebolt database by using its name or ID. These functions are useful as a starting point to create a ``database`` object that can be called in other database functions. + +In the examples below, replace the values for ``database_name`` and ``database_id`` with your database name or ID. + + + + **Locating by name** + + :: + + database = rm.databases.get_by_name(name="database_name") + + **Locating by ID** + + :: + + database = rm.databases.get_by_id(id="database_id") + + +Getting database status +------------------------- + +Use the Python `devtools `_ module to format metadata from a ``database`` object. This is a helpful command to run after a database operation to check if its execution was successful. + + :: + + from devtools import debug + debug(database) + + +Dropping a database +----------------------- + +Delete a database by calling the ``delete`` function. The database is deleted along with all of its tables. + + :: + + database.delete() + + +Engine function examples +==================================== + +This section includes Python examples of various common functions for creating and managing Firebolt engines. + + + +Creating an engine +-------------------- + +Launch a new Firebolt engine and create an ``engine`` object. The created engine uses the default region included in your Settings unless you specify a different region as a parameter. + + :: + + engine = rm.engines.create(name="engine_name") + + +.. note:: + + For a list of all engine parameters, see :ref:`Service.engine` + + + +Listing out engines +--------------------- + +List out the names of all engines under your account by using the ``get_many`` function. + + **List out all engines and metadata** + + This produces an inventory of all engines and their metadata from your account. The Python `devtools `_ module used in the example below helps format the metadata to be more readable. + + :: + + from devtools import debug + + debug(rm.engines.get_many()) + + **List out engines by name** + + This function call lists out the names of your engines, but it can be modified to list out other attributes. This is helpful for tracking down a particular engine in your account. + + :: + + all_engines = rm.engines.get_many() + all_engine_names = [e.name for e in all_engines] + for name in all_engine_names: + print(name) + + + .. note:: + + For a list of all engine attributes, see :ref:`Model.engine` + +Locating an engine +-------------------- + +Find a specific Firebolt engine by using its name or ID. These functions are useful as a starting point to create an ``engine`` object that can be called in other engine functions. + +In the examples below, replace the values for ``engine_name`` and ``engine_id`` with your engine name or ID. + + **Locating by name** + + :: + + engine = rm.engines.get_by_name(name="engine_name") + + **Locating by ID** + + :: + + engine = rm.engines.get_by_id(name="engine_id") + + +Attaching an engine +--------------------- + +Attach an engine to a database. An engine must be attached to a database and started before it can run SQL commands or queries. + + :: + + engine = rm.engines.get_by_name(name="engine_name") + engine.attach_to_database( + database=rm.databases.get_by_name(name="database_name")) + + + +Dropping an engine +-------------------- + +Delete an engine by calling the ``delete`` function. The engine is removed from its attached database and deleted. + + :: + + engine.delete() + + +Starting an engine +------------------- + +Start an engine by calling the ``start`` function on an ``engine`` object. An engine must be attached to a database and started before it can run SQL commands or queries. + + :: + + engine.start() + + + +Stopping an engine +-------------------- + +Stop an engine by calling the ``stop`` function. When stopped, an engine is not available to run queries and does not accrue additional usage time on your account. + + :: + + engine.stop() + +Updating an engine +--------------------- + +Update an engine to change its specifications, returning an updated version of the engine. The engine must be stopped in order to be updated. + +For a list of engine parameters that can be updated, see :meth:`~firebolt.model.engine.Engine.update` + + :: + + engine.update(description = "This is a new description.") + +Getting engine status +---------------------- + +Use the Python `devtools `_ module to format metadata from an ``engine`` object. This is a helpful command to run after an engine operation to check if its execution was successful. + + :: + + from devtools import debug + debug(engine) + diff --git a/docsrc/conf.py b/docsrc/conf.py index ea4f0c8f283..244adc12792 100644 --- a/docsrc/conf.py +++ b/docsrc/conf.py @@ -37,7 +37,11 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.autosectionlabel", +] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docsrc/firebolt.async_db.rst b/docsrc/firebolt.async_db.rst index 1b3e922fbbc..dd51d37a070 100644 --- a/docsrc/firebolt.async_db.rst +++ b/docsrc/firebolt.async_db.rst @@ -1,10 +1,10 @@ ========================== -firebolt.async\_db package +Async\_db ========================== +The async_db package enables connecting to a Firebolt database for asynchronous queries. - -firebolt.async\_db.connection module +Async\_db.connection ------------------------------------ .. automodule:: firebolt.async_db.connection @@ -13,7 +13,7 @@ firebolt.async\_db.connection module :undoc-members: :show-inheritance: -firebolt.async\_db.cursor module +Async\_db.cursor -------------------------------- .. automodule:: firebolt.async_db.cursor @@ -22,10 +22,11 @@ firebolt.async\_db.cursor module :undoc-members: :show-inheritance: -Module contents ---------------- +Async\_db.util +------------------------------ -.. automodule:: firebolt.async_db +.. automodule:: firebolt.async_db.util :members: :undoc-members: :show-inheritance: + diff --git a/docsrc/firebolt.client.rst b/docsrc/firebolt.client.rst index ef97c946df3..313f91cc8f4 100644 --- a/docsrc/firebolt.client.rst +++ b/docsrc/firebolt.client.rst @@ -1,9 +1,10 @@ ======================= -firebolt.client package +Client ======================= +The client package contains functionality for user authentication and logging requests. -firebolt.client.auth module +Client.auth --------------------------- .. automodule:: firebolt.client.auth @@ -11,7 +12,7 @@ firebolt.client.auth module :undoc-members: :show-inheritance: -firebolt.client.client module +Client.client ----------------------------- .. automodule:: firebolt.client.client @@ -20,12 +21,18 @@ firebolt.client.client module :undoc-members: :show-inheritance: -.. automodule:: firebolt.client.constants +.. + Client.constants + -------------------------------- + .. automodule:: firebolt.client.constants :members: :undoc-members: :show-inheritance: + (no members) -firebolt.client.resource\_manager\_hooks module + + +Client.resource\_manager\_hooks ----------------------------------------------- .. automodule:: firebolt.client.resource_manager_hooks diff --git a/docsrc/firebolt.common.rst b/docsrc/firebolt.common.rst index 92a982c18e0..e3ecffcc6ed 100644 --- a/docsrc/firebolt.common.rst +++ b/docsrc/firebolt.common.rst @@ -1,9 +1,10 @@ ======================= -firebolt.common package +Common ======================= +The common package contains settings parameters and error exceptions. -firebolt.common.exception module +Common.exception -------------------------------- .. automodule:: firebolt.common.exception @@ -11,7 +12,7 @@ firebolt.common.exception module :undoc-members: :show-inheritance: -firebolt.common.settings module +Common.settings ------------------------------- .. automodule:: firebolt.common.settings @@ -19,11 +20,24 @@ firebolt.common.settings module :undoc-members: :show-inheritance: +Common.urls +--------------------------- + .. automodule:: firebolt.common.urls :members: :undoc-members: :show-inheritance: +Common.token\_storage +------------------------------------- + +.. automodule:: firebolt.common.token_storage + :members: + :undoc-members: + :show-inheritance: + +Common.util +--------------------------- .. automodule:: firebolt.common.util :exclude-members: async_to_sync, cached_property, fix_url_schema, mixin_for, prune_dict diff --git a/docsrc/firebolt.db.rst b/docsrc/firebolt.db.rst index ae2a231417e..cd87a4c8723 100644 --- a/docsrc/firebolt.db.rst +++ b/docsrc/firebolt.db.rst @@ -1,9 +1,10 @@ =================== -firebolt.db package +Db =================== +The db package enables connecting to a Firebolt database for synchronous queries. -firebolt.db.connection module +Db.connection ----------------------------- .. automodule:: firebolt.db.connection @@ -11,7 +12,7 @@ firebolt.db.connection module :undoc-members: :show-inheritance: -firebolt.db.cursor module +Db.cursor ------------------------- .. automodule:: firebolt.db.cursor diff --git a/docsrc/firebolt.model.rst b/docsrc/firebolt.model.rst index c7a41bc6366..b0787550002 100644 --- a/docsrc/firebolt.model.rst +++ b/docsrc/firebolt.model.rst @@ -1,9 +1,10 @@ ====================== -firebolt.model package +Model ====================== +The model package contains various classes and functions for managing Firebolt engines and databases. -firebolt.model.database module +Model.database ------------------------------ .. automodule:: firebolt.model.database @@ -12,7 +13,7 @@ firebolt.model.database module :undoc-members: :show-inheritance: -firebolt.model.engine module +Model.engine ---------------------------- .. automodule:: firebolt.model.engine @@ -21,7 +22,7 @@ firebolt.model.engine module :undoc-members: :show-inheritance: -firebolt.model.engine\_revision module +Model.engine\_revision -------------------------------------- .. automodule:: firebolt.model.engine_revision @@ -30,7 +31,7 @@ firebolt.model.engine\_revision module :undoc-members: :show-inheritance: -firebolt.model.instance\_type module +Model.instance\_type ------------------------------------ .. automodule:: firebolt.model.instance_type @@ -39,7 +40,7 @@ firebolt.model.instance\_type module :undoc-members: :show-inheritance: -firebolt.model.provider module +Model.provider ------------------------------ .. automodule:: firebolt.model.provider @@ -47,7 +48,7 @@ firebolt.model.provider module :undoc-members: :show-inheritance: -firebolt.model.region module +Model.region ---------------------------- .. automodule:: firebolt.model.region diff --git a/docsrc/firebolt.service.rst b/docsrc/firebolt.service.rst index 0f5db3cface..c597ba8bd91 100644 --- a/docsrc/firebolt.service.rst +++ b/docsrc/firebolt.service.rst @@ -1,7 +1,8 @@ ======================== -firebolt.service package +Service ======================== +The service package enables launching and cataloging Firebolt engines and databases. .. automodule:: firebolt.service.base :members: @@ -15,7 +16,7 @@ firebolt.service package :undoc-members: :show-inheritance: -firebolt.service.database module +Service.database -------------------------------- .. automodule:: firebolt.service.database @@ -23,7 +24,7 @@ firebolt.service.database module :undoc-members: :show-inheritance: -firebolt.service.engine module +Service.engine ------------------------------ .. automodule:: firebolt.service.engine @@ -37,7 +38,7 @@ firebolt.service.engine module :undoc-members: :show-inheritance: -firebolt.service.instance\_type module +Service.instance\_type -------------------------------------- .. automodule:: firebolt.service.instance_type @@ -46,7 +47,7 @@ firebolt.service.instance\_type module :undoc-members: :show-inheritance: -firebolt.service.manager module +Service.manager ------------------------------- .. automodule:: firebolt.service.manager @@ -54,7 +55,7 @@ firebolt.service.manager module :undoc-members: :show-inheritance: -firebolt.service.provider module +Service.provider -------------------------------- .. automodule:: firebolt.service.provider @@ -62,7 +63,7 @@ firebolt.service.provider module :undoc-members: :show-inheritance: -firebolt.service.region module +Service.region ------------------------------ .. automodule:: firebolt.service.region @@ -70,7 +71,7 @@ firebolt.service.region module :undoc-members: :show-inheritance: -firebolt.service.types module +Service.types ----------------------------- .. automodule:: firebolt.service.types diff --git a/docsrc/index.rst b/docsrc/index.rst index a384c7709e6..8594366bfb0 100644 --- a/docsrc/index.rst +++ b/docsrc/index.rst @@ -3,75 +3,83 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -================= -**firebolt-sdk** -================= - -Welcome to firebolt-sdk's documentation! - ######################## -**Installation** +**Firebolt-python-sdk** ######################## -* Requires Python ``>=3.7`` -* ``pip install firebolt-sdk`` +The Firebolt Python SDK enables connecting to Firebolt, managing Firebolt resources and executing queries using a library of Python classes and functions. + +======================== +Prerequisites +======================== + +* Python version 3.7 or later along with the pip package installer. For more information, see the `Python `_ web page. -########################## -**Connection parameters** -########################## +* A Firebolt account and login credentials. -These parameters are used to connect to a Firebolt database: +======================== +Installation +======================== -* **engine_url** - url for a Firebolt engine to make requests to. This can be retrieved from our web interface, or from the `engine `_ attribute endpoint -* **database** - the name of the database to receive queries -* **username** - Firebolt account username -* **password** - Firebolt account password +Use pip to install the Firebolt Python SDK from the command line as shown in the example below: -Optional parameters +``$ pip install firebolt-sdk`` -* **api_endpoint** - api hostname for logging in. Defaults to ``api.app.firebolt.io``. -############### -**Examples** -############### +Optional features +^^^^^^^^^^^^^^^^^^^ -See `PEP-249 `_ for the DB API reference and specifications. An example `jupyter notebook `_ is included to illustrate the use of the Firebolt API. +By default, the Firebolt Python SDK uses the ``datetime`` module to parse date and datetime values. For large operations involving date and datetime values, the Python SDK can achieve faster results by using the `ciso8601 `_ package, however this can cause installation issues in some cases. +To install firebolt-python-sdk with ``ciso8601`` support, run ``pip install firebolt-sdk[ciso8601]``. -####################### -**Optional features** -####################### -By default, firebolt-sdk uses ``datetime`` module to parse date and datetime values, which might be slow for a large amount of operations. In order to speed up datetime operations, it's possible to use `ciso8601 `_ package. +Release notes +^^^^^^^^^^^^^^ -To install firebolt-sdk with ``ciso8601`` support, run ``pip install firebolt-sdk[ciso8601]`` +For information about changes in the latest version of the Firebolt Python SDK, see the `release notes `_ -################### -**Contributing** -################### -See: `CONTRIBUTING.MD `_ -################### -**License** -################### +Contributing +^^^^^^^^^^^^^^ + +For procedures and requirements for contributing to this SDK, see the `contributing `_ page on Github. + +License +^^^^^^^^ The Firebolt DB API is licensed under the `Apache License Version 2.0 `_ software license. .. note:: - This project is under active development + This project is under active development. ======================================== + + +Walkthroughs and examples +=========================== + +.. toctree:: + :maxdepth: 1 + + Connecting and querying + Managing resources + + +Reference documentation +======================== + .. toctree:: :maxdepth: 1 - firebolt.async_db - firebolt.client - firebolt.common - firebolt.db - firebolt.model - firebolt.service + Async_db + Client + Common + Db + Model + Service @@ -79,5 +87,3 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/src/firebolt/db/cursor.py b/src/firebolt/db/cursor.py index b5b5456552e..512e88ad891 100644 --- a/src/firebolt/db/cursor.py +++ b/src/firebolt/db/cursor.py @@ -26,9 +26,8 @@ class Cursor(AsyncBaseCursor): description: Information about a single result row rowcount: The number of rows produced by last query closed: True if connection is closed, False otherwise - arraysize: Read/Write, - specifies the number of rows to fetch at a time - with :py:func:`fetchmany` method + arraysize: Read/Write, specifies the number of rows to fetch at a time + with the :py:func:`fetchmany` method """ __slots__ = AsyncBaseCursor.__slots__ + (