DEV Community: Chad Dombrova

Using Spack to build the VFX Refence Platform

Chad Dombrova — Wed, 30 Aug 2023 03:47:49 +0000

Exploring Spack as an alternative to Rez for VFX and Animation

If you are a software developer in the VFX/Animation industry then chances are you've heard of Rez. Rez is widely used to manage complex software builds and environments, and it was recently added to the Academy Software Foundation.

I first discovered Rez in 2013 while looking for a replacement for Luma's in-house environment management tool. Over the following two years I worked with the author and other contributors on the Rez 2.0 rewrite. When colleagues asked me why we couldn't use tool X instead of Rez, my answer was that our industry is unique. Only we are required to build, deploy, and simultaneously utilize such a multitude of libraries and versions. The ultimate badge of our special status is that this "dependency hell" became so intractable that software vendors and studio leaders united to establish the VFX Reference Platform in order to reduce the build surface area.

In my experience, a software development team in our industry needs a tool that meets at least these requirements:

manage builds of numerous software packages, each using its own build tools, such as cmake, autoconf, scons, etc
specify variations for package builds, allowing definition of build matrices
resolve transitive dependencies from a loose set of version range requirements
load environment variables associated with released packages into a shell environment
ability to build behind a firewall, without direct internet access

Unbeknownst to me, while we were making Rez, a different community made a tool that addresses these core requirements and eclipses Rez in many ways.

That tool is Spack, built by the supercomputing and scientific computing community. This is a serious tool, backed by (as you might expect) some sophisticated engineering, with a robust layered configuration suitable for small and large organizations.

In this article I track what I've learned while building the VFX Reference Platform using Spack.

Comparison to Rez

Before we dive in, here's a mile-high overview of the two projects.

Popularity

The first thing that stands out about Spack is that its user base is many times larger than Rez, if we use Github stars and forks as a metric.

Project health

Next up, according to www.repocheck.com, Spack is a healthier project, with far more closed PRs and issues, and a healthier ratio of opened to closed.

In the last month Rez saw 2 completed PRs while Spack had a whopping 472.

Features

After reading through the docs and experimenting a bit, I found that Spack has solutions to many of my complaints with Rez.

With Spack you can...

Build a package and all of its dependencies with a single command.
Use package repos to share build recipes, akin to Homebrew on Mac. Imagine a repo that's curated and tested by the ASWF that can be used by the entire industry.
Simplify working in air-gapped environments by creating local mirrors of source code tarballs
Automatically generate CI pipelines that will create a dependency graph of CI jobs to build each package in parallel.
Host caches of binary builds for easy distribution without recompilation.
Generate an optimized docker container with your compiled binaries.

Rez to Spack cheat sheet

Rez	Spack	Notes
package	package	package.py in Spack is responsible for build recipe and environment
request	spec	see below for a comparison of version specifiers
variant	variant	variants in Spack are explicitly named and can encompass multiple dependencies
resolve a request	concretize a spec	concretization can run in multiple processes
`rez env`	`spack load`	update a shell env with specified packages

Diving in

Ok, time to get our hands dirty.

The Goal: Build as much of the VFX Reference Platform as possible using Spack.

📘 Note

If you're following along at home, I'm using a custom fork of Spack that fixes a few package recipes and adds some new capabilities (see "Managing environment variables", below). You can see all of the changes here.

Also, the steps in this article are compiled into some reproducible shell scripts in this repo:
chadrik / spack-vfx-demo

Companion scripts for the article "Using Spack to build the VFX Reference Platform"
Build the VFX Reference Platform using Spack
git clone https://github.com/chadrik/spack-vfx-demo
cd spack-vfx-demo
./demo.sh
View on GitHub

I chose to use docker so that my tests would be completely reproducible. I love that I can use docker, and what's more there's a spack/centos7 image. This is already feeling more modern than Rez.

I'm mounting a local directory as a volume in order to reuse builds across docker invocations, and to avoid maxing out the docker disk limit.

mkdir ./spack-builds
git clone https://github.com/chadrik/spack --branch vfx-demo
docker run -it --rm \
  -v $(pwd)/spack-builds:/opt/spack/opt/spack/ \
  -v $(pwd)/spack/lib:/opt/spack/lib \
  -v $(pwd)/spack/var/spack:/opt/spack/var/spack \
spack/centos7:v0.19.0

Now that we're in the container, let's see if we can locate the OpenEXR package:

$ spack list exr
fakexrandr  openexr  py-annexremote
==> 3 packages

More info:

$ spack info openexr
CMakePackage:   openexr

Description:
    OpenEXR Graphics Tools (high dynamic-range image file format)

Homepage: https://www.openexr.com/

Preferred version:  
    3.1.5     https://github.com/AcademySoftwareFoundation/openexr/archive/refs/tags/v3.1.5.tar.gz

Safe versions:  
    3.1.5     https://github.com/AcademySoftwareFoundation/openexr/archive/refs/tags/v3.1.5.tar.gz
    2.3.0     https://github.com/AcademySoftwareFoundation/openexr/releases/download/v2.3.0/openexr-2.3.0.tar.gz
    2.2.0     http://download.savannah.nongnu.org/releases/openexr/openexr-2.2.0.tar.gz
    2.1.0     http://download.savannah.nongnu.org/releases/openexr/openexr-2.1.0.tar.gz
    2.0.1     http://download.savannah.nongnu.org/releases/openexr/openexr-2.0.1.tar.gz
    1.7.0     http://download.savannah.nongnu.org/releases/openexr/openexr-1.7.0.tar.gz
    1.6.1     http://download.savannah.nongnu.org/releases/openexr/openexr-1.6.1.tar.gz
    1.5.0     http://download.savannah.nongnu.org/releases/openexr/openexr-1.5.0.tar.gz
    1.4.0a    http://download.savannah.nongnu.org/releases/openexr/openexr-1.4.0a.tar.gz
    1.3.2     http://download.savannah.nongnu.org/releases/openexr/openexr-1.3.2.tar.gz

With this configuration, the latest version of openexr available in Spack is 3.1.5, but there are a number of earlier versions available as well.

A quick test of version specs

As with Rez, Spack can resolve loose version requirements into specific set of package versions and their dependencies.

In Spack terms, this is called "concretizing a spec".

Below is a quick test of a few version specifiers. All of these found openexr 3.1.5:

spack spec openexr@3.1      # >= 3.1.0
spack spec openexr@3:4      # >= 3.0.0, < 5
spack spec openexr@3:3.1    # >= 3.0.0, < 3.2

And as expected, the command below did not find openexr 3.1.5:

spack spec openexr@3:3.1.0  # >= 3.0.0, < 3.1.0

This demonstrates two things:

upper bounds are inclusive. i.e. <=
omitted sub-versions float to the highest value when used as an upper bound, and lowest versions when used as a lower bound

If you need a quick refresher while you're at the console, you can run spack help --spec.

Setting up the compiler

Before we do a build we need to install gcc 9.3.1, since this is the version required by VFX Reference Platform CY2021 and CY2022 and it's not in the container.

yum install -y centos-release-scl && yum install -y devtoolset-9
spack compiler find /opt/rh/devtoolset-9/root/usr/bin/

Alternatively, you can build your own gcc:

spack install gcc@9.3.1

📘 Note

The above gcc installation instructions need to be repeated each time the container is started, unless you make a new container with that step baked in. This is because anything installed into the docker file system is ephemeral, and will not be persisted between invocations.

Building OpenImageIO

As a way to test a complex build with numerous dependencies, I chose to tackle OpenImageIO.

First, we'll inspect the full list of packages required to build OpenImageIO, with dependencies locked down versions that are compatible with the VFX Reference Platform:

spack spec openimageio +python ^openexr@3.1 ^python@3.9 ^py-numpy@1.20 ^boost@1.76

Some details:

+python: enables the variant of openimageio which will build the python bindings
^: requested dependency versions. I want to lock down the dependencies to match those in CY2022.

For reference, the package.py file for openimageio looks like this:


from spack.package import *
from spack.pkg.builtin.boost import Boost


class Openimageio(CMakePackage):
    """OpenImageIO is a library for reading and writing images, and a bunch of
    related classes, utilities, and applications."""

    homepage = "https://www.openimageio.org"
    url = "https://github.com/OpenImageIO/oiio/archive/refs/tags/v1.8.15.tar.gz"

    version("2.4.8.0", sha256="e8402851970d48c718917060fa79bb7d75a050316556337cd0d4f0d0f971c904")
    version("2.2.7.0", sha256="857ac83798d6d2bda5d4d11a90618ff19486da2e5a4c4ff022c5976b5746fe8c")
    version("1.8.15", sha256="4d5b4ed3f2daaed69989f53c0f9364dd87c82dc0a09807b5b6e9008e2426e86f")

    # Core dependencies
    depends_on("cmake@3.2.2:", type="build")
    depends_on("boost@1.53:", type=("build", "link"))

    # TODO: replace this with an explicit list of components of Boost,
    # for instance depends_on('boost +filesystem')
    # See https://github.com/spack/spack/pull/22303 for reference
    depends_on(Boost.with_default_variants, type=("build", "link"))
    depends_on("libtiff@4.0:", type=("build", "link"))
    depends_on("openexr@2.3:", type=("build", "link"))
    depends_on("libpng@1.6:", type=("build", "link"))
    depends_on("libjpeg", type=("build", "link"))

    # Optional dependencies
    variant("ffmpeg", default=False, description="Support video frames")
    depends_on("ffmpeg@3.0:", when="+ffmpeg")

    variant("jpeg2k", default=False, description="Support for JPEG2000 format")
    depends_on("openjpeg@2.0:", when="+jpeg2k")

    variant("python", default=False, description="Build python bindings")
    extends("python", when="+python")
    depends_on("py-numpy", when="+python", type=("build", "run"))
    depends_on("py-pybind11", when="+python", type=("build", "run"))

    variant("qt", default=False, description="Build qt viewer")
    depends_on("qt@5.6.0:+opengl", when="+qt")

    conflicts("target=aarch64:", when="@:1.8.15")

    def cmake_args(self):
        args = ["-DUSE_FFMPEG={0}".format("ON" if "+ffmpeg" in self.spec else "OFF")]
        args += ["-DUSE_OPENJPEG={0}".format("ON" if "+jpeg2k" in self.spec else "OFF")]
        args += ["-DUSE_PYTHON={0}".format("ON" if "+python" in self.spec else "OFF")]
        args += ["-DUSE_QT={0}".format("ON" if "+qt" in self.spec else "OFF")]
        if "+python" in self.spec:
            args += ["-DPYTHON_VERSION={0}".format(self.spec["python"].version)]
        args += ["-Wno-deprecated-declarations"]
        return args

To build, just replace spack spec with spack install:

spack install openimageio +python ^openexr@3.1 ^python@3.9 ^py-numpy@1.20 ^boost@1.76

Drumroll.......

and.... it failed installing ncurses.

External packages

After some experimentation, it appears this error occurs with all versions of ncurses in Spack when using gcc 9.3.1, but not gcc 4.8.5.

As a quick way around this problem, I decided to install ncurses via yum.

Spack is designed to build just about everything from scratch by default -- including many libraries that would typically be installed by a package manager like yum or apt (this is because Spack is itself a package manager). However, there is a way to register "external" packages that are not managed by Spack's repository of package build recipes.

First, we start by installing ncurses:

yum install -y ncurses-devel

Next, run the following:

$ spack external find
==> The following specs have been detected on this system and added to /root/.spack/packages.yaml
autoconf@2.69    binutils@2.27.44  coreutils@8.22  diffutils@3.3     flex@2.5.37  git@1.8.3.1  groff@1.22.2   m4@1.4.16      pkg-config@0.27.1  swig@2.0.10  texinfo@5.1
automake@1.13.4  bison@3.0.4       curl@7.29.0     findutils@4.5.11  gawk@4.0.2   gmake@3.82   libtool@2.4.2  openssh@7.4p1  subversion@1.7.14  tar@1.26

This finds a bunch of libraries, but the output shows that ncurses is not among them. The docs say that special handling must be added for external packages to be found, so for now we can add it manually:

vi ~/.spack/packages.yaml

Then we add the following to the bottom of the file:

  ncurses:
    externals:
    - spec: ncurses@5.9.14+termlib
      prefix: /usr

📘 Note

When you register an external package, you are telling Spack that it is a drop-in replacement for the same package built by Spack. This means if it's a library the external package should include headers, which often means you need to install a "devel" package.

Of the external packages that were found, there is one devel package we need to install:

yum install -y binutils-devel

Ok, let's try installing again:

spack install openimageio +python ^openexr@3.1 ^python@3.9 ^py-numpy@1.20 ^boost@1.76

Success!

After a little setup and trial and error, we just built a quarter of the VFX Reference Platform with one command.

Building the VFX Reference Platform

Now let's see if we can do even more. Rather than create an ad hoc build as before, we will create a Spack "environment", which is like a python virtualenv.

First, activate shell support:

. /opt/spack/share/spack/setup-env.sh

Then create and activate the environment:

spack env create vfx2022
spack env activate -p vfx2022

Next we use spack add to add each of the packages to build.

Below are the VFX Reference Platform 2022 libraries that I could find that have matching versions in Spack (though openvdb is out of date). Incredibly, there are only 4 libraries missing from the builtin Spack repo: Aces, Ptex, FBX, and OpenColorIO.

spack add openimageio +python
spack add openexr@3.1
spack add python@3.9
spack add py-numpy@1.20
spack add boost@1.76
spack add qt@5.15 +webkit
spack add intel-tbb@2020.3
spack add intel-mkl@2020
spack add opensubdiv@3.4
spack add alembic@1.8
spack add openvdb@8

As before, we can use abstract specs when defining our environment, which will be "concretized" into specific versions and variants.

Let's take a quick pitstop to see how the environment is managed:

cat /opt/spack/var/spack/environments/vfx2022/spack.yaml

# This is a Spack Environment file.
#
# It describes a set of packages to be installed, along with
# configuration settings.
spack:
  # add package specs to the `specs` list
  specs: [openimageio+python, openexr@3.1, python@3.9, py-numpy@1.20, boost@1.76,
    qt@5.15+webkit, intel-tbb@2020.3, intel-mkl@2020, opensubdiv@3.4, alembic@1.7,
    openvdb@8]
  view: true
  concretizer:
    unify: true

To concretize our specs within a Spack environment we use spack concretize, and the result will be cached as long as the inputs in spack.yaml don't change.

Here's the result of concretization:

[vfx2022] [root@96edee2040aa ~]# spack concretize
==> Error: No version for 'python' satisfies '@2.7.18' and '@3.9.8'. Consider setting `concretizer:unify` to `when_possible` or `false` to relax the concretizer strictness.

The error indicates one of the new packages added since building openimagio is hardwired to use python@2.7.18. There's no obvious workflow for conflict resolution. Score one point for Rez, with its handy (but often overwhelming!) conflict resolutions graphs.

After some trial and error I discovered that the problem is qt. Looking at the qt package.py there's a note that webkit requires python2 for building, so I'll remove that variant for now.

spack rm qt
spack add qt@5.15  # add without +webkit

Before we concretize there's one more external dependency to setup to avoid a build problem triggered by qt's deps:

yum install -y harfbuzz-devel
echo -e "  harfbuzz:\n    externals:\n    - spec: harfbuzz@1.7.5\n      prefix: /usr" >> ~/.spack/packages.yaml
spack add harfbuzz@1.7.5

Then we re-concretize:

spack concretize

Here's the output from just the openimageio portion:

Spack installs the built packages into a centralized location, so all of the packages that were already installed during the build of openimageio are skipped this time around. Previously installed packages are prefixed with [+] while those which still need to be built have [-].

📘 Note

Spack generates a hash for each spec. This hash is a function of the full provenance of the package, so any change to the spec affects the hash. Spack uses this value to compare specs and to generate unique installation directories for every combinatorial version.

In the output above we can see that ^py-numpy@1.20.3 needs to be rebuilt. This is because in the vfx2022 environment I added a new requirement that was omitted when I built openimagio the first time: intel-mkl@2020. Since py-numpy depends on this package, a new variant of py-numpy with this altered dependency needs to be built.

Time to build all the packages that have been added to the environment:

spack install

We just built most of the VFX Reference Platform!

Managing environment variables

One of the most useful features of Rez is its ability to take a set of loose package versions and create a new shell with environment variables that are composed from the resolved packages. For example, rez env maya-2020 bifrost would set MAYA_LOCATION and PATH to load this verson of Maya and ensure that the Bifrost plugin is on the MAYA_MODULE_PATH.

Spack does not have this exact feature, but it has the building blocks to implement it. The spack load command is able to load the environment variables of explicitly provided packages, but unlike Rez or spack spec it does not accept abstract specs -- you must know exactly what you want loaded.

I forked Spack to see how hard it would be to make this work more like rez env, and it was pretty approachable. I needed to add a few simple features to existing commands:

Add spack load --concretize to treat the list of input specs as abstract specs to concretize.
Add a concretization mode that only considers installed (i.e. built) packages, and errors if it cannot resolve successfully.
Add spack load --deptype to control which dependency types are loaded: we only want "run" deps, so that we skip build-only dependencies.

You can see all of these changes in this PR.

With those fixes in place, here's the workflow:

Deactivate the vfx2022 environment and make sure there are no packages currently loaded:

[vfx2022] [root@661cfada1db4 ~]# spack env deactivate
[root@661cfada1db4 ~]# spack find --loaded
==> 0 loaded packages

Now load the runtime dependencies of openimagio into the current environment:

[root@661cfada1db4 ~]# spack load --deptype run --concretize openimageio

Let's confirm that we've loaded openimageio and its runtime dependencies:

[root@661cfada1db4 ~]# yum install -y which
[root@661cfada1db4 ~]# which oiiotool
/opt/spack/opt/spack/linux-centos7-x86_64/gcc-9.3.1/openimageio-2.4.8.0-rdvmyrbos6q6om6apzqvunbnx5h6egv7/bin/oiiotool
[root@661cfada1db4 ~]# spack find --loaded
-- linux-centos7-x86_64 / gcc@9.3.1 -----------------------------
openimageio@2.4.8.0  py-numpy@1.20.3  py-pybind11@2.10.1  py-setuptools@59.4.0  python@3.9.15
==> 5 loaded packages

I still have more testing to do, but it works in my basic scenarios. And obviously we'd want to make a command that's a shortcut for spack load --deptype run --concretize since that's a mouthful.

I jumped on the Spack Slack workspace and the author and contributors were open to the idea of adding these features. But life intervened and I haven't followed through with a PR yet.

Installed package layout

The install directory seems compatible with placing on network storage.

The installed package structure is something like this:

/opt/spack/opt/spack/linux-centos7-haswell/gcc-9.3.1/gdbm-1.19-mqmfeifz6htulhb44thxp6mpw7z7x7sg

Breaking this apart:

<install_dir>/<os>/<compiler>/<package>-<version>-<variant_spec_hash>

At the root of the install directory there is a .spack-db folder that appears to hold a file-based database of the contained packages. This is a nice touch for speeding up access since there can be a lot of folders here, especially because package variants are stored flat. It does mean that you can't simply delete packages from this directory: you have to use the proper command to keep the database in sync.

A few sharp edges

Most of the problems that I encountered were with the recipes rather than the tool itself. This makes sense since it's obviously not plausible to test every combination of OS, compiler, and package. Luckily, solving my various recipe issues was pretty straightforward.

Here are some other issues that I observed:

When using spack install or spack spec, concretizing an abstract spec that does not resolve to an existing spec will not error: it will complain later when it can't find the source.
spack install failed building boost with -j20 but worked when omitting the flag.
spack spec can be very slow. This may be improved by registering more external packages, which would reduce the number of dependencies to solve for.
support for Windows is still in progress. The docs state "while this work is still in an early stage, it is currently possible to set up Spack and perform a few operations on Windows."
The compiler must be configured before doing any spec concretization, as it will only find installed packages built with the active compiler

Closing thoughts

Rez is an environment management tool that grew build capabilities, whereas Spack seems to be the opposite: a build manager with some basic environment management. Making a robust build tool is many times harder than environment management. With a few days of work I was able to add functionality to Spack along the lines of rez-env. Making Rez's build functionality as capable as Spack would be... a lot harder. Multiple orders of magnitude more difficult.

I think the payoff of Spack would be high, especially in terms of enabling our industry to cooperate on build problems that we're all currently solving on our own. Imagine if the ASWF hosted a repo of battled-tested package recipes to build the VFX Reference Platform and ASWF libraries. With Spack that would be achievable with relatively little effort.

Spack has the potential to be a compelling package manager for the VFX/Animation industry, with a bit of work. It's certainly interesting how much overlap there is between our industry and supercomputing community in terms of build and deployment concerns. Who knows, maybe it could grow into a fruitful partnership.

Let me know what you think in the comments!

PyMEL's new type stubs

Chad Dombrova — Thu, 06 Apr 2023 13:42:26 +0000

The release of PyMEL 1.3.0 introduces PEP 561 type stubs for code completion and static analysis. For most people this just means that your favorite editor will provide better code completion, but I hope that for some it can be a gateway to a new level of development using static type analysis using a tool like mypy. Either way, if you take some time to understand the stubs, you can adjust your code to avoid warnings and increase the accuracy of the analysis.

To entice you with the payoff, here is PyCharm showing some deeper insight with the new stubs:

Completion of arguments and their types

Analysis of result types

Evolution from dynamic to static

Before getting to the stubs, I wanted to cover one of the other big recent changes to PyMEL. You can skip to the "Type stubs" section if you only came for the stubs.

A little history

At its lowest level PyMEL is an auto-generated wrapper around maya.cmds and maya.OpenMaya. Until recently, the automatic nature of this has been accomplished using function and class factories -- functions and classes that dynamically create new functions and classes -- driven by data caches that hold information about the members of maya.cmds and maya.OpenMaya, such as argument types and return values. The data caches are created by the PyMEL developers after each major version of Maya is released, by running a process that parses the docs (or xml version of the docs when Autodesk provides them) and inspects imported maya.cmds and maya.OpenMaya modules.

The sheer number of classes and functions that are wrapped and the data that must be read to accomplish this has a noticeable impact on import time. As an early mitigation strategy, we added lazy loading of functions as well as their docstrings, so the caches would only be read if absolutely necessary.

We also experimented with different schemes for the caches, such as compressed json files. A surprising observation from our years of experimentation was that loading pure python modules is actually very fast, so we began storing our caches as .py files.

Problems and solutions

One of the joys of python is its highly dynamic nature and its accessible data model. In my early years of python development, I enjoyed the challenge of creatively bending it to my will. I waged war on problems with function factories, metaclasses, data descriptors, and monkey-patching (in retrospect, I consider these the "teenage years" of experimentation, when, in the words of the great mathematician Dr. Ian Malcolm, I was too preoccupied with whether or not I could that I didn't stop to think if I should). In those days, I never could have imagined that we would ultimately turn to a solution that I considered anathema to python development: a build process to generate code.

We ultimately arrived at the code-generation approach due to several intractable problems with our previous dynamic factory strategy:

Tracebacks inside pymel functions can be confusing because they emanate from deep within the internals of the factory functions themselves. This makes it difficult to understand the context: there's not any "real" code to inspect, only function closures and local variables.
There's a runtime cost to reading data from the caches and executing the many function factories at import time.
As PyMEL developers, it's difficult to understand how changes to the cache between versions of Maya might produce different results within the dynamically generated functions: a code-gen approach reveals the exact changes as a diff in git.

Switching to a code-generation workflow meant porting our function factories to write out actual python code. The end result is that pymel now has a lot more code within its modules, but it no longer needs to load data from caches to import them: the cached data is essentially baked into the code itself (though we kept the lazy loading of docstrings).

For example, in the generated code for the cluster command, below, we can see that the wrapped func will try to cast the result to a PyNode if called in create/edit mode:

@_factories.addCmdDocs
def cluster(*args, **kwargs):
    res = cmds.cluster(*args, **kwargs)
    if not kwargs.get('query', kwargs.get('q', False)):
        res = _factories.maybeConvert(res, _general.PyNode)
    return res

For the bakeDeformer command, we can see that flexible handling of time values has been added:

@_factories.addCmdDocs
def bakeDeformer(*args, **kwargs):
    for flag in ('customRangeOfMotion', 'rom'):
        try:
            rawVal = kwargs[flag]
        except KeyError:
            continue
        else:
            kwargs[flag] = _factories.convertTimeValues(rawVal)
    res = cmds.bakeDeformer(*args, **kwargs)
    return res

If an error is raised by the underlying maya.cmds function, it will now come from within a real function like these, whose definitions reveal exactly what has been modified about the underlying function.

Type stubs

One of the other benefits of the new code-gen approach is that it simplifies our process for generating stub files. We've rebuilt our stub generator around mypy's stubgen tool, which we've extended to allow additional guidance from our rich data caches.

The end result is that our new type stubs are very accurate. They're accurate enough that you can now use mypy to statically type check your maya code.

At Luma, we're using mypy to check nearly our entire code-base, including our Maya-related code, thanks to these latest changes. Fully adopting mypy (or an alternative like pytype) is no small feat, but working within a fully type-annotated code base with a type checker to enforce accuracy is like coding in a higher plane of existence: fewer bugs, easier code navigation, faster dev onboarding, easier refactoring, and dramatically increased confidence about every change. I wrote about some deeper insights in these posts.

Even if you're not quite ready to fully annotate your code now, the good news is that the new stubs are based on a standard that has been adopted by many editors like PyCharm and VS Code, so you should begin to see immediate improvements just by pip installing pymel into a virtual env that your editor knows about.

Learning by example

Let's take some time to look at some stubbed functions so that you can learn how to maximize their benefit.

Here's the bakeDeformer stub:

def bakeDeformer(
    *args, 
    colorizeSkeleton: bool | int = ..., 
    cs: bool | int = ..., 
    customRangeOfMotion: str | Tuple[float, float] | Tuple[float] = ..., 
    rom: str | Tuple[float, float] | Tuple[float] = ..., 
    dstMeshName: _util.ProxyUnicode | str = ..., 
    dm: _util.ProxyUnicode | str = ..., 
    dstSkeletonName: _util.ProxyUnicode | str = ..., 
    ds: _util.ProxyUnicode | str = ..., 
    hierarchy: bool | int = ..., 
    hi: bool | int = ..., 
    influences: _util.ProxyUnicode | str = ..., 
    i: _util.ProxyUnicode | str = ..., 
    maxInfluences: int = ..., 
    mi: int = ..., 
    pruneWeights: float = ..., 
    pw: float = ..., 
    smoothWeights: int = ..., 
    sw: int = ..., 
    srcMeshName: _util.ProxyUnicode | str = ..., 
    sm: _util.ProxyUnicode | str = ..., 
    srcSkeletonName: _util.ProxyUnicode | str = ..., 
    ss: _util.ProxyUnicode | str = ...
): ...

Some things to notice:

bool | int means "bool or int". For simplicity we allow integers anywhere that booleans are expected, since it's a common MEL-inspired idiom to use 1 and 0 for True and False.
In places where str is accepted, we also allow ProxyUnicode: since all PyNode classes inherit from ProxyUnicode this ensures that they are valid anywhere a string is expected.
As we saw in the wrapped code above, the customRangeOfMotion arg is a time value, and PyMEL adds more flexible handling, so that "1:10", (1, 10) and (1,) are all acceptable.
The return type is not specified, which means it defaults to Any. Unfortunately there's not enough data available in the commands docs to determine what these command return, and it's made even more complicated by the fact that they can return different results depending on what arguments are provided. Thankfully methods that wrap maya.OpenMaya do have stubs with accurate result types.

Ok, now let's look at a more complicated example, listRelatives:

Each function signature is on one line, which is actually in compliance with the style guide for stubs, so I apologize for the length.

@overload
def listRelatives(*args: Any, type: Type[DagNodeT], allDescendents: bool | int = ..., ad: bool | int = ..., allParents: bool | int = ..., ap: bool | int = ..., children: bool | int = ..., c: bool | int = ..., fullPath: bool | int = ..., f: bool | int = ..., noIntermediate: bool | int = ..., ni: bool | int = ..., parent: bool | int = ..., p: bool | int = ..., path: bool | int = ..., pa: bool | int = ..., shapes: bool | int = ..., s: bool | int = ...) -> List[DagNodeT]: ...

@overload
def listRelatives(*args: Any, shapes: Literal[True], allDescendents: bool | int = ..., ad: bool | int = ..., allParents: bool | int = ..., ap: bool | int = ..., children: bool | int = ..., c: bool | int = ..., fullPath: bool | int = ..., f: bool | int = ..., noIntermediate: bool | int = ..., ni: bool | int = ..., parent: bool | int = ..., p: bool | int = ..., path: bool | int = ..., pa: bool | int = ..., type: str | List[str] = ..., typ: str | List[str] = ...) -> List[nodetypes.Shape]: ...

@overload
def listRelatives(*args: Any, type: Union[str, Iterable[Union[str, Type[nodetypes.DagNode]]]] = ..., allDescendents: bool | int = ..., ad: bool | int = ..., allParents: bool | int = ..., ap: bool | int = ..., children: bool | int = ..., c: bool | int = ..., fullPath: bool | int = ..., f: bool | int = ..., noIntermediate: bool | int = ..., ni: bool | int = ..., parent: bool | int = ..., p: bool | int = ..., path: bool | int = ..., pa: bool | int = ..., shapes: bool | int = ..., s: bool | int = ...) -> List[nodetypes.DagNode]: ...

Below I've trimmed the signatures down to just the arguments relevant to our discussion:

@overload
def listRelatives(
    *args: Any, 
    type: Type[DagNodeT],  
    shapes: bool | int = ...
) -> List[DagNodeT]: ...

@overload
def listRelatives(
    *args: Any, 
    shapes: Literal[True], 
    type: str | List[str] = ...
) -> List[nodetypes.Shape]: ...

@overload
def listRelatives(
    *args: Any, 
    type: Union[str, Iterable[Union[str, Type[nodetypes.DagNode]]]] = ...,  
    shapes: bool | int = ...
) -> List[nodetypes.DagNode]: ...

Let's break this down.

Each @overload describes a different scenario of input arguments and return types for this function. Your type checker will analyze your code to match an invocation of this function with one of these scenarios.

The first overload states that if you provide a node type to the type argument then listRelatives should return a list of nodes of that type.

Here's the proof in PyCharm:

In order for your editor or static type checker to properly infer the result type, you must use the actual class from the pymel.core.nodetypes module when using the type arg, as in the example above with type=pm.nt.Transform. Using a string, such as type="transform", will not give the analyzer the information it needs, and it will fall through to the third and most generic overload. This distinction only matters when analyzing your code: passing either string or class will continue to work the same at runtime!

It's also important to note that only the long form of the argument has a dedicated overload: you must use type= and not typ=. This was a pragmatic decision on my part to avoid an explosion of overloads for every combination of short and long args. Again, this only applies to analysis, runtime behavior remains unchanged.

The second overload states that if you provide shapes=True then listRelatives should return a list of Shape nodes. Again, only the long form is supported for analysis purposes: use shapes=True not s=True.

The third overload is a catchall for other scenarios and it declares that listRelatives should return a list of DagNodes in this case.

tl;dr The stubs allow code analyzers like the one in your favorite editor to understand what type should be returned from a function based on the types and values of its arguments.

Other common patterns

Another thing you can do to improve type analysis is use more specific types when casting strings to PyNodes. I find it's common in PyMEL code to simply rely on pm.PyNode(nodeName) to return the appropriate class for that node type, but the problem is your editor/analyzer does not know what the resulting type should be.

For example, in the code below your editor or type checker can only know that exportSet is a PyNode:

if pm.objExists(EXPORT_SET_NAME):
    exportSet = pm.PyNode(EXPORT_SET_NAME)
    return exportSet.members()
else:
    # EXPORT_SET_NAME does not exist
    return []

We can improve this by being more specific:

try:
    exportSet = pm.nt.ObjectSet(EXPORT_SET_NAME)
except pm.MayaNodeError:
    # EXPORT_SET_NAME does not exist
    return []
else:
    return exportSet.members()

Possible future benefits

As the typing coverage within PyMEL improves, it opens up the possibility of using a tool like mypyc to compile python code into high performance C-extension modules. It's unclear just how much this would help, because the major bottlenecks in PyMEL remain conversion back and forth between strings and OpenMaya objects, and sadly, after more than 15 years Autodesk has not provided any means for cmds and api/OpenMaya to efficiently communicate with each other. But it's an intriguing possibility to explore!

Other resources

Lastly, in case they are of some use, below are some tools and packages I created related to type annotations and analysis:

types-PySide2: The most accurate type stubs for PySide2. These are now installed by default with the latest version of Qt.py
mypy-runner: Ease your way into static type checking by focusing on a small set of problems at a time.
typeright: Insert type annotations into your python source code in various ways.

Have fun annotating!

Advanced Static Typing with mypy (part2)

Chad Dombrova — Wed, 31 Aug 2022 16:28:04 +0000

More lessons learned from 7 years of annotating a large code base

If you haven't read the first part of this series, it's not strictly necessary to understand this article, but it's worth a read. This article is more focused on topics that relate to the typing of classes, whereas the other is more focused on general concepts and functions.

A quick primer on generics and variance

This is an advanced topic and the better you comprehend it, the less time you'll spend solving type errors via trial and error. It's especially important once you start creating your own generic classes, so the first thing you should do is read up on variance of generic types in the mypy docs.

Now that you've read all of that, let's forge ahead.

Consider this simple example:


class Employee:
    def work(self) -> None:
        pass

class Manager(Employee):
    def manage(self) -> None:
        pass

def do_work(x: Employee) -> None:
   x.work()

do_work(Employee())
do_work(Manager())

mypy passes with flying colors. We can pass a Manager instance to do_work because Manager is considered a subtype of Employee. Subclasses are subtypes. Easy enough. But it gets more complicated when we introduce generics.

Consider this:

from typing import Iterable, TypeVar, Generic
T = TypeVar('T')

class Employee:
    def work(self):
        pass

class Manager(Employee):
    def manage(self):
        pass

class Team(Generic[T]):
    pass

def do_team_work(x: Team[Employee]) -> None:
   pass

team = Team[Employee]()
do_team_work(team)
management_team = Team[Manager]()
do_team_work(management_team)  # mypy error!

Is Team[Manager] a subtype of Team[Employee]? Intuitively it seems like it should be, but in fact it is not! The code above produces the following error:

Argument 1 to "do_work" has incompatible type "Team[Manager]"; expected "Team[Employee]

This is pretty unintuitive. Now it's time to RTFD!

From the mypy docs on variance of generic types:

By default, mypy assumes that all user-defined generics are invariant.

Team is a user-defined generic, so it's invariant. What does that mean?

The very first thing we need to understand is what is meant by "generic"? Essentially this means a container type. For example, a list is a container type, it holds other objects, for example a list[str]. A dictionary is a container type, it contains other types in the form of keys and values, e.g. a dict[str, int].

We intuitively understand that a subclass is a sub-type of its parent class. For example, in the code below, it's obvious that B is a sub-type of A.

class A:
    pass

class B(A):
    pass

"Variance" is all about understanding how and why generics -- i.e. containers -- are subtypes of each other.

To understand this, we have to review the 3 types of variance: invariant, covariant, and contravariant. Here's my simplified version of the mypy docs:

Given these classes:

from typing import Generic, TypeVar

T = TypeVar("T") 

class A:
    pass

class B(A):
    pass

class Thing(Generic[T]):
    pass

Here's how we can think about the variance of some generic type Thing:

Variance type	Rule description	Rule code
covariant	`Thing[T]` is covariant if `Thing[B]` is always a subtype of `Thing[A]`	`issubclass(Thing[B], Thing[A]) is True`
contravariant	`Thing[T]` is contravariant if `Thing[A]` is always a subtype of `Thing[B]`	`issubclass(Thing[A], Thing[B]) is True`
invariant	`Thing[T]` is called invariant if neither of the above is true	`issubclass(Thing[B], Thing[A]) is False and issubclass(Thing[A], Thing[B]) is False`

This definition is recursive, because to know if B is a subtype of A, we must again refer to their variance.

We want Team[B] to be a subtype of Team[A], so referring to the list above we need the first one, covariance. Here's how we do this:

from typing import Iterable, TypeVar, Generic
T_co = TypeVar('T_co', covariant=True)

class Employee:
    def work(self):
        pass

class Manager(Employee):
    def manage(self):
        pass

class Team(Generic[T_co]):
    pass

def do_work(x: Team[Employee]) -> None:
   pass

team = Team[Employee]()
do_team_work(team)
management_team = Team[Manager]()
do_team_work(management_team)  # <-- NO mypy error!

This does not mean that you should use covariant=True for every TypeVar that you define! A covariant TypeVar should be reserved for immutable generics -- containers which cannot have their members added or removed after instantiation. If it is not immutable, then you subvert the variance protection that mypy provides. This is why Sequence is covariant, but List is not -- Sequence does not provide any methods for modifying its contents.

It seems to be a pretty well-established convention to use _co and _contra suffixes for covariant and contravariant respectively.

How to deal with classes that instantiate attributes outside of `init`

It often comes up that a class has a function to refresh its instance variables, and the principles of code reuse dictate that we use that function in our __init__ to initialize the variables as well:

def read_from_db() -> Tuple[int, str]:
    ...

class Person:
    def __init__(self, name: str) -> None:
        self.name = name
        self.age: int = None         # error!
        self.location: str = None    # error!
        self.refresh()

    def refresh(self) -> None:
        self.age, self.location = read_from_db()

mypy produces the following errors:

error: Incompatible types in assignment (expression has type "None", variable has type "int")
error: Incompatible types in assignment (expression has type "None", variable has type "str")

The naive solution to this is to make self.age and self.location Optional, however in this case this is not what we want, because in our contrived example read_from_db() always returns a non-None value, and we want don't want code that uses our Person to have to add is None checks everywhere for these attributes.

Here's one solution:

def read_from_db() -> Tuple[int, str]:
    ...

class Person:
    def __init__(self, name: str) -> None:
        self.name = name
        self.refresh()

    def refresh(self) -> None:
        self.age, self.location = read_from_db()

This works because a variable's type is assigned on the first line that it is defined. The downside is that the variables and their types are not front-and-center in the __init__ where we expect them, so developers reading your code may miss them if they don't go hunting. Also, it's somewhat brittle, since shuffling method order during a refactor could lead to some other line being the first assignment of these variables (not in this example, obviously, because there are only two methods and one assignment for each attribute).

Here's an alternative solution:

def read_from_db() -> Tuple[int, str]:
    ...

class Person:
    age: int
    location: str

    def __init__(self, name: str) -> None:
        self.name = name
        self.refresh()

    def refresh(self) -> None:
        self.age, self.location = read_from_db()

This is valid, but we have to be careful when we use technique. We must instantiate self.age and self.location as early in the life-cycle of Person as possible, because mypy now believes they are non-None.

Consider this example:

def read_from_db() -> Tuple[int, str]:
    ...

class Person(object):
    age: int = None
    location: str = None

    def __init__(self, name: str) -> None:
        self.name = name
        # self.refresh() not called!

    def refresh(self) -> None:
        "You must call this manually!"
        self.age, self.location = read_from_db()

p = Person('chad')
next_year = p.age + 1  # runtime error!

mypy will not complain, because it believes p.age is an int, however this code will fail at runtime because p.age is actually None since we have not instantiated it.

When to use `assert` and `typing.cast`

typing.cast and assert are easy ways to resolve mypy errors, especially with Optional types, but they should be used as a last resort.

assert can be used to narrow a type in the same way that you can with an if/else statement, but directly in the current scope.

typing.cast does the same thing, but without the runtime implications.

These two approaches should only be used to correct mypy oversights that can't be corrected by other means.

Why? An assert is a sanity check, it means "if everything is working, this statement should never fail". If there is any chance that it could fail, you should raise an error with a proper exception type.

In the case of typing.cast, mypy will blindly change the type of the variable to whatever you cast it to, and you may be wrong! There is no runtime check to keep you honest. I almost always reserve cast for scenarios that involve "imaginary" types that can't be used in an isinstance statement, such as TypeVars.

Let's consider this example adapted from above:

def read_from_db() -> Tuple[int, str]:
    ...

class Person(object):

    def __init__(self, name: str) -> None:
        self.name = name
        self.age: Optional[int] = None

    def load_age(self) -> None:
        "You must call this manually!"
        self.age = read_from_db()[0]

    def is_younger_than(self, other_age: int) -> bool:
        self.load_age()
        return self.age < other_age   # mypy error!

self.age is Optional inside is_younger_than, because mypy is not able to track conditional changes in state that happen outside of a function.

We can solve this by adding an assert:

    def is_younger_than(self, other_age: int) -> bool:
        self.load_age()
        assert self.age is not None, \
            "self.age is set by load_age"
        return self.age < other_age

When it comes to typing, it is a good habit to add an explanation for every assert or cast. Explain why you believe that the assertion should not fail or the cast is correct at this point in the program's execution. What logical assurances do we have that this will always be safe? If you can't explain it, then you should consider raising a proper exception.

A better alternative is almost always to restructure things to allow static typing to pass. For example, you could try redesigning your API so that the values are always set on __init__ (e.g. by providing alternate instantiators as classmethods).

Below is an example of using a cached property instead of an attribute to solve the situation outlined above:

from functools import cached_property

def read_from_db() -> Tuple[int, str]:
    ...

class Person:

    def __init__(self, name: str) -> None:
        self.name = name

    @cached_property
    def age(self) -> int:
        "You must call this manually!"
        return read_from_db()[0]

    def is_younger_than(self, other_age: int) -> bool:
        return self.age < other_age

Sometimes the cure is worse than the illness -- meaning refactoring the code to remove the type error would be too disruptive -- so it's up to you to decide whether an assert is the right solution, but you should use them sparingly.

Here's my order of preference:

Try to solve the problem with better typing. A type error often means A) the type of the variable is wrong, or B) the type of a function that the variable is being passed to is wrong. If the types don't line up with reality then I try my best to make them. This may require making an argument more permissive (using a protocol), adding overloads to a function, or generics to a class.
If option 1 fails, or the added complexity was untenable, but I know the actual type at runtime, then I do one of two things:
1. use an assert if I'm reasonably certain that the assertion will never fail. provide a comment explaining why it will never fail.
2. raise a proper exception if there is a chance that it might fail.
As a final fallback, I use typing.cast and provide a comment explaining why the cast is necessary.

I highly recommend enabling --warn-redundant-casts so that you can be notified if a call to cast is attempting to cast an expression to the same type. A redundant cast can mislead developers into thinking that the type of the expression or variable was something other than the cast type.

Be mindful with tuples, they come in two forms

Tuples are unique in the typing system because they can be used in two different ways:

a specific, bounded, and possibly heterogenous group of types. e.g. Tuple[str, int] is a 2-tuple containing a string and an integer
an unbounded sequence of homogenous types. e.g. Tuple[str, ...] (note the ellipsis!). this is a sequence of strings of arbitrary length

And of course you can also combine the two: Tuple[Tuple[str, int], ...]

When mypy infers the type of a tuple literal, it assumes the intent is option 1 by default. In order to tell mypy, "no I actually mean option 2", you must add an annotation. This is particularly annoying with inherited class variables.

class Base(object):
    valid_things = ('thing1',)

class A(Base):
    valid_things = ('thing1', 'thing2')  # error: expression has type "Tuple[str, str]", base class defined type as "Tuple[str]"

This results in an error because Base.validThings is Tuple[str] and A.validThings is Tuple[str, str]. Here's a naive solution to this problem:

class Base(object):
    valid_things: Tuple[str, ...] = ('thing1',)

class A(Base):
    valid_things: Tuple[str, ...] = ('thing1', 'thing2')

Unfortunately, it is kind of verbose. One solution that's less verbose and maintains immutabilty is to use frozenset (assuming of course that order does not matter):


class Base(object):
    valid_things = frozenSet(['thing1'])

class A(Base):
    valid_things = frozenSet(['thing1', 'thing2'])

Or we could use the faux-immutability approach explained above in "Use abstract types to help enforce immutability":

class Base(object):
    valid_things: Sequence[str] = ['thing1']

class A(Base):
    valid_things: Sequence[str] = ['thing1', 'thing2']

With the above solution you do need to redeclare the attribute type as Sequence[str] on each sub-class or it will be promoted to List[str] and will be thus be mutable.

Get the benefits of `abc.ABCMeta` without the metaclass conflicts

The purpose of abc.ABCMeta is to raise an error at runtime if you define a class that does not implement all of the methods marked as abstract on the abstract base class. Unfortunately, this can cause conflicts with other classes that uses metaclasses, which is particularly irksome with third-party projects like PyQt, PySide, or typing.Generic (before python 3.7). The solutions to this can be quite unsavory.

mypy gives us a brand new solution to this problem: continue using the abc decorators, but don't use the abc.ABCMeta metaclass: mypy perform the same checks as abc.ABCMeta, but during static analysis rather than at runtime. Of course, this is only effective if your code is annotated well enough to track your abstract classes, but it's a great option if it is.

Did I miss anything? Feel free to leave comments with questions or other tips that I missed!

Advanced Static Typing with mypy (part1)

Chad Dombrova — Tue, 26 Apr 2022 15:59:16 +0000

Lessons learned from 7 years of annotating a large code base

"I don't meditate, I annotate"

Introducing static typing and mypy to a large code base is not for the faint of heart, but the benefits are worth the effort:

release fewer bugs
make large refactors with confidence
navigate codebase with ease
rapidly onboard new developers

Once you've worked with a well-typed python project, working with "naked" code is painful. In fact, you may find, like I did, that annotating code is a rewarding puzzle that can be quite meditative.

This article is not an introduction to static typing, there are other great resources for that. This is adapted from an internal wiki that I wrote over several years of collecting solutions to common problems. Eventually I came to realize that these tips represent a new set of idioms, conventions, best practices, and design patterns for working with typed code that (to my knowledge) haven't been well documented and disseminated yet. Hopefully you'll find them useful.

You may also find a use for some of the tools I've made along the way:

typewriter: generate annotations from various sources
mypy-runner: wrapper around mypy that gives more control over filtering

Also, the second part of this series is here.

Enough foreplay, let's get started!

Use concrete types for function results, and abstract types for arguments

If you read only one part of this article, it should be this.

When adding type annotations for containers (e.g. list, set, tuple, dict, etc), you can increase the flexibility of your code by specifying the capabilities that your function requires of each argument, rather than using a specific type: this is known as "structural subtyping". The easiest way to do this is by using the generic collections in abc.collections, which are also available in the typing module.

In the abc.collections docs you'll see that each abstract collection class corresponds to one more more underlying special methods. For example, Sized implements __len__ which enables len(x), and Container implements __contains__ which enables y in x. An object is considered an instance of one of these classes if it implements the required methods.

Consider this example:

from typing import List

def get_unique(values: List[str], invalid: List[str]) -> List[str]:
    return [x for x in values if x not in invalid]

The annotations for the arguments are overly specific: values and invalid don't need to be lists. This function requires that values implements __iter__, and invalid implements __contains__. We can refer to the abc.collections documentation to see that we can use Iterable and Container respectively:

from typing import Container, Iterable, List

def get_unique(values: Iterable[str], invalid: Container[str]) -> List[str]:
    return [x for x in values if x not in invalid]

Does that mean we should also use an abstract type for the return type? The answer is usually "no". There are specific situations where using abstract rather than concrete result types is beneficial, such as to fake immutability (see next section) or to satisfy Liskov, but in most cases, when you use a more abstract type for return annotations you're withholding information from the type system and other developers. In our example above, the result is always a list, and there's no advantage in pretending that it's not. Doing so might encourage users of your function to needlessly re-cast the result to a list, for example.

Note, if the return type varies based on an argument type, use a TypeVar and/or @typing.overload to describe those relationships.

Use abstract types to help enforce immutability

Using abstract container types has another benefit.

Consider this example:

from functools import lru_cache
from typing import List, Set

@lru_cache(None)
def get_value() -> List[Set[int]]:
    return [{1, 2}, {3}]

x = get_value()
x.append({4})  # oops, we're appending to the cached value!

Caching decorators like lru_cache will return the same object on successive calls to the same function, and our example above demonstrates how a developer might unknowingly alter the cached value, thinking they have a unique copy. We can protect against this by using abstract containers that don't support mutation.

from functools import lru_cache
from typing import AbstractSet, Sequence

@lru_cache(None)
def get_value() -> Sequence[AbstractSet[int]]:
    return [{1, 2}, {3}]

x = get_value()
x.append({4})  # mypy errors here: no append method
x[0].add(4)  # mypy errors here: no add method

Replacing list with tuple and set with frozenset would achieve the same goal, but not every container has a concrete immutable alternative, and it's often easier to strip away capabilities at the typing level, rather than modifying our code to recursively convert mutable types to immutable types.

Note that if you have a nested data structure, as above, and you want to use typing to enforce immutability, you need to declare each type in the hierarchy as immutable. Immutability is not recursively granted by the parent container to its children -- a type only affects the attributes and methods of itself.

Here's a list of concrete types and some abstract types to use enforce immutability.

concrete type	immutable alternative	abstract immutable type
`dict`	?	`Mapping`
`list`	`tuple` / `Tuple`	`Sequence`
`set`	`frozenset` / `FrozenSet`	`AbstractSet`

Don't obscure the use of `isinstance` / `issubclass` / `is type`.

mypy inspects conditional blocks (and asserts) that use isinstance, issubclass, is type (including is None) in order to track the types of variables as they enter new scopes.
As a result, you should avoid using helper functions that wrap these calls when checking types, or if you do, you should use typing.TypeGuard (see below).

For example, at the time of this writing, mypy does not support inspect.isclass():

if inspect.isclass(x) and issubclass(x, Asset):
    ...

Here's what you should do instead:

if isinstance(x, type) and issubclass(x, Asset):
    ...

Another common way to confuse mypy is storing the result of a type check to a variable:

is_asset = isinstance(x, Asset)
if is_asset:
    ... do stuff
else:
    ... do stuff

The solution is simply to perform the check on the if line:

if isinstance(x, Asset):
    is_asset = True
    ... do stuff
else:
    is_asset = False
    ... do stuff

Likewise, when designing APIs, avoid providing methods that distinguish between types, in order to encourage use of isinstance checks.

Here's another example of an idiom that mypy does not understand:

if None not in (x, y, z):
    result = x + y + z

Instead, you need to be more explicit:

if x is not None and y is not None and z is not None:
    result = x + y + z

Or, depending on your circumstances, you might be able to do something like this:

inputs = (x, y, z)
valid = [v for v in inputs if v is not None]
if len(valid) == len(inputs):
    result = sum(valid)

If you do obscure the use of `isinstance` / `issubclass` / `is type`, then use `TypeGuard`

Here's a giant caveat to everything in the last section. A recent addition to typing provides a way to write functions that can be used to narrow the type of a variable in a way that has previously only been possible with builtin functions like isinstance that mypy supports explicitly. The new functionality is called a TypeGuard. This is covered here in the mypy docs.

Here's a simple recipe that's very handy:

from typing import Any, Type, TypeGuard, TypeVar
T = TypeVar("T")

def safe_issubclass(obj: Any, typ: Type[T]) -> TypeGuard[Type[T]]:
    return isinstance(obj, type) and issubclass(obj, typ)

Avoid writing functions that return different types based on an argument

This is a big no-no in static type checking. The naive approach is use a Union result:

def add(x: int, y: int, as_str: bool = False) -> Union[str, int]:
    result = x + y
    if as_str:
        return str(result)
    return result

value = add(1, 2)
print(value + 10)  # error! can't add str and int

Using a Union in this situation undermines the type checker for everything downstream of this call.

It can sometimes be possible to solve this using @typing.overload, but it is a verbose and overly complicated solution.

from typing import overload, Literal, Union

@overload
def add(x: int, y: int, as_str: Literal[False] = False) -> int:
    pass

@overload
def add(x: int, y: int, as_str: Literal[True]) -> str:
    pass

def add(x: int, y: int, as_str: bool = False) -> Union[str, int]:
    result = x + y
    if as_str:
        return str(result)
    return result

value = add(1, 2)
print(value + 10)  # success!  mypy knows that value is an int

The simplest solution is to provide two different functions, ideally where one calls the other and then performs some final type adjustments, so that you can avoid duplicating code.

Use annotations to "relax" inferred types when they're too restrictive

mypy assigns a type to a variable based on its value on the first line on which it is defined. This initial type is often too narrow, because the type of the variable may be a work-in-progress.

Here's an example where we build up a dictionary of keyword args to pass to a function, which is a fairly common practice:

import subprocess
from typing import Dict, Iterable, Union

def run(args: Union[str, Iterable[str]], env: Optional[Dict[str, str]] = None) -> None:
    kwargs = {"shell": isinstance(args, str)}  # <-- inferred type is Dict[str, bool] !!!
    if env:
        kwargs["env"] = env  # error! env is not a bool
    subprocess.call(args, **kwargs)

mypy produces the following errors:

mypytest.py:11: error: Incompatible types in assignment (expression has type "Dict[str, str]", target has type "bool")
mypytest.py:12: error: Argument 2 to "call" has incompatible type "**Dict[str, bool]"; expected "Union[str, unicode]"
mypytest.py:12: error: Argument 2 to "call" has incompatible type "**Dict[str, bool]"; expected "Callable[[], Any]"
mypytest.py:12: error: Argument 2 to "call" has incompatible type "**Dict[str, bool]"; expected "Union[Mapping[str, Union[str, unicode]], Mapping[unicode, Union[str, unicode]]]"

The first error is the real culprit; the others are collateral damage. What's happened here is that mypy has determined that the variable kwargs is Dict[str, bool] based on its first assignment, so it complains when trying to add env to the dict, because it is restricted to bool values.

To solve this, we just need to relax the type of the kwargs dictionary from its inferred type of Dict[str, bool] to Dict[str, Any]:

import subprocess
from typing import Dict, Iterable, Union

def run(args: Union[str, Iterable[str]], env: Optional[Dict[str, str]] = None) -> None:
    kwargs: Dict[str, Any] = {"shell": isinstance(args, str)}
    if env:
        kwargs["env"] = env
    subprocess.call(args, **kwargs)

I do not recommend using a Union for the value component of a dictionary (e.g. Dict[str, Union[int, bool]]), especially not for one that will be used with **: it causes far more trouble than it's worth. Use Dict[str, Any] instead.

It's important to realize that using ** arg expansion undermines mypy, because it's not able to connect the dots between the types of the individual keys in the expanded dictionary and the keyword args in the function being called (you could with a TypedDict, but in most cases that's not worth the extra work). So, in our example above, we could set the type wrong for kwargs["env"] and mypy would not warn us.

The ideal solution, when possible, is to avoid ** expansion and instead pass values directly. This often requires doing a little digging to find the default arguments for the function that's being called to avoid the need for conditionally passing arguments:

import subprocess
from typing import Dict, Iterable, Union

def run(args: Union[str, Iterable[str]], env: Optional[Dict[str, str]] = None) -> None:
    subprocess.call(args, shell=isinstance(args, str), env=env)

This problem also rears its head with variables that we want to be a Union of types:

if whatever:
    foo = 2
else:
    foo = 'some string'

This produces the dreaded Incompatible types in assignment error. To avoid this, we need to declare the real type on the first line that foo is defined:

if whatever:
    foo: Union[int, str] = 2
else:
    foo = 'some string'

Consider returning an optional tuple instead of a tuple with optional values

It's quite common for a function to return None as a signal that a minor failure occurred: i.e. the correct value could not be retrieved. In the case of a function that returns a tuple, prior to adopting static typing, I would have typically returned None for each item in the tuple. For example:

def get_dimensions() -> Tuple[Optional[int], Optional[int], Optional[int]]:
    if is_valid_context():
        return 10, 20, 30
    else:
        return None, None, None

This is nice because we can immediately unpack the results:

x, y, z = get_dimensions()
if x is not None:
    print(x + y + z)  # ERROR: y and z cannot be None

As humans reading this code we can reason that if one of these is None then they all are, or if any of them is not None, then they are all not None. But to a type checker each None-state is independent.

This can create some painfully verbose type-checking scenarios:

x, y, z = get_dimensions()
if x is not None and y is None and z is None:
    print(x + y + z)

The most technically correct solution is to use typing.overload:

from typing import overload, Optional, Tuple

@overload
def get_dimensions() -> Tuple[int, int, int]:
    pass

@overload
def get_dimensions() -> Tuple[None, None, None]:
    pass

def get_dimensions() -> Tuple[Optional[int], Optional[int], Optional[int]]:
    if is_valid_context():
        return 10, 20, 30
    else:
        return None, None, None

With the addition of these overloads mypy knows that there are only two scenarios: either all the items are None or they're all int. However, it's a pretty verbose solution, and particularly unappealing for functions with many arguments, and thus many annotations to keep up to date.

Note that the overloads establish the typing for get_dimensions for the outside world -- code that calls get_dimensions -- but they do not affect the analysis of the internals of get_dimensions itself. Only the typing of the final, non-overloaded function applies to the internals of the function implementation.

Another solution is to make the entire tuple optional:

def get_dimensions() -> Optional[Tuple[int, int, int]]:
    if is_valid_context():
        return 10, 20, 30
    else:
        return None

Then use of the returned result like this:

dimension = get_dimensions()
if dimensions is not None:
    x, y, z = dimensions
    print(x + y + z)

This would not normally be my favorite choice because it often requires an extra variable and line to unpack it, but it seems to be the lesser of the evils.

In python 3.8 this could be made even more concise with the walrus operator:

if (dimensions := get_dimensions()) is not None:
    x, y, z = dimensions
    print(x + y + z)

Techniques to reuse variables

A common complaint about mypy is that it forces developers to create additional variables "needlessly" just to avoid mypy errors about incompatible types.

As mentioned before, mypy assigns a type to a variable based on its value on the first line on which it is defined. If you assign a new value to a variable it must be the same as the original type, or narrower.

Note that this behavior can be disabled using the mypy flag --allow-redefinition, though I honestly don't recommend it.

Narrow the type within scopes

You can always make the type of a variable more specific. Here are some examples of valid narrowing of types:

kind of narrowing	example
base to subclass	`basestring -> str`
union pruning	`Union[str, int] -> int`
abstract to concrete	`Iterable[int] -> List[int]`

ways to narrow
`isinstance(x, y)`
`issubclass(x, y)`
`type(x) is y`
`typing.cast(y, x)`
`typing.TypeGuard[y]`

Here's an example of successful union narrowing:

import subprocess
from typing import Any, Dict, Optional, List, Union

def run(args: Union[str, List[str]], env: Optional[Dict[str, str]] = None) -> None:
    kwargs: Dict[str, Any] = {
        "shell": False,
    }
    if isinstance(args, str):
        # in this scope, args is understood to be a str.
        # now we convert args from str to List[str].
        args = args.split()
        # the str case of Union[str, List[str]] is now removed
    # at this point args can now only be List[str]
    if env:
        kwargs["env"] = env
    subprocess.call(args, **kwargs)

Above, we've successfully narrowed args from Union[str, List[str]] to List[str].

Return early

Another way to avoid variable proliferation is to look for opportunities to return early. Since Python is so flexible, I often see if/else blocks that bind different types to the same variable before returning it:

def letter_list(s: str, strip_last: bool = False) -> Optional[str]:
    if s:
        result = list(s)
        if strip_last:
            result = result[:-1]
    else:
        result = None   # error: incompatible type
    return result

If we try to type result it leads to more problems:

def letter_list(s: str, strip_last: bool = False) -> Optional[str]:
    if s:
        result: Optional[str] = list(s)
        if strip_last:
            result = result[:-1]   # error: None does not support indexing
    else:
        result = None
    return result

The simplest solution is sometimes to return as soon as you can:

def letter_list(s: str, strip_last: bool = False) -> Optional[str]:
    if s:
        result = list(s)
        if strip_last:
            result = result[:-1]
        return result
    else:
        return None

When to use a new variable name

Sometimes using a new variable is unavoidable.

Here's an example of that kind of failure:

import subprocess
from typing import *

def run(args: str, env: Optional[Dict[str, str]] = None) -> None:
    kwargs: Dict[str, Any] = {
        "shell": False,
    }
    args = args.split()  # error: can't reassign the type of args!
    args.insert(0, 'xdg-open')
    if env:
        kwargs["env"] = env
    subprocess.call(args, **kwargs)

The problem line is args = args.split() where we try to convert args from a str to List[str].

Instead, we need to use different variables for each type:

import subprocess
from typing import *

def run(args: str, env: Optional[Dict[str, str]] = None) -> None:
    kwargs: Dict[str, Any] = {
        "shell": False,
    }
    parts = args.split()
    parts.insert(0, 'xdg-open')
    if env:
        kwargs["env"] = env
    subprocess.call(parts, **kwargs)

Generally speaking, I find this to be a good thing, as usually when data changes type, it changes meaning as well.

If you enjoyed this, check out the second part, and feel free to leave comments with questions or other tips that I missed!

DEV Community: Chad Dombrova

Using Spack to build the VFX Refence Platform

Exploring Spack as an alternative to Rez for VFX and Animation

Comparison to Rez

Popularity

Project health

Features

Rez to Spack cheat sheet

Diving in

chadrik / spack-vfx-demo

Companion scripts for the article "Using Spack to build the VFX Reference Platform"

Build the VFX Reference Platform using Spack

A quick test of version specs

Setting up the compiler

Building OpenImageIO

External packages

Building the VFX Reference Platform

Managing environment variables

Installed package layout

A few sharp edges

Closing thoughts

PyMEL's new type stubs

Evolution from dynamic to static

A little history

Problems and solutions

Type stubs

Learning by example

Other common patterns

Possible future benefits

Other resources

Advanced Static Typing with mypy (part2)

More lessons learned from 7 years of annotating a large code base

A quick primer on generics and variance

How to deal with classes that instantiate attributes outside of __init__

When to use assert and typing.cast

Be mindful with tuples, they come in two forms

Get the benefits of abc.ABCMeta without the metaclass conflicts

Advanced Static Typing with mypy (part1)

Lessons learned from 7 years of annotating a large code base

Use concrete types for function results, and abstract types for arguments

Use abstract types to help enforce immutability

Don't obscure the use of isinstance / issubclass / is type.

If you do obscure the use of isinstance / issubclass / is type, then use TypeGuard

Avoid writing functions that return different types based on an argument

Use annotations to "relax" inferred types when they're too restrictive

Consider returning an optional tuple instead of a tuple with optional values

Techniques to reuse variables

Narrow the type within scopes

Return early

When to use a new variable name

How to deal with classes that instantiate attributes outside of `init`

When to use `assert` and `typing.cast`

Get the benefits of `abc.ABCMeta` without the metaclass conflicts

Don't obscure the use of `isinstance` / `issubclass` / `is type`.

If you do obscure the use of `isinstance` / `issubclass` / `is type`, then use `TypeGuard`