Merge pull request #8 from Ensembl/jalvarez/add_test_utils

Add unit test utils

.github/actions/python_build/action.yml

@@ -20,6 +20,10 @@ inputs:
     description: "Python version"
     required: true
     default: "3.10"
+  sqlalchemy-version:
+    description: SQLAlchemy version to run the CI checks on
+    required: true
+    default: "2.*"
   tags:
     description: "Optional dependencies (via available tags) to install, e.g. [cicd]"
     required: true
@@ -36,5 +40,6 @@ runs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
+        pip install sqlalchemy==${{ inputs.sqlalchemy-version }}
         pip install -e .${{ inputs.tags }}
       shell: bash

.github/workflows/ci.yml

@@ -39,3 +39,4 @@ jobs:
     uses: ./.github/workflows/python_ci.yml
     with:
       python-version: "3.10"
+      sqlalchemy-version: "2.*"

.github/workflows/ci_dev.yml

@@ -23,10 +23,15 @@ on:
         description: Python version
         required: true
         type: string
+      sqlalchemy-version:
+        description: SQLAlchemy version
+        required: true
+        type: string
 
 jobs:
   python_ci:
     name: Python CI
     uses: ./.github/workflows/python_ci.yml
     with:
       python-version: ${{ inputs.python-version }}
+      sqlalchemy-version: ${{ inputs.sqlalchemy-version }}

.github/workflows/python_ci.yml

@@ -22,6 +22,10 @@ on:
         description: Python version to run the CI checks on
         required: true
         type: string
+      sqlalchemy-version:
+        description: SQLAlchemy version to run the CI checks on
+        required: true
+        type: string
 
 defaults:
   run:
@@ -88,6 +92,7 @@ jobs:
       - uses: ./.github/actions/python_build
         with:
           python-version: ${{ inputs.python-version }}
+          sqlalchemy-version: ${{ inputs.sqlalchemy-version }}
           tags: "[cicd]"
 
       - name: Run pytest with coverage

.licenserc.yml

@@ -18,9 +18,11 @@ header:
 
   paths-ignore:
     - '**/*.md'
-    - 'tests/**/test_*/*'
+    - 'tests/**/test_*/**/*'
     - '.gitignore'
     - 'LICENSE'
     - 'NOTICE'
+    # symlinks
+    - 'tests/database/test_dbconnection'
 
   comment: on-failure

README.md

@@ -16,3 +16,22 @@ This library is publicly available in [PyPI](https://pypi.org/project/ensembl-ut
 ```bash
 pip install ensembl-utils
 ```
+
+### Quick usage
+
+Besides the standard `import ensembl.utils`, this library also provides some useful command line scripts:
+- `extract_file` - to easily extract archive files in different formats
+
+Furthermore, `ensembl-utils` also has a [`pytest`](https://docs.pytest.org/) plugin with some useful functionalities to ease your unit testing. You can enable it by adding it explicitly when running pytest:
+```bash
+pytest -p ensembl.utils.plugin ...
+```
+
+Or adding the following line to your `conftest.py`:
+```python
+pytest_plugins = ("ensembl.utils.plugin",)
+```
+
+## Dependencies
+
+This repository has been developed to support [SQLAlchemy](https://www.sqlalchemy.org) version 1.4 (1.4.45 or later, to ensure "future-compatibility") as well as version 2.0+.

docs/index.md

@@ -6,9 +6,10 @@ Centralise generic Python utils used by other project within Ensembl design to f
 Check out [installation](install.md) section for further information on how to install the project.
 
 1. [Install](install.md)
-2. [Code of Conduct](code_of_conduct.md)
-3. [Coverage report](coverage.md)
-4. [Code reference](reference/)
+2. [Usage](usage.md)
+3. [Code of Conduct](code_of_conduct.md)
+4. [Coverage report](coverage.md)
+5. [Code reference](reference/)
 
 ## License
 Software as part of [Ensembl Python general-purpose utils](https://github.com/Ensembl/ensembl-utils) is distributed under the [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.txt).

docs/usage.md

@@ -0,0 +1,30 @@
+# Using these utils
+
+You can easily take advantage of the provided functionalities by importing this library in your code as usual:
+```python
+import ensembl.utils
+```
+
+This library also provides some scripts that can help you via the command line:
+- `extract_file` - to easily extract archive files in different formats
+
+_Note:_ All of them include the `--help` option to provide further information about their purpose and how to use them.
+
+## `pytest` plugin
+
+This repository provides a [`pytest`](https://docs.pytest.org/) plugin with some useful functionalities to do unit testing. In particular, there is one fixture to access the test files in a folder with the same name as the test being run (`data_dir`) and a fixture to build and provide unit test databases (`test_dbs`).
+
+To use these elements you need to enable the plugin once you have installed the repository. There are two main ways to do this:
+1. Explicitly indicating it when running `pytest`:
+    ```bash
+    pytest -p ensembl.utils.plugin ...
+    ```
+
+2. Adding the following line to your `conftest.py` file at the root of where the unit tests are located:
+    ```python
+    pytest_plugins = ("ensembl.utils.plugin",)
+    ```
+
+## Dependencies
+
+This repository has been developed to support [SQLAlchemy](https://www.sqlalchemy.org) version 1.4 (1.4.45 or later, to ensure "future-compatibility") as well as version 2.0+.

mkdocs.yml

@@ -74,6 +74,7 @@ nav:
   - Home:
     - Overview: index.md
     - Install: install.md
+    - Usage: usage.md
   - Development:
     - Code of Conduct: code_of_conduct.md
     - Coverage report: coverage.md

pyproject.toml

@@ -33,6 +33,7 @@ keywords = [
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
+    "Framework :: Pytest",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
@@ -45,10 +46,12 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
+    "pytest >= 8.2.0",
     "python-dotenv >= 0.19.2",
     "pyyaml ~= 6.0",
     "requests >= 2.22.0",
-    "sqlalchemy >= 1.4.0",
+    "sqlalchemy >= 1.4.45",
+    "sqlalchemy_utils >= 0.41.2",
 ]
 
 [project.optional-dependencies]
@@ -64,9 +67,7 @@ cicd = [
     "genbadge[coverage]",
     "mypy",
     "pylint",
-    "pytest",
     "pytest-dependency",
-    "requests-mock >= 1.8.0",
     "types-pyyaml",
     "types-requests",
 ]
@@ -86,7 +87,8 @@ docs = [
 [project.urls]
 Homepage = "https://www.ensembl.org"
 Documentation = "https://ensembl.github.io/ensembl-utils/"
-Repository = "https://github.com/Ensembl/ensembl-utils"
+Repository = "https://github.com/Ensembl/ensembl-utils.git"
+Issues = "https://github.com/Ensembl/ensembl-utils/issues"
 
 [project.scripts]
 extract_file = "ensembl.utils.archive:extract_file_cli"

src/ensembl/utils/__init__.py

@@ -14,14 +14,14 @@
 # limitations under the License.
 """Ensembl Python general-purpose utils library."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "StrPath",
 ]
 
 import os
-from typing import Union
+from typing import TypeVar
 
 
-StrPath = Union[str, os.PathLike]
+StrPath = TypeVar("StrPath", str, os.PathLike)

src/ensembl/utils/archive.py

@@ -14,6 +14,8 @@
 # limitations under the License.
 """Utils for common IO operations over archive files, e.g. tar or gzip."""
 
+from __future__ import annotations
+
 __all__ = [
     "SUPPORTED_ARCHIVE_FORMATS",
     "open_gz_file",

src/ensembl/utils/argparse.py

@@ -28,6 +28,8 @@
 
 """
 
+from __future__ import annotations
+
 __all__ = [
     "ArgumentParser",
 ]

src/ensembl/utils/database/__init__.py

@@ -0,0 +1,20 @@
+# See the NOTICE file distributed with this work for additional information
+# regarding copyright ownership.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Database module."""
+
+from __future__ import annotations
+
+from .dbconnection import *
+from .unittestdb import *