Caveats/Known Issues¶

Some functions in thedataclasses module, such asasdict(),have imprecise (too permissive) types. This will be fixed in future releases.

Mypy does not yet recognize aliases ofdataclasses.dataclass, and willprobably never recognize dynamically computed decorators. The following exampledoesnot work:

fromdataclassesimportdataclassdataclass_alias=dataclassdefdataclass_wrapper(cls):returndataclass(cls)@dataclass_aliasclassAliasDecorated:"""  Mypy doesn't recognize this as a dataclass because it is decorated by an  alias of `dataclass` rather than by `dataclass` itself.  """attribute:intAliasDecorated(attribute=1)# error: Unexpected keyword argument

To have Mypy recognize a wrapper ofdataclasses.dataclassas a dataclass decorator, consider using thedataclass_transform()decorator (example uses Python 3.12 syntax):

fromdataclassesimportdataclass,Fieldfromtypingimportdataclass_transform@dataclass_transform(field_specifiers=(Field,))defmy_dataclass[T](cls:type[T])->type[T]:...returndataclass(cls)

Caveats/Known Issues¶

• The detection of attr classes and attributes works by function name only.This means that if you have your own helper functions that, for example,returnattrs.field() mypy will not see them.

• All boolean arguments that mypy cares about must be literalTrue orFalse.e.g the following will not work:

  importattrsYES=True@attrs.define(init=YES)classA:...

• Currently,converter only supports named functions. If mypy finds something else itwill complain about not understanding the argument and the type annotation in__init__ will be replaced byAny.

• Validator decoratorsanddefault decoratorsare not type-checked against the attribute they are setting/validating.

• Method definitions added by mypy currently overwrite any existing methoddefinitions.

Shared repository for cache files¶

You need a repository that allows you to upload mypy cache files fromyour CI build and make the cache files available for download based ona commit id. A simple approach would be to produce an archive of the.mypy_cache directory (which contains the mypy cache data) as adownloadablebuild artifact from your CI build (depending on thecapabilities of your CI system). Alternatively, you could upload thedata to a web server or to S3, for example.

Continuous Integration build¶

The CI build would run a regular mypy build and create an archive containingthe.mypy_cache directory produced by the build. Finally, it will producethe cache as a build artifact or upload it to a repository where it isaccessible by the mypy wrapper script.

Your CI script might work like this:

• Run mypy normally. This will generate cache data under the.mypy_cache directory.

• Create a tarball from the.mypy_cache directory.

• Determine the current git master branch commit id (say, usinggitrev-parseHEAD).

• Upload the tarball to the shared repository with a name derived from thecommit id.

Mypy wrapper script¶

The wrapper script is used by developers to run mypy locally duringdevelopment instead of invoking mypy directly. The wrapper firstpopulates the local.mypy_cache directory from the sharedrepository and then runs a normal incremental build.

The wrapper script needs some logic to determine the most recentcentral repository commit (by convention, theorigin/master branchfor git) the local development branch is based on. In a typical gitsetup you can do it like this:

gitmerge-baseHEADorigin/master

The next step is to download the cache data (contents of the.mypy_cache directory) from the shared repository based on thecommit id of the merge base produced by the git command above. Thescript will decompress the data so that mypy will start with a fresh.mypy_cache. Finally, the script runs mypy normally. And that’s all!

Caching with mypy daemon¶

You can also use remote caching with themypy daemon.The remote cache will significantly speed up the firstdmypycheckrun after starting or restarting the daemon.

The mypy daemon requires extra fine-grained dependency data inthe cache files which aren’t included by default. To use caching withthe mypy daemon, use the--cache-fine-grained option in your CIbuild:

$ mypy --cache-fine-grained <args...>

This flag adds extra information for the daemon to the cache. Inorder to use this extra information, you will also need to use the--use-fine-grained-cache option withdmypystart ordmypyrestart. Example:

$ dmypy start -- --use-fine-grained-cache <options...>

Now your firstdmypycheck run should be much faster, as it can usecache information to avoid processing the whole program.

Refinements¶

There are several optional refinements that may improve things further,at least if your codebase is hundreds of thousands of lines or more:

• If the wrapper script determines that the merge base hasn’t changedfrom a previous run, there’s no need to download the cache data andit’s better to instead reuse the existing local cache data.

• If you use the mypy daemon, you may want to restart the daemon each timeafter the merge base or local branch has changed to avoid processing apotentially large number of changes in an incremental build, as this canbe much slower than downloading cache data and restarting the daemon.

• If the current local branch is based on a very recent master commit,the remote cache data may not yet be available for that commit, asthere will necessarily be some latency to build the cache files. Itmay be a good idea to look for cache data for, say, the 5 latestmaster commits and use the most recent data that is available.

• If the remote cache is not accessible for some reason (say, from a publicnetwork), the script can still fall back to a normal incremental build.

• You can have multiple local cache directories for different local branchesusing the--cache-dir option. If the user switches to an existingbranch where downloaded cache data is already available, you can continueto use the existing cache data instead of redownloading the data.

• You can set up your CI build to use a remote cache to speed up theCI build. This would be particularly useful if each CI build startsfrom a fresh state without access to cache files from previousbuilds. It’s still recommended to run a full, non-incrementalmypy build to create the cache data, as repeatedly updating cachedata incrementally could result in drift over a long time period (dueto a mypy caching issue, perhaps).