Updated pyodbc guide

seesharprun · seesharprun · commit 69f75d8e187f · 2023-08-22T19:05:01.000-04:00
diff --git a/docs/connect/python/pymssql/python-sql-driver-pymssql.md b/docs/connect/python/pymssql/python-sql-driver-pymssql.md
@@ -11,28 +11,29 @@ ms.topic: conceptual
 
 # Python SQL Driver - pymssql
 
-[!INCLUDE[Driver_Python_Download](../../../includes/driver_python_download.md)]
+Use the `pymssql` driver to connect to an SQL database from Python code. This series of articles provides step-by-step guidance for installing and using this Python SQL driver.
 
 ## Get started
 
-* [Step 1: Configure development environment for pymssql Python development](step-1-configure-development-environment-for-pymssql-python-development.md)  
-* [Step 2: Create an SQL database for pymssql Python development](step-2-create-a-sql-database-for-pymssql-python-development.md)  
-* [Step 3: Proof of concept connecting to SQL using pymssql](step-3-proof-of-concept-connecting-to-sql-using-pymssql.md)  
+- [Step 1: Configure development environment for pymssql Python development](step-1-configure-development-environment-for-pymssql-python-development.md)  
+- [Step 2: Create an SQL database for pymssql Python development](step-2-create-a-sql-database-for-pymssql-python-development.md)  
+- [Step 3: Proof of concept connecting to SQL using pymssql](step-3-proof-of-concept-connecting-to-sql-using-pymssql.md)  
 
 ## Documentation
 
-* [pymssql documentation](https://pypi.org/project/pymssql/)  
+- [pymssql documentation](https://pypi.org/project/pymssql/)  
 
 ## Support
 
 Pymssql is community-supported software. This software doesn't come with Microsoft support.
 
-To get help, file an [issue in the pymssql GitHub repository](https://github.com/pymssql/pymssql/issues) or visit other Python community resources.
+> [!TIP]
+> To get help, file an [issue in the pymssql GitHub repository](https://github.com/pymssql/pymssql/issues) or visit other Python community resources.
 
 ## Community resources
 
-* [Azure Python Developer Center](https://azure.microsoft.com/develop/python/)  
-* [python.org Community](https://www.python.org/community/)
+- [Azure Python Developer Center](https://azure.microsoft.com/develop/python/)  
+- [python.org Community](https://www.python.org/community/)
 
 ## Next steps
 
diff --git a/docs/connect/python/pymssql/step-1-configure-development-environment-for-pymssql-python-development.md b/docs/connect/python/pymssql/step-1-configure-development-environment-for-pymssql-python-development.md
@@ -12,7 +12,10 @@ ms.topic: how-to
 
 # Step 1: Configure development environment for pymssql Python development
 
-You need to configure your development environment with the prerequisites in order to develop an application using the Python Driver for SQL Server. The Python SQL Drivers use the TDS protocol, which is enabled by default in SQL Server and Azure SQL Database.  No extra configuration is required.
+You need to configure your development environment with the prerequisites in order to develop an application using the pymssql Python driver for SQL Server.
+
+> [!NOTE]
+> This driver uses the TDS protocol, which is enabled by default in SQL Server and Azure SQL Database.  No extra configuration is required.
 
 ## Prerequisites
 
diff --git a/docs/connect/python/pymssql/step-3-proof-of-concept-connecting-to-sql-using-pymssql.md b/docs/connect/python/pymssql/step-3-proof-of-concept-connecting-to-sql-using-pymssql.md
@@ -32,6 +32,14 @@ Connect to a database using your credentials.
 
 1. Create a new file named **app.py**.
 
+1. Add a module docstring.
+
+    ```python
+    """
+    Connects to a SQL database using pymssql
+    """
+    ```
+
 1. Import the `pymssql` package.
 
     ```python
@@ -81,7 +89,7 @@ Use an SQL query string to execute a query and parse the results.
     ```
 
     > [!NOTE]
-    > This function essentially accepts any query and returns a result set, which can be iterated over with the use of [cursor.fetchone()](https://pypi.org/project/pymssql/).
+    > This function essentially accepts any query and returns a result set, which can be iterated over with the use of [cursor.fetchone()]().
 
 1. Use [`cursor.fetchall`](https://pymssql.readthedocs.io/en/latest/ref/pymssql.html#pymssql.Cursor.fetchall) with a `foreach` loop to get all the records from the database. Then print the records.
 
@@ -91,7 +99,9 @@ Use an SQL query string to execute a query and parse the results.
         print(f"{r['CustomerID']}\t{r['OrderCount']}\t{r['CompanyName']}")
     ```
 
-1. Test the application.
+1. **Save** the **app.py** file.
+
+1. Open a terminal and test the application.
 
     ```bash
     python app.py
@@ -121,7 +131,7 @@ In this example, you execute an [`INSERT`](../../../t-sql/statements/insert-tran
     productNumber = randrange(1000)
     ```
 
-    > [!INFORMATION]
+    > [!TIP]
     > Generating a random product number here ensures that you can run this sample multiple times.
 
 1. Create a SQL statement string.
@@ -161,13 +171,26 @@ In this example, you execute an [`INSERT`](../../../t-sql/statements/insert-tran
     conn.commit()
     ```
 
+    > [!TIP]
+    > Optionally, you can use [`connection.rollback`](https://pymssql.readthedocs.io/en/latest/ref/pymssql.html#pymssql.Connection.rollback) to rollback the transaction.
+
+1. Close the cursor and connection using [`cursor.close`](https://pymssql.readthedocs.io/en/latest/ref/pymssql.html#pymssql.Cursor.close) and [`connection.close`](https://pymssql.readthedocs.io/en/latest/ref/pymssql.html#pymssql.Connection.close).
+
+    ```python
+    cursor.close()
+    conn.close()
+    ```
+
+1. **Save** the **app.py** file and test the application again
+
+    ```bash
+    python app.py
+    ```
+
     ```output
     Inserted Product ID : 1001
     ```
 
-    > [!TIP]
-    > Optionally, you can use [`connection.rollback`](https://pymssql.readthedocs.io/en/latest/ref/pymssql.html#pymssql.Connection.rollback) to rollback the transaction.
-
 ## Next steps
 
 > [!div class="nextstepaction"]
diff --git a/docs/connect/python/pyodbc/python-sql-driver-pyodbc.md b/docs/connect/python/pyodbc/python-sql-driver-pyodbc.md
@@ -8,32 +8,32 @@ ms.service: sql
 ms.subservice: connectivity
 ms.topic: conceptual
 ---
-# Python SQL Driver - pyodbc
 
-:::image type="icon" source="../../../includes/media/download.svg" border="false"::: [Install SQL driver for Python](../../sql-connection-libraries.md#anchor-20-drivers-relational-access)
+# Python SQL Driver - pyodbc
 
-This article provides step-by-step guidance for installing and using the Python SQL Driver, pyODBC.
+Use the `pyodbc` driver to connect to an SQL database from Python code. This series of articles provides step-by-step guidance for installing and using this Python SQL driver.
 
 ## Get started
 
-* [Step 1: Configure development environment for pyodbc Python development](step-1-configure-development-environment-for-pyodbc-python-development.md).
-* [Step 2: Create an SQL database for pyodbc Python development](step-2-create-a-sql-database-for-pyodbc-python-development.md).
-* [Step 3: Proof of concept connecting to SQL using pyodbc](step-3-proof-of-concept-connecting-to-sql-using-pyodbc.md).
+- [Step 1: Configure development environment for pyodbc Python development](step-1-configure-development-environment-for-pyodbc-python-development.md)
+- [Step 2: Create an SQL database for pyodbc Python development](step-2-create-a-sql-database-for-pyodbc-python-development.md)
+- [Step 3: Proof of concept connecting to SQL using pyodbc](step-3-proof-of-concept-connecting-to-sql-using-pyodbc.md)
 
 ## Documentation
 
-For documentation, see [pyodbc documentation](https://mkleehammer.github.io/pyodbc/).
+- [pyodbc documentation](https://mkleehammer.github.io/pyodbc/)
 
 ## Support
 
 PyODBC is community-supported software. Microsoft contributes to the pyODBC open-source community and is an active participant in the repository at [https://github.com/mkleehammer/pyodbc/](https://github.com/mkleehammer/pyodbc/). However, this software doesn't come with Microsoft support.
 
-To get help, file an [issue in the pyODBC GitHub repository](https://github.com/mkleehammer/pyodbc/issues) or visit other Python community resources.
+> [!TIP]
+> To get help, file an [issue in the pyODBC GitHub repository](https://github.com/mkleehammer/pyodbc/issues) or visit other Python community resources.
 
 ## Community resources
 
-* [Azure Python Developer Center](https://azure.microsoft.com/develop/python/)  
-* [python.org Community](https://www.python.org/community/)
+- [Azure Python Developer Center](https://azure.microsoft.com/develop/python/)  
+- [python.org Community](https://www.python.org/community/)
 
 ## Next steps
 
diff --git a/docs/connect/python/pyodbc/step-1-configure-development-environment-for-pyodbc-python-development.md b/docs/connect/python/pyodbc/step-1-configure-development-environment-for-pyodbc-python-development.md
@@ -1,58 +1,79 @@
 ---
-title: "Step 1: Configure pyodbc Python environment"
-description: "Step 1 of this getting started guide involves installing Python, the Microsoft ODBC Driver for SQL Server, and pyODBC into your development environment."
+title: Step 1: Configure pyodbc environment
+description: Step 1 of this getting started guide involves installing Python, the Microsoft ODBC Driver for SQL Server, and pyODBC into your development environment.
 author: David-Engel
 ms.author: v-davidengel
-ms.date: 04/17/2023
+ms.date: 08/22/2023
 ms.service: sql
 ms.subservice: connectivity
-ms.topic: conceptual
+ms.topic: how-to
+# CustomerIntent: As a developer, I want to install the pymssql package so that I can connect to SQL with Python code.
 ---
+
 # Step 1: Configure development environment for pyodbc Python development
 
-This article explains how to configure your development environment for pyodbc Python development.
+You need to configure your development environment with the prerequisites in order to develop an application using the pyodbc Python driver for SQL Server.
+
+## Prerequisites
+
+- Python 3
+  - If you don't already have Python, install the **Python runtime** and **Python Package Index (PyPI) package manager** from [python.org](https://www.python.org/downloads/).  
+  - Prefer to not use your own environment? Open as a devcontainer using [GitHub Codespaces](https://github.com/features/codespaces).
+    - [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/github/codespaces-blank?quickstart=1).
+
+## Install the ODBC driver
+
+This driver requires the host operating system to have the appropriate ODBC driver already installed.
+
+### [Windows](#tab/windows)
+
+1. Obtain and install the Microsoft ODBC driver for SQL Server on Windows:
 
-## Windows
+   - [Microsoft ODBC Driver for SQL Server on Windows](../../odbc/windows/system-requirements-installation-and-driver-files.md#installing-microsoft-odbc-driver-for-sql-server)
 
-1. **Download Python installer**. If your machine doesn't have Python, install it. Go to the [**Python download page**](https://www.python.org/downloads/windows/) and download the appropriate installer. For example, if you are on a 64-bit machine, download the Python 3.10 (x64) installer.  
-  
-2. **Install Python**. Once the installer is downloaded, do the following steps:
+1. Verify that you have installed the driver.
 
-   1. Double-click the file to start the installer.
-   1. Select your language, and agree to the terms.
-   1. Follow the instructions on the screen to install Python on your computer.
-   1. You can verify that Python is installed by going to a command prompt and running `python -V`. You can also search for Python in the start menu.
+### [Linux](#tab/linux)
 
-3. [**Install the Microsoft ODBC Driver for SQL Server on Windows**.](../../odbc/windows/system-requirements-installation-and-driver-files.md#installing-microsoft-odbc-driver-for-sql-server)
-  
-4. **Open cmd.exe as an administrator**.
+1. Obtain and install the Microsoft ODBC driver for SQL Server on Linux:
 
-5. **Install pyodbc using pip - Python package manager**.
+   - [Microsoft ODBC driver for SQL Server (Linux)](../../odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server.md)
 
-   ```cmd
-   pip install pyodbc  
-   ```
+1. Verify that you have installed the driver.
+
+### [macOS](#tab/macos)
+
+1. Obtain and install the Microsoft ODBC driver for SQL Server on macOS:
+
+   - [Microsoft ODBC driver for SQL Server (macOS)](../../odbc/linux-mac/install-microsoft-odbc-driver-sql-server-macos.md)
+
+1. Verify that you have installed the driver.
+
+---
 
-## Linux
+## Install the pyodbc package
 
-Installing on Linux is similar. If the following instructions don't work, see the [pyODBC install instructions](https://github.com/mkleehammer/pyodbc/wiki/Install#installing-on-linux), which have more details for different Linux distributions.
+Get the [`pyodbc` package](https://pypi.org/project/pyodbc/) from PyPI.
 
-1. **Open terminal**.
+1. Open a command prompt in an empty directory.
 
-2. [**Install the Microsoft ODBC driver for SQL Server (Linux)**.](../../odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server.md)
+1. Install the [`pyodbc` package](https://pypi.org/project/pyodbc/).
 
-3. **Install pyodbc**.  
+    ```bash
+    pip install pyodbc
+    ```
 
-   ```bash  
-   sudo -H pip install pyodbc
-   ```
+## Check installed packages
 
-## macOS
+You can use the PyPI command-line tool to verify that your intended packages are installed.
 
-1. [**Install the Microsoft ODBC driver for SQL Server (macOS)**.](../../odbc/linux-mac/install-microsoft-odbc-driver-sql-server-macos.md)
+1. Check the list of installed packages with `pip list`.
 
-2. **Install pyodbc** from a terminal using the [pyODBC install instructions](https://github.com/mkleehammer/pyodbc/wiki/Install#installing-on-macosx).
+    ```bash
+    pip list
+    ```
 
 ## Next steps
 
-[Create an SQL database for pyodbc](step-2-create-a-sql-database-for-pyodbc-python-development.md).
+> [!div class="nextstepaction"]
+> [Step 2: Create an SQL database for pyodbc Python development](step-2-create-a-sql-database-for-pyodbc-python-development.md)
diff --git a/docs/connect/python/pyodbc/step-2-create-a-sql-database-for-pyodbc-python-development.md b/docs/connect/python/pyodbc/step-2-create-a-sql-database-for-pyodbc-python-development.md
@@ -1,17 +1,45 @@
 ---
-title: "Step 2: Create a SQL database for pyodbc"
-description: "Step 2 of this getting started guide involves creating a database in SQL Server or Azure SQL Database for the pyodbc sample."
+title: Step 2 - Create an SQL database for pyodbc
+description: Step 2 of this getting started guide involves creating a database in SQL Server or Azure SQL Database for this pyodbc sample.
 author: David-Engel
 ms.author: v-davidengel
-ms.date: "03/24/2022"
+ms.date: 08/22/2023
 ms.service: sql
 ms.subservice: connectivity
-ms.topic: conceptual
+ms.topic: how-to
+# CustomerIntent: As a developer, I want to create a SQL database so that I can connect to it with Python code.
 ---
-# Step 2: Create a SQL database for pyodbc Python development
 
-[!INCLUDE[CreateDatabase](../../../includes/createdatabase.md)]
+# Step 2: Create an SQL database for pyodbc Python development
+
+Create an SQL database using either Azure SQL or SQL Server.
+
+## Prerequisites
+
+- Python 3
+  - If you don't already have Python, install the **Python runtime** and **Python Package Index (PyPI) package manager** from [python.org](https://www.python.org/downloads/).
+  - Prefer to not use your own environment? Open as a devcontainer using [GitHub Codespaces](https://github.com/features/codespaces).
+    - [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/github/codespaces-blank?quickstart=1).
+- `pyodbc` package from PyPI.
+
+## Create an SQL database
+
+The samples in this next section only work with the AdventureWorks schema, on either Microsoft SQL Server or Azure SQL Database.
+
+### [Azure SQL Database](#tab/azure-sql)
+
+[Create an SQL database in minutes using the Azure portal](/azure/azure-sql/database/single-database-create-quickstart)
+
+### [Microsoft SQL Server](#tab/sql-server)
+
+[Microsoft SQL Server Samples on GitHub](https://github.com/Microsoft/sql-server-samples/releases/tag/adventureworks)
+
+---
+
+> [!IMPORTANT]
+> Don't forget to get the credentials for the database you create.
 
 ## Next steps
 
-[Connect to SQL using pyodbc](step-3-proof-of-concept-connecting-to-sql-using-pyodbc.md)
+> [!div class="nextstepaction"]
+> [Step 3: Proof of concept connecting to SQL using pyodbc](step-3-proof-of-concept-connecting-to-sql-using-pyodbc.md)
diff --git a/docs/connect/python/pyodbc/step-3-proof-of-concept-connecting-to-sql-using-pyodbc.md b/docs/connect/python/pyodbc/step-3-proof-of-concept-connecting-to-sql-using-pyodbc.md
