Merge pull request #64 from fdcastel/v2.1

Release 2.1

.gitignore

@@ -1,4 +1,5 @@
 .idea/
+.venv/
 _venv/
 /venv/
 build/

.vscode/launch.json

@@ -0,0 +1,30 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Module",
+            "type": "python",
+            "request": "launch",
+            "module": "pytest",
+            "env": {"CI": "True"},
+            "args": [
+                "./test/test_suite.py::NormalizedNameTest::test_get_table_names",
+                "--db",
+                "firebird_fb50"
+            ],
+            "justMyCode": false
+        },
+        {
+            // Disable JustMyCode on Pytest -- https://stackoverflow.com/a/57831657
+            "name": "Debug Unit Test",
+            "type": "python",
+            "request": "launch",
+            "console": "integratedTerminal",
+            "purpose": ["debug-test"],
+            "justMyCode": false
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter",
+        "editor.formatOnSave": true
+    },
+    "python.testing.pytestArgs": [
+        "test",
+        "--tb=no",
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+}

README.development.md

@@ -0,0 +1,138 @@
+# Development notes
+
+Support for 32/64 bit Python 2.7, 3.6+ on Windows/Linux/Mac.
+
+* Use `firebird-driver` and/or `fdb`
+    * Python >= 3.8
+    * SQLAlchemy 1.4 or 2.0
+
+* Use `fdb`
+    * Python == 3.7 and SQLAlchemy 2.0
+    * Python >= 3.6 and SQLAlchemy 1.4
+
+
+# Windows environment
+
+## Install Python
+
+You may install Python with [Chocolatey](https://chocolatey.org/install):
+
+```powershell
+choco install python -y
+```
+
+
+## Install Visual Studio Code
+
+We strongly recommend Visual Studio Code for development. You may install it with:
+
+```powershell
+choco install vscode -y
+```
+
+
+## Initial checkout
+
+Clone this repository into a local folder on your computer and, from the root folder, run 
+
+```powershell
+python -m venv .venv
+.venv/Scripts/activate
+pip install .[dev]
+pip install fdb
+```
+
+This will create a Python virtual environment in `.venv` subfolder and install all required components.
+
+Open the project folder with VSCode. It should detect the virtual environment automatically and activate it. Please refer to [Visual Studio Code documentation on Python](https://code.visualstudio.com/docs/languages/python) for more information.
+
+To activate the virtual environment on a command prompt instance (cmd or powershell) use:
+
+```powershell
+.venv/Scripts/activate
+```
+
+
+# Linux environment
+
+## Initial checkout
+
+Clone this repository into a local folder on your computer and, from the root folder, run 
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install .[dev]
+pip install fdb
+```
+
+This will create a Python virtual environment in `.venv` subfolder and install all required components.
+
+To activate the virtual environment use:
+
+```bash
+. .venv/bin/activate
+```
+
+
+# Tests
+
+## Preparing the tests infrastructure
+
+With the virtual environment activated, run the following script
+
+```
+rebuild-test-databases
+```
+
+This script will 
+
+- Create a `sqlalchemy-firebird-tests` in your temp folder containing the binaries for each supported Firebird version;
+- Create databases for each Firebird version; and
+- Add a `[db]` section into your `setup.cfg` containing one entry for each of the databases created.
+
+You may run this script whenever you need a clean database for your tests. It won't download the files again if they already exist.
+
+
+## Running the tests
+
+Run the following Powershell script
+
+```powershell
+.\run-all-tests.ps1
+```
+
+This will start 5 different processes, each one running a different combination of driver/Firebird version supported.
+
+To run only the tests for a specific database, use
+
+```powershell
+.\run-tests.ps1 -Database 'firebird_fb50'
+```
+
+
+## Debugging the tests
+
+SQLAlchemy has a complex test infrastructure which unfortunately is not completely functional from VSCode test runner.
+
+To run a specific test under VSCode debugger this repository already provides a `.vscode/launch.json` file preconfigured as a sample.
+
+E.g. to run the test `test_get_table_names` with `firebird-driver` and Firebird 5.0 you must set `pytest` arguments as:
+
+```json
+"args": ["./test/test_suite.py::NormalizedNameTest::test_get_table_names", "--db", "firebird_fb50"],
+```
+
+Now run the code (with `F5`) and the debugger should work as expected (e.g. set a breakpoint and it should stop).
+
+
+## Debugging SQLAlchemy code
+
+Sooner or later you probably will need to debug SQLAlchemy code. Fortunately, this is easy as
+
+```bash
+# [From your 'sqlalchemy-firebird' root folder, inside virtual environment]
+pip install -e $path_to_your_sqlalchemy_local_folder
+```
+
+The `launch.json` file already has the required `"justMyCode": false` configuration which allows you to step into SQLAlchemy source files during debugging.

pyproject.toml

@@ -3,7 +3,6 @@ addopts = "--tb native -v -r fxX --maxfail=100 -p no:warnings --log-info=sqlalch
 
 markers = [
     "backend: mark test as for the backend",
-    "hanging: tests hanging during a full test suite run",
 ]
 
 python_files = "test/*test_*.py"
@@ -22,7 +21,7 @@ exclude = '''
 '''
 
 [build-system]
-requires = ["setuptools"]
+requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -71,6 +70,10 @@ Tracker = "https://github.com/pauldex/sqlalchemy-firebird/issues"
 "firebird.fdb" = "sqlalchemy_firebird.fdb:FBDialect_fdb"
 "firebird.firebird" = "sqlalchemy_firebird.firebird:FBDialect_firebird"
 
+[project.scripts]
+prepare-test-environment = "sqlalchemy_firebird:infrastructure.prepare_test_environment"
+rebuild-test-databases = "sqlalchemy_firebird:infrastructure.rebuild_test_databases"
+
 [tool.setuptools.dynamic]
 readme = {file = ["README.rst"], content-type = "text/x-rst"}
 version = {attr = "sqlalchemy_firebird.__version__"}

run-all-tests.ps1

@@ -0,0 +1,7 @@
+#
+# Run all tests in parallel (one process per driver/engine combination)
+#
+
+'fdb_fb25','fdb_fb30','firebird_fb30','firebird_fb40','firebird_fb50' | ForEach-Object {
+    Start-Process 'powershell' ".\.venv\Scripts\activate ; while (`$true) { .\run-tests.ps1 -Db $_ ; pause }"
+}

run-tests.ps1

@@ -0,0 +1,44 @@
+#
+# Run all tests for a given driver/engine.
+#
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory=$true)]
+    [ValidateScript({
+        if (Get-Content 'setup.cfg' | Select-String -Pattern "^$_\s*=") { return $true }
+        throw [System.Management.Automation.ValidationMetadataException] "The database '$_' was not found in 'setup.cfg'."
+    })]
+    [string]$Database
+)
+
+if (-not $env:VIRTUAL_ENV) {
+    throw "Virtual environment not detected. Please run '.venv/scripts/activate' first."
+}
+
+# Set console width
+[console]::WindowWidth=260
+
+Clear-Host   
+Write-Warning "Using connection '$Database'..."
+
+# Recreate test database
+rebuild-test-databases $Database
+
+# pytest: do not truncate error messages -- https://github.com/pytest-dev/pytest/issues/9920
+$env:CI = 'True' 
+
+# pytest additional parameters
+$extraParams = @(
+    '--tb=no',    # Disable tracebacks
+    '--color=yes' # Force color in output. Pytest disables it because Tee-Object redirection.
+)
+
+# Run pytest
+$host.ui.RawUI.WindowTitle = "[$Database]: (Running...)"
+& pytest --db $Database $extraParams 2>$null | Tee-Object -Variable testOutput
+$pytestExitCode = $LASTEXITCODE
+
+# Update window title with test results
+$summary1st = $testOutput[-1] -replace '\x1b\[\d+(;\d+)?m' -replace '='    # strip colors and '='
+$host.ui.RawUI.WindowTitle = "[$Database]: $summary1st (exit code = $pytestExitCode)"