Merge pull request #367 from BCG-X-Official/dev/3.0rc0

BUILD: release Pytools to 3.0rc0

.pre-commit-config.yaml

@@ -5,20 +5,20 @@ repos:
       - id: isort
 
   - repo: https://github.com/psf/black
-    rev: 23.10.1
+    rev: 24.4.2
     hooks:
       - id: black
-        language: python_venv
-        language_version: python39
+        language: python
+        language_version: python311
 
   - repo: https://github.com/pycqa/flake8
-    rev: 5.0.4
+    rev: 7.0.0
     hooks:
       - id: flake8
         name: flake8
         entry: flake8 --config tox.ini
-        language: python_venv
-        language_version: python39
+        language: python
+        language_version: python311
         additional_dependencies:
           - flake8-comprehensions ~= 3.10
         types: [ python ]
@@ -30,15 +30,15 @@ repos:
       - id: check-json
       - id: check-xml
       - id: check-yaml
-        language: python_venv
+        language: python
         exclude: condabuild/meta.yaml
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.2.0
+    rev: v1.10.0
     hooks:
       - id: mypy
         files: src|sphinx|test
-        language: python_venv
-        language_version: python39
+        language: python
+        language_version: python311
         additional_dependencies:
           - numpy~=1.24

README.rst

@@ -113,7 +113,7 @@ or have a look at
 .. |azure_code_cov| image:: https://img.shields.io/azure-devops/coverage/gamma-facet/facet/9/2.1.x
    :target: https://dev.azure.com/gamma-facet/facet/_build?definitionId=9&_a=summary
 
-.. |python_versions| image:: https://img.shields.io/badge/python-3.7|3.8|3.9-blue.svg
+.. |python_versions| image:: https://img.shields.io/badge/python-3.10|3.11|3.12-blue.svg
     :target: https://www.python.org/downloads/release/python-380/
 
 .. |code_style| image:: https://img.shields.io/badge/code%20style-black-000000.svg

RELEASE_NOTES.rst

@@ -5,6 +5,99 @@ Release Notes
 .. |nbsp| unicode:: 0xA0
    :trim:
 
+*pytools* 3.0
+-------------
+
+*pytools* 3.0 adds support for language features introduced up to and including
+Python 3.11, and drops support for Python versions.
+
+
+*pytools* 3.0.0
+~~~~~~~~~~~~~~~
+
+- :mod:`pytools.api`: new utility functions to get object's init parameters, validate
+  ``__all__`` declarations, and define stand-in objects for missing classes and
+  functions
+
+    - API: new function :func:`.get_init_params` to retrieve the object attributes
+      associated with the object's ``__init__`` method
+    - API: new metaclass :class:`MissingClassMeta` to define a stand-in class for a
+      missing class that could not be imported from an optional dependency
+    - API: new function :func:`.missing_function` to define a stand-in function for a
+      missing function that could not be imported from an optional dependency
+    - API: new function :func:`.validate__all__declarations` to validate the ``__all__``
+      declarations of a module and its submodules
+
+- :mod:`pytools.asyncio`: new module with utility functions for asynchronous programming
+
+  - :func:`.arun` to run an asynchronous function in a new event loop
+  - :func:`.aenumerate` to enumerate an asynchronous iterable
+  - :func:`.async_flatten` to flatten nested asynchronous iterables for optimized
+    asynchronous processing
+  - :func:`.iter_async_to_sync` to convert an asynchronous iterable to a synchronous
+    one
+  - :func:`.iter_sync_to_async` to convert a synchronous iterable to an asynchronous
+    one
+  - :func:`.unpack_exception_group` to unpack an exception group into one or more
+    individual exceptions
+
+- :mod:`pytools.data.taxonomy`: new submodule with classes :class:`.Taxonomy` and
+  :class:`.Category` to represent hierarchical taxonomies
+
+- :mod:`pytools.expression`:
+
+  - new function :func:`.expression_from_init_params` to create an object's
+    :class:`.Expression` representation from the attributes in its ``__init__`` method
+  - new submodule :mod:`pytools.expression.repr` with enhanced versions of standard
+    Python container classes implementing the :class:`.HasExpressionRepr` interface:
+
+    - :class:`.ListWithExpressionRepr` for lists
+    - :class:`.TupleWithExpressionRepr` for tuples
+    - :class:`.SetWithExpressionRepr` for sets
+    - :class:`.DictWithExpressionRepr` for dictionaries
+
+- :mod:`pytools.http`: new module with function :func:`.fetch_url` to download a file
+  from a URL
+
+- :mod:`pytools.repr`: new module with mixin class :class:`.HasDictRepr`, providing a
+  method to return a dictionary representation of an object
+
+- :mod:`pytools.sphinx`: new utilities for generating Sphinx documentation
+
+  - API: new decorator :obj:`.apenddoc` to append docstrings to the docstring of another
+    object, usually the constructor of the superclass
+  - API: new Sphinx callback class :class:`.ResolveTypeVariables` to resolve type
+    variables in attribute signatures
+
+- :mod:`pytools.text`: new class :class:`.TextTemplate` to generate text from a template
+  string with stricter management of template variables
+
+- :mod:`pytools.typing`: new module for generic type inspection at runtime
+
+  - new function :func:`.get_common_generic_base` to retrieve the common generic base
+    class of two types
+  - new function :func:`.get_common_generic_subclass` to retrieve the common generic
+    subclass of two types
+  - new function :func:`.get_generic_bases` to retrieve the generic base classes of a
+    type
+  - new function :func:`.get_generic_instance` to retrieve the generic instance of a
+    type
+  - new function :func:`.get_type_arguments` to retrieve the type arguments of a generic
+    type
+  - new function :func:`.isinstance_generic` to check if an object is an instance of a
+    generic type
+  - new function :func:`.issubclass_generic` to check if a type is a subclass of a
+    generic type
+
+- :mod:`pytools.viz`:
+    - API: new function :func:`.is_running_in_notebook` to check if the code is running
+      in a Jupyter or Colab notebook
+    - API: new property :attr:`.hex` for :class:`.RgbColor` and :class:`.RgbaColor` to
+      return the color as a hexadecimal string
+
+- Various adjustments to maintain compatibility with recent Python versions
+
+
 *pytools* 2.1
 -------------
 

azure-pipelines.yml

@@ -1,9 +1,9 @@
 trigger:
-  - 2.1.x
+  - 3.0.x
   - release/*
 
 pr:
-  - 2.1.x
+  - 3.0.x
   - release/*
 
 pool:
@@ -26,7 +26,7 @@ resources:
       type: github
       endpoint: BCG-X-Official
       name: BCG-X-Official/pytools
-      ref: 2.1.x
+      ref: 3.0.x
 
 variables:
   ${{ if not(startsWith(variables['Build.SourceBranch'], 'refs/pull/')) }}:
@@ -51,8 +51,8 @@ stages:
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
           - script: |
               python -m pip install isort~=5.12
               python -m isort --check --diff .
@@ -62,32 +62,32 @@ stages:
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
           - script: |
-              python -m pip install black~=23.10.1
+              python -m pip install black~=24.4.2
               python -m black --check .
             displayName: 'Run black'
       - job:
         displayName: 'flake8'
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
           - script: |
-              python -m pip install flake8~=5.0 flake8-comprehensions~=3.10
+              python -m pip install flake8~=7.0 flake8-comprehensions~=3.10
               python -m flake8 --config tox.ini -v .
             displayName: 'Run flake8'
       - job:
         displayName: 'mypy'
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
           - script: |
-              python -m pip install mypy~=1.2.0 numpy~=1.24
+              python -m pip install mypy~=1.10.0 numpy~=1.24
               python -m mypy src
             displayName: 'Run mypy'
 
@@ -144,8 +144,8 @@ stages:
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
 
           - checkout: self
 
@@ -184,7 +184,7 @@ stages:
               searchFolder: '$(System.DefaultWorkingDirectory)/'
               testRunTitle: 'Publish test results'
 
-          - task: PublishCodeCoverageResults@1
+          - task: PublishCodeCoverageResults@2
             inputs:
               codeCoverageTool: Cobertura
               summaryFileLocation: '$(System.DefaultWorkingDirectory)/coverage.xml'
@@ -219,15 +219,15 @@ stages:
             # This comprises only one minimum dependencies test for tox,
             # which is usually faster than conda.
             maximum_dependencies_conda:
-              FACET_V_PYTHON_BUILD: '=3.9'
+              FACET_V_PYTHON_BUILD: '=3.12'
               BUILD_SYSTEM: 'conda'
               PKG_DEPENDENCIES: 'max'
             minimum_dependencies_tox:
-              FACET_V_PYTHON_BUILD: '=3.7'
+              FACET_V_PYTHON_BUILD: '=3.11'
               BUILD_SYSTEM: 'tox'
               PKG_DEPENDENCIES: 'min'
             maximum_dependencies_tox:
-              FACET_V_PYTHON_BUILD: '=3.9'
+              FACET_V_PYTHON_BUILD: '=3.12'
               BUILD_SYSTEM: 'tox'
               PKG_DEPENDENCIES: 'max'
 
@@ -305,27 +305,27 @@ stages:
         strategy:
           matrix:
             default_dependencies_conda:
-              FACET_V_PYTHON_BUILD: '=3.8'
+              FACET_V_PYTHON_BUILD: '=3.11'
               BUILD_SYSTEM: 'conda'
               PKG_DEPENDENCIES: 'default'
             minimum_dependencies_conda:
-              FACET_V_PYTHON_BUILD: '=3.7'
+              FACET_V_PYTHON_BUILD: '=3.11'
               BUILD_SYSTEM: 'conda'
               PKG_DEPENDENCIES: 'min'
             maximum_dependencies_conda:
-              FACET_V_PYTHON_BUILD: '=3.9'
+              FACET_V_PYTHON_BUILD: '=3.12'
               BUILD_SYSTEM: 'conda'
               PKG_DEPENDENCIES: 'max'
             default_dependencies_tox:
-              FACET_V_PYTHON_BUILD: '=3.8'
+              FACET_V_PYTHON_BUILD: '=3.11'
               BUILD_SYSTEM: 'tox'
               PKG_DEPENDENCIES: 'default'
             minimum_dependencies_tox:
-              FACET_V_PYTHON_BUILD: '=3.7'
+              FACET_V_PYTHON_BUILD: '=3.11'
               BUILD_SYSTEM: 'tox'
               PKG_DEPENDENCIES: 'min'
             maximum_dependencies_tox:
-              FACET_V_PYTHON_BUILD: '=3.9'
+              FACET_V_PYTHON_BUILD: '=3.12'
               BUILD_SYSTEM: 'tox'
               PKG_DEPENDENCIES: 'max'
 
@@ -441,8 +441,8 @@ stages:
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
 
           - checkout: pytools
           - checkout: self
@@ -506,8 +506,8 @@ stages:
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
 
           - checkout: pytools
           - checkout: self
@@ -633,8 +633,8 @@ stages:
         steps:
           - task: UsePythonVersion@0
             inputs:
-              versionSpec: '3.9'
-            displayName: 'use Python 3.9'
+              versionSpec: '3.11'
+            displayName: 'use Python 3.11'
 
           - task: InstallSSHKey@0
             inputs:

environment.yml

@@ -8,7 +8,7 @@ dependencies:
   - matplotlib        ~= 3.7
   - numpy             ~= 1.24
   - pandas            ~= 2.0
-  - python            ~= 3.9
+  - python            ~= 3.10
   - scipy             ~= 1.10
   - typing_extensions ~= 4.3
   - typing_inspect    ~= 0.7

make.py

@@ -29,7 +29,7 @@
     os.path.normpath(os.path.join(SCRIPT_DIR, "sphinx", "base")),
 )
 # noinspection PyUnresolvedReferences
-from make_util import get_package_version
+from make_util import get_package_version  # noqa: E402
 
 FACET_PATH_ENV = "FACET_PATH"
 FACET_PATH_URI_ENV = "FACET_PATH_URI"
@@ -92,9 +92,9 @@ def __init__(self, project: str, dependency_type: str) -> None:
 
         # add the project roots path to the environment as a URI
 
-        os.environ[
-            FACET_PATH_URI_ENV
-        ] = f"file://{request.pathname2url(projects_root_path)}"
+        os.environ[FACET_PATH_URI_ENV] = (
+            f"file://{request.pathname2url(projects_root_path)}"
+        )
 
         # determine the package version of the project
 
@@ -103,9 +103,9 @@ def __init__(self, project: str, dependency_type: str) -> None:
 
         package_version = str(get_package_version(package_path=src_root_path))
 
-        os.environ[
-            FACET_BUILD_PKG_VERSION_ENV.format(project=project.upper())
-        ] = package_version
+        os.environ[FACET_BUILD_PKG_VERSION_ENV.format(project=project.upper())] = (
+            package_version
+        )
 
         self.package_version = package_version
         self.pyproject_toml = None