Skip to content

typeshed_stats.gather API reference

Tools for gathering stats about typeshed packages.


AnnotationStats

Stats on the annotations for a source file or a directory of source files.

Attributes:

Name Type
annotated_parameters int
unannotated_parameters int
annotated_returns int
unannotated_returns int
explicit_Incomplete_parameters int
explicit_Incomplete_returns int
explicit_Any_parameters int
explicit_Any_returns int
annotated_variables int
explicit_Any_variables int
explicit_Incomplete_variables int
classdefs int
classdefs_with_Any int
classdefs_with_Incomplete int

CompletenessLevel

Whether or not a stubs package has been explicitly marked as 'partial'.

See PEP 561 for an elaboration of what it means for a stub to be marked as partial.

Members:

Name Description
PARTIAL The stubs package may not cover the entire API at runtime
COMPLETE The stubs package should cover the entire API at runtime
STDLIB These are the stdlib stubs -- the idea of 'partial/complete' doesn't really apply in the same way

FileInfo

Statistics about a single .pyi file in typeshed.

Attributes:

Name Type
file_path Path
parent_package str
number_of_lines int
pyright_setting PyrightSetting
annotation_stats AnnotationStats

PackageInfo

Statistics about a single stubs package in typeshed.

Attributes:

Name Type
package_name str
stub_distribution_name str
upstream_url str | None
completeness_level CompletenessLevel
extra_description str | None
number_of_lines int
package_status PackageStatus
upload_status UploadStatus
stubtest_settings StubtestSettings
pyright_setting PyrightSetting
annotation_stats AnnotationStats

PackageName: TypeAlias = str module-attribute


PackageStatus

The various states of freshness/staleness a stubs package can be in.

Members:

Name Description
STDLIB These are typeshed's stubs for the standard library. Typeshed's stdlib stubs are generally fairly up to date, and are tested against all currently supported Python versions in typeshed's CI.
NOT_ON_PYPI The runtime package that these stubs are for doesn't exist on PyPI, so whether or not these stubs are up to date or not is unknown.
OBSOLETE The runtime package has added inline type hints; these typeshed stubs are now obsolete.
NO_LONGER_UPDATED The runtime package has not added type hints, but these stubs are no longer updated by typeshed for some other reason.
OUT_OF_DATE These stubs may be out of date. In typeshed's CI, stubtest tests these stubs against an older version of the runtime package than the latest that's available.
UP_TO_DATE These stubs should be fairly up to date. In typeshed's CI, stubtest tests these stubs against the latest version of the runtime package that's available.

PyrightSetting

The various possible pyright settings typeshed uses in CI.

Members:

Name Description
ENTIRELY_EXCLUDED All files in this stubs package are excluded from the pyright check in typeshed's CI.
SOME_FILES_EXCLUDED Some files in this stubs package are excluded from the pyright check in typeshed's CI.
NOT_STRICT This package is tested with pyright in typeshed's CI, but all files in this stubs package are excluded from the stricter pyright settings.
STRICT_ON_SOME_FILES Some files in this stubs package are tested with the stricter pyright settings in typeshed's CI; some are excluded from the stricter settings.
STRICT All files in this stubs package are tested with the stricter pyright settings in typeshed's CI.

StubtestSettings

Information on the settings under which stubtest is run on a certain package.

Attributes:

Name Type
strictness StubtestStrictness
platforms list[str]
allowlist_length int

StubtestStrictness

Enumeration of the various possible settings typeshed uses for stubtest in CI.

Members:

Name Description
SKIPPED Stubtest is skipped in typeshed's CI for this package.
MISSING_STUBS_IGNORED The --ignore-missing-stub stubtest setting is used in typeshed's CI.
ERROR_ON_MISSING_STUB Objects missing from the stub cause stubtest to emit an error in typeshed's CI.

UploadStatus

Whether or not a stubs package is currently uploaded to PyPI.

Members:

Name Description
UPLOADED These stubs are currently uploaded to PyPI.
NOT_CURRENTLY_UPLOADED These stubs are not currently uploaded to PyPI.

gather_annotation_stats_on_file(path)

Gather annotation stats on a single typeshed stub file.

Parameters:

Name Type Description Default
path Path | str

The location of the file to be analysed.

required

Returns:

Type Description
AnnotationStats

An AnnotationStats object containing data about the annotations in the file.

Examples:

>>> from typeshed_stats.gather import (
...     tmpdir_typeshed,
...     gather_annotation_stats_on_file,
... )
>>> with tmpdir_typeshed() as typeshed:
...     stats_on_functools = gather_annotation_stats_on_file(
...         typeshed / "stdlib" / "functools.pyi"
...     )
>>> type(stats_on_functools)
<class 'typeshed_stats.gather.AnnotationStats'>
>>> stats_on_functools.unannotated_parameters
0

gather_annotation_stats_on_package(package_name, *, typeshed_dir)

Aggregate annotation stats on a typeshed stubs package.

Parameters:

Name Type Description Default
package_name PackageName

The name of the stubs package to analyze.

required
typeshed_dir Path | str

A path pointing to the location of a typeshed directory in which to find the stubs package source.

required

Returns:

Type Description
AnnotationStats

An AnnotationStats object containing data about the annotations in the package.

Examples:

>>> from typeshed_stats.gather import (
...     tmpdir_typeshed,
...     gather_annotation_stats_on_package,
... )
>>> with tmpdir_typeshed() as typeshed:
...     mypy_extensions_stats = gather_annotation_stats_on_package(
...         "mypy-extensions", typeshed_dir=typeshed
...     )
>>> type(mypy_extensions_stats)
<class 'typeshed_stats.gather.AnnotationStats'>
>>> mypy_extensions_stats.unannotated_parameters
0

gather_stats_on_file(file_path, *, typeshed_dir)

Gather stats on a single .pyi file in typeshed.

Parameters:

Name Type Description Default
file_path Path | str

A path pointing to the file on which to gather stats. This can be an absolute path, or a path relative to the typeshed_dir argument.

required
typeshed_dir Path | str

A path pointing to the overall typeshed directory. This can be an absolute or relative path.

required

Returns:

Type Description
FileInfo

An instance of the FileInfo class.

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, gather_stats_on_file
>>> with tmpdir_typeshed() as typeshed:
...     # Paths can be relative to typeshed_dir
...     functools_info = gather_stats_on_file(
...         "stdlib/functools.pyi", typeshed_dir=typeshed
...     )
...     # Absolute paths are also fine
...     stubs_dir = typeshed / "stubs"
...     requests_api_info = gather_stats_on_file(
...         stubs_dir / "requests/requests/api.pyi", typeshed_dir=typeshed
...     )
...     # Gather per-file stats on a directory
...     markdown_per_file_stats = [
...         gather_stats_on_file(module, typeshed_dir=typeshed)
...         for module in (stubs_dir / "Markdown").rglob("*.pyi")
...     ]
>>> type(functools_info)
<class 'typeshed_stats.gather.FileInfo'>
>>> functools_info.parent_package
'stdlib'
>>> functools_info.file_path.as_posix()
'stdlib/functools.pyi'
>>> requests_api_info.parent_package
'requests'
>>> requests_api_info.file_path.as_posix()
'stubs/requests/requests/api.pyi'

gather_stats_on_multiple_packages(packages=None, *, typeshed_dir)

Concurrently gather statistics on multiple packages.

Note

This function calls asyncio.run to start an asyncio event loop. It is therefore not suitable to be called from inside functions that are themselves called as part of an asyncio event loop.

Parameters:

Name Type Description Default
packages Iterable[str] | None

An iterable of package names to be analysed, or None. If None, defaults to all third-party stubs, plus the stubs for the stdlib.

None
typeshed_dir Path | str

The path to a local clone of typeshed.

required

Returns:

Type Description
Sequence[PackageInfo]

A sequence of PackageInfo objects. Each PackageInfo object contains information representing an analysis of a certain stubs package in typeshed.

Examples:

>>> from typeshed_stats.gather import (
...     PackageInfo,
...     tmpdir_typeshed,
...     gather_stats_on_multiple_packages,
... )
>>> with tmpdir_typeshed() as typeshed:
...     infos = gather_stats_on_multiple_packages(
...         ["stdlib", "aiofiles", "boto"], typeshed_dir=typeshed
...     )
>>> [info.package_name for info in infos]
['aiofiles', 'boto', 'stdlib']
>>> all(type(info) is PackageInfo for info in infos)
True

gather_stats_on_package(package_name, *, typeshed_dir, session=None) async

Gather miscellaneous statistics about a single stubs package in typeshed.

Note

This function calls get_package_status(), which makes network requests to PyPI. See the docs on get_package_status() for details.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to gather statistics on.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, in which the source code for the stubs package can be found.

required
session ClientSession | None

An aiohttp.ClientSession instance, to be used for making a network requests, or None. If None is provided for this argument, a new aiohttp.ClientSession instance will be created to make the network request.

None

Returns:

Type Description
PackageInfo

An instance of the PackageInfo class.

Examples:

>>> import asyncio
>>> from typeshed_stats.gather import tmpdir_typeshed, gather_stats_on_package
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_info = asyncio.run(
...         gather_stats_on_package("stdlib", typeshed_dir=typeshed)
...     )
>>> stdlib_info.package_name
'stdlib'
>>> stdlib_info.stubtest_settings.strictness
StubtestStrictness.ERROR_ON_MISSING_STUB
>>> type(stdlib_info.number_of_lines) is int and stdlib_info.number_of_lines > 0
True

get_completeness_level(package_name, *, typeshed_dir)

Determine whether a stubs package is explicitly marked as 'partial'.

See PEP 561 for an elaboration of what it means for a stub to be marked as partial.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the partial status for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the partial status.

required

Returns:

Type Description
CompletenessLevel

A member of the CompletenessLevel enumeration (see the docs on CompletenessLevel for details).

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_completeness_level
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_completeness = get_completeness_level(
...         "stdlib", typeshed_dir=typeshed
...     )
...     requests_completeness = get_completeness_level(
...         "requests", typeshed_dir=typeshed
...     )
>>> requests_completeness
CompletenessLevel.COMPLETE
>>> help(_)
Help on CompletenessLevel in module typeshed_stats.gather:

CompletenessLevel.COMPLETE
    The stubs package should cover the entire API at runtime

>>> stdlib_completeness
CompletenessLevel.STDLIB

get_number_of_lines_of_file(file_path)

Get the total number of lines of code for a single stub file in typeshed.

Parameters:

Name Type Description Default
file_path Path | str

A path to the file to analyse.

required

Returns:

Type Description
int

The number of lines of code the stubs file contains, excluding empty lines.


get_package_extra_description(package_name, *, typeshed_dir)

Get the "extra description" of the package given in the METADATA.toml file.

Each typeshed package comes with a METADATA.toml file, containing various useful pieces of information about the package.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the extra description for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the description.

required

Returns:

Type Description
str | None

The "extra description" of the package given in the METADATA.toml file, if one is given, else None.

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_package_extra_description
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_description = get_package_extra_description(
...         "stdlib", typeshed_dir=typeshed
...     )
...     protobuf_description = get_package_extra_description(
...         "protobuf", typeshed_dir=typeshed
...     )
>>> stdlib_description is None
True
>>> isinstance(protobuf_description, str)
True

get_package_size(package_name, *, typeshed_dir)

Get the total number of lines of code for a stubs package in typeshed.

Parameters:

Name Type Description Default
package_name PackageName

The name of the stubs package to find the line number for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory in which to find the stubs package.

required

Returns:

Type Description
int

The number of lines of code the stubs package contains, excluding empty lines.

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_package_size
>>> with tmpdir_typeshed() as typeshed:
...     mypy_extensions_size = get_package_size(
...         "mypy-extensions", typeshed_dir=typeshed
...     )
>>> type(mypy_extensions_size) is int and mypy_extensions_size > 0
True

get_package_status(package_name, *, typeshed_dir, session=None) async

Retrieve information on how up to date a stubs package is.

If stubtest tests these stubs against the latest version of the runtime package in typeshed's CI, it's a fair bet that the stubs are relatively up to date. If stubtest tests these stubs against an older version, however, the stubs may be out of date.

Note

This function makes network requests to PyPI in order to determine what the latest version of the runtime is, and then compares this against the metadata of the stubs package.

Parameters:

Name Type Description Default
package_name PackageName

The name of the stubs package to analyze.

required
typeshed_dir Path | str

A path pointing to a typeshed directory in which to find the stubs package.

required
session ClientSession | None

An aiohttp.ClientSession instance, to be used for making a network requests, or None. If None is provided for this argument, a new aiohttp.ClientSession instance will be created to make the network request.

None

Returns:

Type Description
PackageStatus

A member of the PackageStatus enumeration (see the docs on PackageStatus for details).

Examples:

>>> import asyncio
>>> from typeshed_stats.gather import tmpdir_typeshed, get_package_status
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_status = asyncio.run(
...         get_package_status("stdlib", typeshed_dir=typeshed)
...     )
...     gdb_status = asyncio.run(get_package_status("gdb", typeshed_dir=typeshed))
>>> stdlib_status
PackageStatus.STDLIB
>>> help(_)
Help on PackageStatus in module typeshed_stats.gather:

PackageStatus.STDLIB
    These are typeshed's stubs for the standard library. Typeshed's stdlib stubs are generally fairly up to date, and are tested against all currently supported Python versions in typeshed's CI.

>>> gdb_status
PackageStatus.NOT_ON_PYPI

get_pyright_setting_for_package(package_name, *, typeshed_dir)

Get the settings typeshed uses in CI when pyright is run on a certain package.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the pyright setting for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the pyright setting.

required

Returns:

Type Description
PyrightSetting

A member of the PyrightSetting enumeration (see the docs on PyrightSetting for details).

Examples:

>>> from typeshed_stats.gather import (
...     tmpdir_typeshed,
...     get_pyright_setting_for_package,
... )
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_setting = get_pyright_setting_for_package(
...         "stdlib", typeshed_dir=typeshed
...     )
>>> stdlib_setting
PyrightSetting.STRICT_ON_SOME_FILES
>>> help(_)
Help on PyrightSetting in module typeshed_stats.gather:

PyrightSetting.STRICT_ON_SOME_FILES
    Some files in this stubs package are tested with the stricter pyright settings in typeshed's CI; some are excluded from the stricter settings.

get_pyright_setting_for_path(file_path, *, typeshed_dir)

Get the settings typeshed uses in CI when pyright is run on a certain path.

Parameters:

Name Type Description Default
file_path Path | str

The path to query.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the pyright setting.

required

Returns:

Type Description
PyrightSetting

A member of the PyrightSetting enumeration (see the docs on PyrightSetting for details).


get_stub_distribution_name(package_name, *, typeshed_dir)

Get the name this stubs package is uploaded to PyPI under.

For the vast majority of packages in typeshed, this is types-{runtime-name}, but there may be a small number of packages that are uploaded under nonstandard names to PyPI.

Parameters:

Name Type Description Default
package_name PackageName

The (runtime) name of the package to find the stub distribution name for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the information.

required

Returns:

Type Description
str

The name under which the stubs package is uploaded to PyPI.

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_stub_distribution_name
>>> with tmpdir_typeshed() as typeshed:
...     requests_stub_dist_name = get_stub_distribution_name(
...         "requests", typeshed_dir=typeshed
...     )
...     pika_stub_dist_name = get_stub_distribution_name(
...         "pika", typeshed_dir=typeshed
...     )
>>> requests_stub_dist_name
'types-requests'
>>> pika_stub_dist_name
'types-pika-ts'

get_stubtest_allowlist_length(package_name, *, typeshed_dir)

Get the number of unique "allowlist entries" typeshed uses in CI when stubtest is run on a certain package.

An allowlist entry indicates a place in the stub where stubtest emits an error, but typeshed has chosen to silence the error rather than "fix it". Not all allowlist entries are bad: sometimes there are good reasons to ignore an error emitted by stubtest.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the number of allowlist entries for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the number of stubtest allowlist entries.

required

Returns:

Type Description
int

The number of allowlist entries for that package.

int

Duplicate entries in allowlists are removed.

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_stubtest_allowlist_length
>>> with tmpdir_typeshed() as typeshed:
...     num_stdlib_allows = get_stubtest_allowlist_length(
...         "stdlib", typeshed_dir=typeshed
...     )
...     num_requests_allows = get_stubtest_allowlist_length(
...         "requests", typeshed_dir=typeshed
...     )
>>> type(num_stdlib_allows)
<class 'int'>
>>> num_stdlib_allows > 0 and num_requests_allows > 0
True

get_stubtest_platforms(package_name, *, typeshed_dir)

Get the list of platforms on which stubtest is run in typeshed's CI.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the stubtest setting for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the stubtest configuration.

required

Returns:

Type Description
list[str]

A list of strings describing platforms stubtest is run on. The names correspond to the platform names given by sys.platform at runtime.

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_stubtest_platforms
>>> with tmpdir_typeshed() as typeshed:
...     pywin_platforms = get_stubtest_platforms("pywin32", typeshed_dir=typeshed)
>>> pywin_platforms
['win32']

get_stubtest_settings(package_name, *, typeshed_dir)

Get the stubtest settings for a certain stubs package in typeshed.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the stubtest settings for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the stubtest settings.

required

Returns:

Type Description
StubtestSettings

An instance of the StubtestSettings class.


get_stubtest_strictness(package_name, *, typeshed_dir)

Get the setting typeshed uses in CI when stubtest is run on a certain package.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the stubtest setting for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the stubtest setting.

required

Returns:

Type Description
StubtestStrictness

A member of the StubtestStrictness enumeration (see the docs on StubtestStrictness for details).

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_stubtest_strictness
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_setting = get_stubtest_strictness("stdlib", typeshed_dir=typeshed)
...     gdb_setting = get_stubtest_strictness("RPi.GPIO", typeshed_dir=typeshed)
>>> stdlib_setting
StubtestStrictness.ERROR_ON_MISSING_STUB
>>> help(_)
Help on StubtestStrictness in module typeshed_stats.gather:

StubtestStrictness.ERROR_ON_MISSING_STUB
    Objects missing from the stub cause stubtest to emit an error in typeshed's CI.

>>> gdb_setting
StubtestStrictness.SKIPPED

get_upload_status(package_name, *, typeshed_dir)

Determine whether a certain package is currently uploaded to PyPI.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the upload status for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the upload status.

required

Returns:

Type Description
UploadStatus

A member of the UploadStatus enumeration (see the docs on UploadStatus for details).

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_upload_status
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_setting = get_upload_status("stdlib", typeshed_dir=typeshed)
...     requests_setting = get_upload_status("requests", typeshed_dir=typeshed)
>>> stdlib_setting
UploadStatus.NOT_CURRENTLY_UPLOADED
>>> help(_)
Help on UploadStatus in module typeshed_stats.gather:

UploadStatus.NOT_CURRENTLY_UPLOADED
    These stubs are not currently uploaded to PyPI.

>>> requests_setting
UploadStatus.UPLOADED

get_upstream_url(package_name, *, typeshed_dir)

Get the URL for the source code of the runtime package these stubs are for.

Parameters:

Name Type Description Default
package_name PackageName

The name of the package to find the upstream URL for.

required
typeshed_dir Path | str

A path pointing to a typeshed directory, from which to retrieve the URL.

required

Returns:

Type Description
str | None

The upstream URL (as a string). If no URL is listed in the stubs package's METADATA.toml file, returns None.

Examples:

>>> from typeshed_stats.gather import tmpdir_typeshed, get_upstream_url
>>> with tmpdir_typeshed() as typeshed:
...     stdlib_url = get_upstream_url("stdlib", typeshed_dir=typeshed)
...     requests_url = get_upstream_url("requests", typeshed_dir=typeshed)
...     hdbcli_url = get_upstream_url("hdbcli", typeshed_dir=typeshed)
>>> stdlib_url
'https://github.com/python/cpython'
>>> requests_url
'https://github.com/psf/requests'
>>> hdbcli_url is None
True

tmpdir_typeshed()

Clone typeshed into a tempdir, then yield a Path pointing to it.

A context manager.

Yields:

Type Description
Path

A Path pointing to a tempdir with a clone of typeshed inside.