# Adding Type Annotations for Python's fspath Protocol

DevFeed: [Adding Type Annotations for Python's fspath Protocol](<https://devfeed.tech/articles/adding-type-annotations-for-fspath-38896.md>)

Original publisher: [Read original article](<http://neopythonic.blogspot.com/2016/05/adding-type-annotations-for-fspath.html>)

Author: Guido van Rossum (noreply@blogger.com)

Published: 2016-05-18T14:06:00Z

Content type: article

Language: en

Sources: [Guido van Rossum](<https://devfeed.tech/sources/guido-van-rossum.md>)

Topics: [Python](<https://devfeed.tech/topics/python.md>), [Protocol (disambiguation)](<https://devfeed.tech/topics/protocol.md>), [file](<https://devfeed.tech/topics/file.md>), [generics](<https://devfeed.tech/topics/generics.md>)

Tags: [file](<https://devfeed.tech/tags/file.md>), [generics](<https://devfeed.tech/tags/generics.md>), [protocol](<https://devfeed.tech/tags/protocol.md>), [python](<https://devfeed.tech/tags/python.md>)

## AI overview

This blog post explains how to add type annotations for Python 3.6's filesystem path protocol, including __fspath__(), os.fspath(), pathlib.Path, and os.DirEntry. It demonstrates generic and overloaded type definitions for os.scandir() and related standard-library stubs.

## Source excerpt

Type annotations for fspath Python 3.6 will have a new dunder protocol, __fspath__() , which should be supported by classes that represent filesystem paths. Example of such classes are the pathlib.Path family and os.DirEntry (returned by os.scandir() ). You can read more about this protocol in the brand new PEP 519. In this blog post I'm going to discuss how we would add type annotations for these additions to the standard library. I'm making frequent use of AnyStr , a quite magical type variable predefined in the typing module. If you're not familiar with it, I recommend reading my blog post about AnyStr . You may also want to read up on generics in PEP 484 (or read mypy's docs on the subject). Adding os.scandir() to the stubs for os.py For practice, let's see if we can add something to the stub file for os.py. As of this writing there's no typeshed information for os.scandir() , which I think is a shame. I think the following will do nicely. Note how we only define DirEntry and scandir() for Python versions >= 3.5. (Mypy doesn't support this yet, but it will soon, and the example here still works -- it just doesn't realize scandir() is only available in Python 3.5.) This could be added to the end of stdlib/3/os/__init__.pyi: from typing import Generic, AnyStr, overload, Iterator if sys.version_info >= (3, 5): class DirEntry(Generic[AnyStr]): name = ... # type: AnyStr path = ... # type: AnyStr def inode(self) -> int: ... def is_dir(self, *, follow_symlinks: bool = ...) -> bool: ... def is_file(self, *, follow_symlinks: bool = ...) -> bool: ... def is_symlink(self) -> bool: ... def stat(self, *, follow_symlinks: bool = ...) -> stat_result: ... @overload def scandir() -> Iterator[DirEntry[str]]: ... @overload def scandir(path: AnyStr) -> Iterator[DirEntry[AnyStr]]: ... Deconstructing this a bit, we see a generic class (that's what the Generic[AnyStr] base class means) and an overloaded function. The scandir() definition uses @overload because it can also be called wit