Release Notes

pytools 3.0

pytools 3.0 adds support for language features introduced up to and including Python 3.10, and drops support for Python versions.

pytools 3.0.2

• BUILD: numpy 2 is now supported

• FIX: issubclass_generic() now supports unions, tuples of types, and None, and uses clearer error messages if called with invalid arguments

pytools 3.0.1

• BUILD: add support for Python 3.10

pytools 3.0.0

• 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 get_init_params() to retrieve the object attributes associated with the object’s __init__ method

  • API: new metaclass MissingClassMeta to define a stand-in class for a missing class that could not be imported from an optional dependency

  • API: new function missing_function() to define a stand-in function for a missing function that could not be imported from an optional dependency

  • API: new function validate__all__declarations() to validate the __all__ declarations of a module and its submodules

• pytools.asyncio: new module with utility functions for asynchronous programming

  • arun() to run an asynchronous function in a new event loop

  • aenumerate() to enumerate an asynchronous iterable

  • async_flatten() to flatten nested asynchronous iterables for optimized asynchronous processing

  • iter_async_to_sync() to convert an asynchronous iterable to a synchronous one

  • iter_sync_to_async() to convert a synchronous iterable to an asynchronous one

  • unpack_exception_group() to unpack an exception group into one or more individual exceptions

• pytools.data.taxonomy: new submodule with classes Taxonomy and Category to represent hierarchical taxonomies

• pytools.expression:

  • new function expression_from_init_params() to create an object’s Expression representation from the attributes in its __init__ method

  • new submodule pytools.expression.repr with enhanced versions of standard Python container classes implementing the HasExpressionRepr interface:

    • ListWithExpressionRepr for lists

    • TupleWithExpressionRepr for tuples

    • SetWithExpressionRepr for sets

    • DictWithExpressionRepr for dictionaries

• pytools.http: new module with function fetch_url() to download a file from a URL

• pytools.repr: new module with mixin class HasDictRepr, providing a method to return a dictionary representation of an object

• pytools.sphinx: new utilities for generating Sphinx documentation

  • API: new decorator apenddoc to append docstrings to the docstring of another object, usually the constructor of the superclass

  • API: new Sphinx callback class ResolveTypeVariables to resolve type variables in attribute signatures

• pytools.text: new class TextTemplate to generate text from a template string with stricter management of template variables

• pytools.typing: new module for generic type inspection at runtime

  • new function get_common_generic_base() to retrieve the common generic base class of two types

  • new function get_common_generic_subclass() to retrieve the common generic subclass of two types

  • new function get_generic_bases() to retrieve the generic base classes of a type

  • new function get_generic_instance() to retrieve the generic instance of a type

  • new function get_type_arguments() to retrieve the type arguments of a generic type

  • new function isinstance_generic() to check if an object is an instance of a generic type

  • new function issubclass_generic() to check if a type is a subclass of a generic type

• pytools.viz:

  • API: new class HTMLStyle for rendering HTML content with drawers

  • API: new function is_running_in_notebook() to check if the code is running in a Jupyter or Colab notebook

  • API: new property RgbColor.hex and RgbaColor.hex to return the color as a hexadecimal string

• Various adjustments to maintain compatibility with recent Python versions

pytools 2.1

2.1.3

• FIX: DendrogramMatplotStyle now calls Axis.set_ticklabels() using a positional argument for the labels, to address a change in matplotlib 3.7

2.1.2

This is a maintenance release to catch up with pytools 2.0.7.

2.1.1

• API: AllTracker now resolves forward references in type aliases exported via __all__

2.1.0

• API: new decorator fitted_only to mark methods that may only be called after their associated object has been fitted using FittableMixin.fit()

• API: remove method ensure_fitted from FittableMixin, which is no longer needed due to the new decorator fitted_only.

• API: new Sphinx callback TrackCurrentClass to keep track of the current class being processed by autodoc.

• API: new Sphinx callback RenamePrivateArguments to rename private “positional-only” arguments in a function’s signature (with two leading underscores) back to their original names in the source code, so that autodoc can pick them up correctly.

• API: Expression objects support plain text and HTML output in Jupyter notebooks

pytools 2.0

pytools 2 introduces enhanced visualisations along with additional API improvements, and is now subject to static type checking with mypy.

2.0.7

• FIX: prevent matplot warnings about missing fonts when rendering drawers using the MatplotStyle

2.0.6

• BUILD: add support for pandas 2.0 and above

2.0.5

• API: de-dent docstrings before processing them with the subsdoc decorator

• FIX: in method AllTracker.resolve_forward_references(), unwrap functions before accessing their __globals__ attribute

2.0.4

• FIX: make MatplotStyle.get_renderer() compatible with matplotlib 3.6

2.0.3

• REFACTOR: rename arg of FittableMixin.fit() to __x, so that mypy recognizes it as a positional-only argument, and that subclasses can change its name without breaking the API

• FIX: make ResolveTypeVariables compatible with Python 3.9

• FIX: recognise private (positional-only) arguments in DocValidator

• DOC: show original names of private (positional-only) arguments in Sphinx documentation, not their substituted private names generated by Python

2.0.2

• REFACTOR: run mypy type checks in strict mode

• FIX: more reliably determine the class when resolving type variables for Sphinx API documentation

• FIX: no longer raise an exception when attempting to get the class name for Union and other “special” types

2.0.1

• FIX: in class AllTracker, do not attempt to update forward references in imported objects

• BUILD: update build scripts to support the stricter dependency resolver introduced by pip 20.3, and to fix a compatibility issue with recent updates to nbsphinx

• BUILD: enable local sphinx builds in other FACET packages

• DOC: simplify how the docs build manages existing documentation of previous versions in the Azure pipeline and the associated commands in make.py: under the new approach, documentation is only preserved for the latest patch of each minor version, reducing the amount of near-similar documentation

• DOC: use pydata sphinx theme v0.9 (but disable dark mode)

2.0.0

pytools.api

• API: collection validation/conversion functions to_set(), to_tuple(), to_list(), and to_collection() have a new argument optional

• API: decorator subsdoc() has a new optional argument using, indicating an object whose docstring will be used as the basis for creating the substituted docstring of the decorated object

pytools.data

• API: new class Matrix allows MatrixDrawer to render flexible row and column widths, based on the Matrix.weights property, and supports axis labels for the row, column, and weight axes

• API: moved class LinkageTree to module pytools.data

pytools.expression

• API: improved conversion of numpy arrays to Expression objects in function make_expression()

• API: removed method get_class_id from class HasExpressionRepr

pytools.fit

• API: method FittableMixin.ensure_fitted() is now public, replacing the formerly private method _ensure_fitted()

pytools.meta

• API: removed function compose_meta due to conflicts with mypy static type checks

• API: new metaclass SingletonABCMeta combining SingletonMeta and ABCMeta

pytools.parallelization

• API: method JobRunner.run_jobs() now expects a single iterable of Job objects instead of individual jobs as positional arguments

• API: method JobRunner.run_queues() now expects a single iterable of JobQueue objects instead of individual queues as positional arguments, and returns a list of results instead of an iterator

• API: methods JobRunner.run_queue() and JobRunner.run_queues() are now thread-safe

• API: renamed method collate of class JobQueue to JobQueue.aggregate()

• API: SimpleQueue is now an abstract class, expecting subclasses to implement method SimpleQueue.aggregate()

• API: renamed class NestedQueue to CompositeQueue

pytools.sphinx

• API: new Sphinx callback class ObjectDescriptionTransform

• API: renamed callback class ResolveGenericClassParameters to ResolveTypeVariables and updated to resolve type variables also in attribute signatures

pytools.text

• API: new function camel_case_to_snake_case()

pytools.viz

Additions and enhancements to dendrogram and matrix visualizations.

• Dendrograms: major design overhaul

  • API: replaced the heatmap and line dendrogram styles with a single, freshly designed DendrogramMatplotStyle offering a tighter layout and using the thickness of the dendrogram’s branches to indicate the cumulative weight of the leaf nodes

  • API: DendrogramMatplotStyle.padding determines the adjustable padding between neighbouring branches; setting padding to zero produces a chart similar to the previous heatmap style

  • API: DendrogramDrawer no longer sorts leaf nodes as part of the drawing process; the sorting mechanism is now available via method LinkageTree.sort_by_weight()

  • VIZ: DendrogramMatplotStyle and DendrogramReportStyle now render leaves in left-to-right order, instead of the previous right-to-left order

  • API: the DendrogramReportStyle now reduces the label section of the dendrogram to the length of the longest label; renamed the label_width property to max_label_width

  • API: moved class LinkageTree to module pytools.data

  • API: new method LinkageTree.iter_nodes() for depth-first traversal of the linkage tree

• Matrices: major design overhaul

  • API: class MatrixDrawer now expects instances of new class Matrix as its input

  • API: MatrixDrawer no longer accepts DataFrame objects, but Matrix.from_frame() can be used to convert data frames to matrix objects

  • API: new attribute MatrixMatplotStyle.nan_substitute specifies the value to look up in the colormap to determine the color of undefined matrix cells

  • VIZ: MatrixMatplotStyle enforces a 1:1 aspect ratio for the row and column axes, so that equal row and column widths represent equal weights

• API: new public method Drawer.get_style_kwargs(), replacing the previously private method _get_style_kwargs()

• API: implement RgbColor and RgbaColor as classes instead of type aliases

• API: removed method dark() from class ColoredStyle and instead introduce constants ColorScheme.DEFAULT, ColorScheme.DEFAULT_LIGHT, and ColorScheme.DEFAULT_DARK

pytools 1.2

1.2.5

This is a maintenance release to catch up with pytools 1.1.10.

1.2.4

This is a maintenance release to catch up with pytools 1.1.8.

1.2.3

This release enhances support for generating Sphinx documentation, and catches up with pytools 1.1.7.

• API: add sphinx processor ResolveGenericClassParameters to substitute generic type parameters introduced by base classes or via the self and cls special method arguments

• API: add sphinx processor AutodocProcessBases to handle autodoc-process-bases events (introduced in Sphinx 4.1)

• API: function validate_type() now accepts multiple alternative types to validate values against, in line with how isinstance() tests for multiple types

1.2.2

This is a maintenance release to catch up with pytools 1.1.5.

1.2.1

This is a maintenance release to catch up with pytools 1.1.4.

1.2.0

• API: new function to_collection() preserves any type of collection, and converts iterators into tuple instances

• API: functions to_set(), to_list(), to_tuple(), to_collection(), and validate_element_types() now accept multiple alternative types to validate elements against, in line with how isinstance() tests for multiple types

• BUILD: add support for matplotlib ~= 3.0, scipy ~= 1.6, and typing-inspect ~= 0.7

pytools 1.1

1.1.10

This release addresses additional issues in the release process, focusing on the make_base.py script for Sphinx builds used across gamma-pytools, sklearndf, and gamma-facet.

1.1.9

This is a bugfix release to restore the GitHub release process.

1.1.8

• BUILD: the make_base.py build script no longer imports the actual module to obtain the current package version, similarly as introduced for make.py in pytools 1.1.7

1.1.7

• BUILD: update the make.py build script to remove its reliance on importing the actual module just to obtain the build version; instead, make.py now scans the top-level __init__.py file for a __version__ declaration

1.1.6

• VIZ: set colors of axis labels to the foreground color of the current color scheme

• FIX: ensure correct weight labels when rendering dendrograms as plain text using the DendrogramReportStyle

• FIX: calling method get_class_id of class Id could cause a TypeError

• FIX: Replace3rdPartyDoc sphinx callback now substitutes 3rd-party docstrings also for property definitions

1.1.5

• FIX: fixed a rare case where Expression.eq_() returned False for two equivalent expressions if one of them included an ExpressionAlias

• FIX: accept any type of numerical values as leaf weights of LinkageTree

1.1.4

• BUILD: add support for joblib 1.0.*

1.1.3

• FIX: comparing two InfixExpression objects using method Expression.eq_() would erroneously yield True if both expressions had the same operator but a different number of operands, and the operands of the shorter expression were equal to the operands at the start of the longer expression

1.1.2

• Catch up with fixes and pipeline updates introduced by pytools 1.0.3 and 1.0.4

• API: support inheriting class docstrings from superclasses using the inheritdoc() decorator

• API: new subsdoc() decorator to replace text in docstrings

• API: use background color for matrix grid in MatrixMatplotStyle

1.1.1

• API: MatplotStyle now uses PyPlot’s current axes by default, instead of creating a new figure and axis

1.1.0

• API: JobRunner provides a new object-oriented interface to joblib, running instances of Job and JobQueue in parallel

• API: AllTracker detects and prohibits exporting objects imported from other modules

• API: AllTracker detects and prohibits exporting global constants (the preferred approach is to define constants inside classes as this provides better context, and will be properly documented via Sphinx)

pytools 1.0

1.0.6

• FIX: back-port pytools 1.1 bugfix for Expression.eq_()

1.0.5

• FIX: back-port pytools 1.1 bugfix for building multi-version documentation

1.0.4

• FIX: do not substitute ~= by ~== when adapting version syntax for tox

1.0.3

This is a maintenance release focusing on enhancements to the CI/CD pipeline, along with minor fixes.

• BUILD: add the bcg_gamma conda channel when building

• BUILD: Enforce pre-release for minor and major releases

• DOC: add pre-commit hook instructions to contribution guide

• BUILD: update flake8 to 3.9.0

• BUILD: apply make_base.py changes from 1.1.x also on develop (adds more robust parsing of package versions)

• FIX: version syntax adaptation with mixed = and >=

1.0.2

This is a maintenance release focusing on enhancements to the CI/CD pipeline, along with minor fixes.

• API: sort list of items returned by AllTracker.get_tracked()

• API: add protected method to class MatplotStyle to apply color scheme to Axes object

• FIX: preserve correct instance for subclasses of singleton classes

• FIX: add a few missing type hints

• BUILD: add support for numpy 1.20

• BUILD: updates and changes to the CI/CD pipeline

1.0.1

Initial release.

previous

FAQ