chore: update documentation and minor bug fixes (#532)

Author: karenc-bq

.github/workflows/draft_release.yml

@@ -64,4 +64,5 @@ jobs:
           draft: true
           name: "AWS Advanced Python Wrapper - v${{ env.RELEASE_VERSION }}"
           bodyFile: RELEASE_DETAILS.md
+          artifacts: ./dist/*
           token: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -1,4 +1,4 @@
-## [1.0.0] - 2023-10-xx
+## [1.0.0] - 2024-05-16
 The Amazon Web Services (AWS) Advanced Python Wrapper allows an application to take advantage of the features of clustered Aurora databases.
 
 ### :magic_wand: Added

Maintenance.md

@@ -0,0 +1,58 @@
+# Release Schedule
+
+| Release Date | Release                                                                                    |
+|--------------|--------------------------------------------------------------------------------------------|
+| May 16, 2024 | [Release 1.0.0](https://github.com/awslabs/aws-advanced-python-wrapper/releases/tag/1.0.0) |
+
+`aws-advanced-python-wrapper` [follows semver](https://semver.org/#semantic-versioning-200) which means we will only
+release breaking changes in major versions. Generally speaking patches will be released to fix existing problems without
+adding new features. Minor version releases will include new features as well as fixes to existing features. We will do
+our best to deprecate existing features before removing them completely.
+
+For minor version releases, `aws-advanced-python-wrapper` uses a “release-train” model. Approximately every four weeks we
+release a new minor version which includes all the new features and fixes that are ready to go.
+Having a set release schedule makes sure `aws-advanced-python-wrapper` is released in a predictable way and prevents a
+backlog of unreleased changes.
+
+In contrast, `aws-advanced-python-wrapper` releases new major versions only when there are a critical mass of
+breaking changes (e.g. changes that are incompatible with existing APIs). This tends to happen if we need to
+change the way the driver is currently working. Fortunately, the JDBC API is fairly mature and has not changed, however
+in the event that the API changes we will release a version to be compatible.
+
+Please note: Both the roadmap and the release dates reflect intentions rather than firm commitments and may change
+as we learn more or encounter unexpected issues. If dates do need to change, we will be as transparent as possible,
+and log all changes in the changelog at the bottom of this page.
+
+# Maintenance Policy
+
+For `aws-advanced-python-wrapper` new features and active development always takes place against the newest version.
+The `aws-advanced-python-wrapper` project follows the semantic versioning specification for assigning version numbers
+to releases, so you should be able to upgrade to the latest minor version of that same major version of the
+software without encountering incompatible changes (e.g., 1.1.0 → 1.3.x).
+
+Sometimes an incompatible change is unavoidable. When this happens, the software’s maintainers will increment
+the major version number (e.g., increment from `aws-advanced-python-wrapper` 1.1.1 to `aws-advanced-python-wrapper` 2.0.0).
+The last minor version of the previous major version of the software will then enter a maintenance window
+(e.g., 1.3.x). During the maintenance window, the software will continue to receive bug fixes and security patches,
+but no new features.
+
+We follow OpenSSF’s best practices for patching publicly known vulnerabilities, and we make sure that there are
+no unpatched vulnerabilities of medium or higher severity that have been publicly known for more than 60 days
+in our actively maintained versions.
+
+The duration of the maintenance window will vary from product to product and release to release.
+By default, versions will remain under maintenance until the next major version enters maintenance,
+or 1-year passes, whichever is longer. Therefore, at any given time, the current major version and
+previous major version will both be supported, as well as older major versions that have been in maintenance
+for less than 12 months. Please note that maintenance windows are influenced by the support schedules for
+dependencies the software includes, community input, the scope of the changes introduced by the new version,
+and estimates for the effort required to continue maintenance of the previous version.
+
+The software maintainers will not back-port fixes or features to versions outside the maintenance window.
+That said, PRs with said back-ports are welcome and will follow the project's review process.
+No new releases will result from these changes, but interested parties can create their own distribution
+from the updated source after the PRs are merged.
+
+| Major Version | Latest Minor Version | Status  | Initial Release | Maintenance Window Start | Maintenance Window End |
+|---------------|----------------------|---------|-----------------|--------------------------|------------------------|
+| 1             | 1.0.0                | Current | May 16, 2024    | May 16, 2024             | N/A                    | 

README.md

@@ -211,12 +211,12 @@ The `aws-advanced-python-wrapper` has a regular monthly release cadence. A new r
 
 This `aws-advanced-python-wrapper` is being tested against the following Community and Aurora database versions in our test suite:
 
-| Database          | Versions                                                                                                                                                                                                  |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| MySQL             | 8.3.0                                                                                                                                                                                                     |
-| PostgreSQL        | 15.2                                                                                                                                                                                                      |
-| Aurora MySQL      | MySQL	8.0.mysql_aurora.3.02.2 (Wire-compatible with MySQL 8.0.23 onward. For more details see [here](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.3022.html)) |
-| Aurora PostgreSQL | 14.7 and 15.2 (Compatible with PostgreSQL 14.7 and 15.2, see release notes [here](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/AuroraPostgreSQL.Updates.html))               |
+| Database          | Versions                                                                                                                                                                                                                                                                                                                         |
+|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| MySQL             | 8.3.0                                                                                                                                                                                                                                                                                                                            |
+| PostgreSQL        | 16.2                                                                                                                                                                                                                                                                                                                             |
+| Aurora MySQL      | - LTS version, see [here](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.Versions.html#AuroraMySQL.Updates.LTS) for more details. <br><br> - Latest release, as shown on [this page](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.30Updates.html). |
+| Aurora PostgreSQL | - LTS version, see [here](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Updates.LTS.html) for more details. <br><br> - Latest release, as shown on [this page](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/AuroraPostgreSQL.Updates.html).)                        |
 
 The `aws-advanced-python-wrapper` is compatible with MySQL 5.7 and MySQL 8.0 as per MySQL Connector/Python.
 

aws_advanced_python_wrapper/driver_info.py

@@ -12,15 +12,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-import os
-from pathlib import Path
-
-import toml
-
-PROJECT_DIR = Path(__file__).parent.parent
-PYPROJECT = toml.load(os.path.join(PROJECT_DIR, "pyproject.toml"))
-
 
 class DriverInfo:
-    DRIVER_NAME = PYPROJECT["tool"]["poetry"]["description"]
-    DRIVER_VERSION = PYPROJECT["tool"]["poetry"]["version"]
+    DRIVER_NAME = "aws_advanced_python_wrapper"
+    DRIVER_VERSION = "1.0.0-rc"

aws_advanced_python_wrapper/host_monitoring_plugin.py

@@ -638,9 +638,15 @@ def release_monitor(self, monitor: Monitor):
             self._monitor_map.remove_matching_values([monitor])
             self._tasks_map.compute_if_present(monitor, MonitoringThreadContainer._cancel)
 
-    # This method is only used for cleanup during testing
     @staticmethod
-    def release_instance():
+    def clean_up():
+        """Clean up any dangling monitoring threads created by the host monitoring plugin.
+        This method should be called at the end of the application.
+        The Host Monitoring Plugin creates monitoring threads in the background to monitor all connections established to each of cluster instances.
+        The threads will terminate if there are no connections to the cluster instance the thread is monitoring for over a period of time,
+        specified by the `monitor_disposal_time_ms`. Client applications can also manually call this method to clean up any dangling resources.
+        This method should be called right before application termination.
+        """
         if MonitoringThreadContainer._instance is None:
             return
 
@@ -649,7 +655,6 @@ def release_instance():
                 MonitoringThreadContainer._instance._release_resources()
                 MonitoringThreadContainer._instance = None
 
-    # This method is only used for cleanup during testing
     def _release_resources(self):
         with self._monitor_lock:
             self._monitor_map.clear()
@@ -662,7 +667,9 @@ def _release_resources(self):
 
             self._tasks_map.clear()
 
+            # Reset the executor.
             self._executor.shutdown(wait=False)
+            MonitoringThreadContainer._executor = ThreadPoolExecutor(thread_name_prefix="MonitoringThreadContainerExecutor")
 
 
 class MonitorService:

aws_advanced_python_wrapper/utils/pg_exception_handler.py

@@ -35,9 +35,13 @@ def is_network_exception(self, error: Optional[Exception] = None, sql_state: Opt
         if isinstance(error, QueryTimeoutError) or isinstance(error, ConnectionTimeout):
             return True
         if sql_state is None:
-            error_sql_state = getattr(error, "sqlstate")
-            if error_sql_state is not None:
-                sql_state = error_sql_state
+            try:
+                error_sql_state = getattr(error, "sqlstate")
+                if error_sql_state is not None:
+                    sql_state = error_sql_state
+            except AttributeError:
+                # getattr may throw an AttributeError if the error does not have a `sqlstate` attribute
+                pass
 
         if sql_state is not None and sql_state in self._NETWORK_ERRORS:
             return True

docs/examples/PGFailover.py

@@ -18,6 +18,9 @@
 
 import psycopg
 
+from aws_advanced_python_wrapper.host_monitoring_plugin import \
+    MonitoringThreadContainer
+
 if TYPE_CHECKING:
     from aws_advanced_python_wrapper.pep249 import Connection
 
@@ -61,27 +64,37 @@ def execute_queries_with_failover_handling(conn: Connection, sql: str, params: O
 
 
 if __name__ == "__main__":
+    props = {
+        "monitoring-connect_timeout": 10,
+        "monitoring-socket_timeout": 10
+    }
+
     with AwsWrapperConnection.connect(
             psycopg.Connection.connect,
             host="database.cluster-xyz.us-east-1.rds.amazonaws.com",
             dbname="postgres",
             user="john",
             password="pwd",
-            plugins="failover",
-            wrapper_dialect="aurora-pg",
+            plugins="failover,host_monitoring",
+            connect_timeout=30,
+            socket_timeout=30,
             autocommit=True
     ) as awsconn:
-        configure_initial_session_states(awsconn)
-        execute_queries_with_failover_handling(
-            awsconn, "CREATE TABLE IF NOT EXISTS bank_test (id int primary key, name varchar(40), account_balance int)")
-        execute_queries_with_failover_handling(
-            awsconn, "INSERT INTO bank_test VALUES (%s, %s, %s)", (0, "Jane Doe", 200))
-        execute_queries_with_failover_handling(
-            awsconn, "INSERT INTO bank_test VALUES (%s, %s, %s)", (1, "John Smith", 200))
-
-        cursor = execute_queries_with_failover_handling(awsconn, "SELECT * FROM bank_test")
-        res = cursor.fetchall()
-        for record in res:
-            print(record)
-
-        execute_queries_with_failover_handling(awsconn, "DROP TABLE bank_test")
+        try:
+            configure_initial_session_states(awsconn)
+            execute_queries_with_failover_handling(
+                awsconn, "CREATE TABLE IF NOT EXISTS bank_test (id int primary key, name varchar(40), account_balance int)")
+            execute_queries_with_failover_handling(
+                awsconn, "INSERT INTO bank_test VALUES (%s, %s, %s)", (0, "Jane Doe", 200))
+            execute_queries_with_failover_handling(
+                awsconn, "INSERT INTO bank_test VALUES (%s, %s, %s)", (1, "John Smith", 200))
+
+            cursor = execute_queries_with_failover_handling(awsconn, "SELECT * FROM bank_test")
+            res = cursor.fetchall()
+            for record in res:
+                print(record)
+
+            execute_queries_with_failover_handling(awsconn, "DROP TABLE bank_test")
+        finally:
+            # Clean up any remaining resources created by the Host Monitoring Plugin.
+            MonitoringThreadContainer.clean_up()

docs/using-the-python-driver/using-plugins/UsingTheHostMonitoringPlugin.md

@@ -16,6 +16,15 @@ One use case is to pair EFM with the [Failover Connection Plugin](./UsingTheFail
 
 The Host Monitoring Connection Plugin will be loaded by default if the [`plugins`](../UsingThePythonDriver.md#connection-plugin-manager-parameters) parameter is not specified. The Host Monitoring Connection Plugin can also be explicitly loaded by adding the plugin code `host_monitoring` to the [`plugins`](../UsingThePythonDriver.md#aws-advanced-python-driver-parameters) parameter. Enhanced Failure Monitoring is enabled by default when the Host Monitoring Connection Plugin is loaded, but it can be disabled by setting the `failure_detection_enabled` parameter to `False`.
 
+This plugin only works with drivers that support aborting connections from a separate thread. At this moment, this plugin is incompatible with the MySQL Connector/Python driver.
+
+> [IMPORTANT]\
+> The Host Monitoring Plugin creates monitoring threads in the background to monitor all connections established to each cluster instance. The monitoring threads can be cleaned up in two ways:
+> 1. If there are no connections to the cluster instance the thread is monitoring for over a period of time, the Host Monitoring Plugin will automatically terminate the thread. This period of time is adjustable via the `monitor_disposal_time_ms` parameter.
+> 2. Client applications can manually call `MonitoringThreadContainer.clean_up()` to clean up any dangling resources.
+> It is best practice to call `MonitoringThreadContainer.clean_up()` at the end of the application to ensure a graceful exit; otherwise, the application may wait until the `monitor_disposal_time_ms` has been passed before terminating. This is because the Python driver waits for all daemon threads to complete before exiting.
+> See [PGFailover](../../examples/PGFailover.py) for an example.
+
 ### Enhanced Failure Monitoring Parameters
 
 <div style="text-align:center"><img src="../../images/monitor_process.png" /></div>
@@ -44,6 +53,11 @@ The Host Monitoring Connection Plugin may create new monitoring connections to c
 import psycopg
 from aws_advanced_python_wrapper import AwsWrapperConnection
 
+props = {
+    "monitoring-connect_timeout": 10,
+    "monitoring-socket_timeout": 10
+}
+    
 conn = AwsWrapperConnection.connect(
     psycopg.Connection.connect,
     host="database.cluster-xyz.us-east-1.rds.amazonaws.com",
@@ -54,7 +68,7 @@ conn = AwsWrapperConnection.connect(
     # Configure the timeout values for all non-monitoring connections.
     connect_timeout=30, socket_timeout=30,
     # Configure different timeout values for the monitoring connections.
-    monitoring-connect_timeout=10, monitoring-socket_timeout=10)
+    **props)
 ```
 
 > [!IMPORTANT]\