python stub что это

Stubs

Create a stub file for your own implementation

Navigate to the directory where the target implementation resides. Select File | New from the main menu, then select Python File (alternatively, use the Alt+Insert shortcut).

In the New Python file dialog, select Python stub and specify the filename. The filename should be the same as the name of the implementation file.

Press Enter to complete the action.

For your convenience, you can create a separate directory to keep your stub and its implementation. This will help you reuse the stub for your other projects.

Create a stub file for the external implementation

You can create a stub file for some implementations that reside in the packages installed in your environments.

In the directory, recreate the hierarchy corresponding to the implementation package.

Within the created structure, navigate to the target directory and select File | New from the main menu, then select Python File (alternatively, use the Alt+Insert shortcut). In the New Python file dialog, select Python stub and specify the filename. Press Enter and the file will be created. You can put any other required files to the stub directory.

Navigate between a stub and its implementation

PyCharm shows an asterisk in the left gutter for those code elements that have stubs. Click the asterisk to jump between a stub and its implementation:

Reuse stubs

You can make your stubs accessible for your other PyCharm projects.

Inspect your project: the directory with the stub files is now marked as a library root.

Any time you will use this project interpreter to work with other projects, this stub library will be accessible through the path you have just added.

Install a stub package

For the more widely use, you can create a stub package and upload to the pypi repository. See more information in the Packaging Python Projects guide. With the PEP-561 support, you can install stubs packages for your project interpreter.

Install the package. If needed, click Manage repositories to add a repository where your stub packages reside.

Stub packages have a predefined name format, so type «-stubs» in the search field to discover them.

Click Install Package to complete installation.

Источник

Automatic stub generation (stubgen)В¶

A stub file (see PEP 484) contains only type hints for the public interface of a module, with empty function bodies. Mypy can use a stub file instead of the real implementation to provide type information for the module. They are useful for third-party modules whose authors have not yet added type hints (and when no stubs are available in typeshed) and C extension modules (which mypy can’t directly process).

Stubgen can generate this stub file based on the above file:

The command-line flags may change between releases.

Specifying what to stub¶

You can give stubgen paths of the source files for which you want to generate stubs:

Details of the options:

Generate a stub file for the given module. This flag may be repeated multiple times.

Stubgen will not recursively generate stubs for any submodules of the provided module.

Generate stubs for the given package. This flag maybe repeated multiple times.

Stubgen applies heuristics to avoid generating stubs for submodules that include tests or vendored third-party packages.

Specifying how to generate stubs¶

By default stubgen will try to import the target modules and packages. This allows stubgen to use runtime introspection to generate stubs for C extension modules and to improve the quality of the generated stubs. By default, stubgen will also use mypy to perform light-weight semantic analysis of any Python modules. Use the following flags to alter the default behavior:

Don’t perform semantic analysis of source files. This may generate worse stubs – in particular, some module, class, and function aliases may be represented as variables with the Any type. This is generally only useful if semantic analysis causes a critical mypy error.

Additional flags¶

Show help message and exit.

Run stubgen in Python 2 mode (the default is Python 3 mode).

If an exception was raised during stub generation, continue to process any remaining modules instead of immediately failing with an error.

Include definitions that are considered private in stubs (with names such as _foo with single leading underscore and no trailing underscores).

Don’t export all names imported from other modules within the same package. Instead, only export imported names that are not referenced in the module that contains the import.

Produce more verbose output.

Produce less verbose output.

Источник

Stub files¶

Creating a stub¶

Here is an overview of how to create a stub file:

Now you can access the module in mypy programs and type check code that uses the library. If you write a stub for a library module, consider making it available for other programmers that use mypy by contributing it back to the typeshed repo.

The following sections explain the kinds of type annotations you can use in your programs and stub files.

You may be tempted to point MYPYPATH to the standard library or to the site-packages directory where your 3rd party packages are installed. This is almost always a bad idea – you will likely get tons of error messages about code you didn’t write and that mypy can’t analyze all that well yet, and in the worst case scenario mypy may crash due to some construct in a 3rd party package that it didn’t expect.

Stub file syntax¶

Stub files are written in normal Python 3 syntax, but generally leaving out runtime logic like variable initializers, function bodies, and default arguments.

It is always legal to use Python 3 syntax in stub files, even when writing Python 2 code. The example above is a valid stub file for both Python 2 and 3.

Using stub file syntax at runtime¶

The recommended style is to use ellipses to do so, just like in stub files. It is also considered stylistically acceptable to throw a NotImplementedError in cases where the user of the code may accidentally call functions with no actual logic.

Источник

Abstract

PEP 484 introduced type hinting to Python, with goals of making typing gradual and easy to adopt. Currently, typing information must be distributed manually. This PEP provides a standardized means to leverage existing tooling to package and distribute type information with minimal work and an ordering for type checkers to resolve modules and collect this information for type checking.

Rationale

Currently, package authors wish to distribute code that has inline type information. Additionally, maintainers would like to distribute stub files to keep Python 2 compatibility while using newer annotation syntax. However, there is no standard method to distribute packages with type information. Also, if one wished to ship stub files privately the only method available would be via setting MYPYPATH or the equivalent to manually point to stubs. If the package can be released publicly, it can be added to typeshed [1]. However, this does not scale and becomes a burden on the maintainers of typeshed. In addition, it ties bug fixes in stubs to releases of the tool using typeshed.

PEP 484 has a brief section on distributing typing information. In this section [2] the PEP recommends using shared/typehints/pythonX.Y/ for shipping stub files. However, manually adding a path to stub files for each third party library does not scale. The simplest approach people have taken is to add site-packages to their MYPYPATH, but this causes type checkers to fail on packages that are highly dynamic (e.g. sqlalchemy and Django).

Definition of Terms

The definition of «MAY», «MUST», and «SHOULD», and «SHOULD NOT» are to be interpreted as described in RFC 2119.

«Distributions» are the packaged files which are used to publish and distribute a release. [3]

«Module» a file containing Python runtime code or stubbed type information.

«Package» a directory or directories that namespace Python modules. (Note the distinction between packages and distributions. While most distributions are named after the one package they install, some distributions install multiple packages.)

Specification

There are several motivations and methods of supporting typing in a package. This PEP recognizes three types of packages that users of typing wish to create:

This PEP aims to support all three scenarios and make them simple to add to packaging and deployment.

The two major parts of this specification are the packaging specifications and the resolution order for resolving module type information. The type checking spec is meant to replace the shared/typehints/pythonX.Y/ spec of PEP 484 [2].

New third party stub libraries SHOULD distribute stubs via the third party packaging methods proposed in this PEP in place of being added to typeshed. Typeshed will remain in use, but if maintainers are found, third party stubs in typeshed MAY be split into their own package.

Packaging Type Information

In order to make packaging and distributing type information as simple and easy as possible, packaging and distribution is done through existing frameworks.

Package maintainers who wish to support type checking of their code MUST add a marker file named py.typed to their package supporting typing. This marker applies recursively: if a top-level package includes it, all its sub-packages MUST support type checking as well. To have this file installed with the package, maintainers can use existing packaging options such as package_data in distutils, shown below.

Distutils option example:

For namespace packages (see PEP 420), the py.typed file should be in the submodules of the namespace, to avoid conflicts and for clarity.

This PEP does not support distributing typing information as part of module-only distributions or single-file modules within namespace packages.

The single-file module should be refactored into a package and indicate that the package supports typing as described above.

Stub-only Packages

For package maintainers wishing to ship stub files containing all of their type information, it is preferred that the *.pyi stubs are alongside the corresponding *.py files. However, the stubs can also be put in a separate package and distributed separately. Third parties can also find this method useful if they wish to distribute stub files. The name of the stub package MUST follow the scheme foopkg-stubs for type stubs for the package named foopkg. Note that for stub-only packages adding a py.typed marker is not needed since the name *-stubs is enough to indicate it is a source of typing information.

Third parties seeking to distribute stub files are encouraged to contact the maintainer of the package about distribution alongside the package. If the maintainer does not wish to maintain or package stub files or type information inline, then a third party stub-only package can be created.

For example, if the pentagon and hexagon are separate distributions installing within the namespace package shapes.polygons The corresponding types-only distributions should produce packages laid out as follows:

Type Checker Module Resolution Order

The following is the order in which type checkers supporting this PEP SHOULD resolve modules containing type information:

If typecheckers identify a stub-only namespace package without the desired module in step 3, they should continue to step 4/5. Typecheckers should identify namespace packages by the absence of __init__.pyi. This allows different subpackages to independently opt for inline vs stub-only.

Partial Stub Packages

Many stub packages will only have part of the type interface for libraries completed, especially initially. For the benefit of type checking and code editors, packages can be «partial». This means modules not found in the stub package SHOULD be searched for in parts four and five of the module resolution order above, namely inline packages and typeshed.

Type checkers should merge the stub package and runtime package or typeshed directories. This can be thought of as the functional equivalent of copying the stub package into the same directory as the corresponding runtime package or typeshed folder and type checking the combined directory structure. Thus type checkers MUST maintain the normal resolution order of checking *.pyi before *.py files.

If a stub package distribution is partial it MUST include partial\n in a py.typed file. For stub-packages distributing within a namespace package (see PEP 420), the py.typed file should be in the submodules of the namespace.

Type checkers should treat namespace packages within stub-packages as incomplete since multiple distributions may populate them. Regular packages within namespace packages in stub-package distributions are considered complete unless a py.typed with partial\n is included.

Implementation

The proposed scheme of indicating support for typing is completely backwards compatible, and requires no modification to package tooling. A sample package with inline types is available [typed_package], as well as a [stub_package]. A sample package checker [pkg_checker] which reads the metadata of installed packages and reports on their status as either not typed, inline typed, or a stub package.

The mypy type checker has an implementation of PEP 561 searching which can be read about in the mypy docs [4].

[numpy-stubs] is an example of a real stub-only package for the numpy distribution.

Acknowledgements

This PEP would not have been possible without the ideas, feedback, and support of Ivan Levkivskyi, Jelle Zijlstra, Nick Coghlan, Daniel F Moisset, Andrey Vlasovskikh, Nathaniel Smith, and Guido van Rossum.

Version History

References

Copyright

This document has been placed in the public domain.

The PSF

The Python Software Foundation is the organization behind Python. Become a member of the PSF and help advance the software and our mission.

Источник

python / typeshed Go PK Goto Github PK

Collection of library stubs for Python, with static types

License: Apache License 2.0

typeshed’s Introduction

Typeshed contains external type annotations for the Python standard library and Python builtins, as well as third party packages as contributed by people external to those projects.

This data can e.g. be used for static analysis, type checking or type inference.

Typeshed supports Python versions 2.7 and 3.6 and up.

These PyPI packages follow PEP 561 and are automatically released (multiple times a day, when needed) by typeshed internal machinery.

Type checkers should be able to use these stub packages when installed. For more details, see the documentation for your type checker.

The _typeshed package

typeshed includes a package _typeshed as part of the standard library. This package and its submodules contains utility types, but is not available at runtime. For more information about how to use this package, see the stdlib/_typeshed directory.

If you’ve run into behavior in the type checker that suggests the type stubs for a given library are incorrect or incomplete, we want to hear from you!

Our main forum for discussion is the project’s GitHub issue tracker. This is the right place to start a discussion of any of the above or most any other topic concerning the project.

If you have general questions about typing with Python, or you need a review of your type annotations or stubs outside of typeshed, head over to our discussion forum. For less formal discussion, try the typing chat room on gitter.im. Some typeshed maintainers are almost always present; feel free to find us there and we’re happy to chat. Substantive technical discussion will be directed to the issue tracker.

typeshed’s People

Contributors

Stargazers

Watchers

Forkers

typeshed’s Issues

No stubs for stdlib module «calendar»

Migrating stubs from other repositories

These may include sources like PyCharm, mypy, pytypedecl, etc. We may also want to formally review at least some of the stubs before committing to make sure that they conform to the typeshed conventions.

If the same stubs is available from multiple sources, we’d probably want to start with the most complete/precise ones. We also want to keep Python 2 and 3 stubs for each module reasonably similar, but this is not absolutely necessary.

Inherit from any in SimpleNamespace and threading.local stubs

I will create a pull request on Friday.

class instance has `__dict__`

is a valid python3 statement but mypy (more a typeshed issue I guess) gives me

But, it is wrong, as

Complete six.moves

There are a bunch of six.moves submodules (and other things) that aren’t supported yet because there are no stubs yet for the module to which they refer. We should remember to update six.moves whenever we add stubs for such a module.

Add Generator to typing.pyi

PEP 484 defines Generator, a subclass of Iterator that can be used as the return type for generators for which you want to use send() and/or get a return value (with yield from ). This needs to be added to the typing.pyi stubs. I’m not 100% sure that this won’t require changes to mypy, for which I added python/mypy#1011.

Why does mypy not treat DictReader as iterable?

I have cloned the latest git on mypy and I’m on master
Python 3.5.1

mypy says: error: Iterable expected in the ‘for row in reader’ line.

Potentially merge Python 2 and 3 stubs for many modules

We’d need to add aliases for string-like types such as str/bytes/unicode, and these would be different between Python 2 and 3. We’d need to decide where to define the type aliases, either in the stub of the module that uses them or in a shared typeshed-related (?) module that is only available as a stub.

Support partial/incomplete stubs

Maybe we should have a way of specifying a stub as (potentially) incomplete for libraries that are changing rapidly and there is no dedicated maintainer for the stub. In cases like this a type checker / inferencer would either treat all names as implicitly defined in the module (with type Any ), or it could parse the actual main Python implementation and merge the annotations from the stubs to the full module AST.

collections.deque is not recognised as MutableSequence

In Python 3.5.1, deque should be a MutableSequence (https://bugs.python.org/issue23704)
By mypy does not recognise it as such

error: Incompatible types in assignment (expression has type deque[None], variable has type MutableSequence[Any])

Stub versioning

Several people have expressed interest in versioning stub files.

Here are some reasons:

Create recommended process for notifying 3rd party package maintainers

Specify how to annotate variable types

We should probably have a single convention for attribute and module-level variable annotations that would at least be recommended (even if other ways would also work).

Here are some potential approaches:

Stub for flask

I could make one. Will work with @mitsuhiko to vet it.

Missing stub for «shelve»

# This is an autogenerated file. It serves as a starting point
# for a more percise manual annotation of this module.

invalid syntax in builtins

The PEP 484 section on stub files says that stub files have the same syntax as Python files. Typeshed conforms to this spec except in one place in builtins.pyi :

This is a «can’t assign to keyword» syntax error.

taskgen/decoder.py:2: error: No library stub file for module ‘dateutil’

i will try to do it.

stub for asyncio.coroutine incorrect

In PR #81, an incorrect stub was introduced for coroutine (see here) which breaks this mypy unit test, among others. I’m not sure why this wasn’t caught by CI.

A fix for this is blocking python/mypy#1218, which needs to update to the latest typeshed master.

Is anyone working on an sqlite3 stub?

It’s probably fairly hard to make a useful one, given how dynamic it is. 🙁

2.7 stub for Decimal is incomplete, incompatible with numbers.Number

Document version/system/implementation checks that tools might want to support

A tool takes as input a python version, host system, python implementation, and body of python code, and returns a set of errors. Some tools may also support querying the type of an expression (e.g. for autocompletion of its attributes in an IDE).

At the very least, most tools will want to support python2 vs python3 detection.

Here’s my list of branches that should be followed:

min/max are missing optional default keyword only argument

Add better readme

# TODO chain.from_Iterable

Is there any way to implement this currently? I find I run into it quite often.

stubs for 3rd party modules

I’d like to look into creating some stubs for various projects not owned by me. I know in PEP-0484 it says:

Note that stubs for a given package will not be included here without the explicit consent of the package owner.

I’m just looking for clarification about whether that specifically means that such stubs will only come from the package owner or if I (for example) would have to work it out with the package owner and then have the owner communicate that to Boss Of Typeshed.

Take a library that has multiple modules and packages. Should our pull request put all the stubs in a package named after the third party library and then have a structure in that package mirroring the structure of that third party library?

how to type check the xml element class

I have been adding type hints to the xml module on this branch. Now, the Element class has one mandatory param which shoud be a str or bytes. But at in the Comment function the Comment function itself is passed in instead, and then this is used later on to identify that an element is a comment. An interesting way of checking this imo, but is there any way of dealing with thisʔ Atm, this will just mean the xml module will fail its own type check.

Also, if this issue should have been raised elsewhere, let me know.

basestring doesn’t support any operations

Currently the basestring class is empty, but it should support all operations that both str and unicode support.

sqlalchemy stubs are incomplete and broken

There appear to be several missing modules, but other modules need to import them.

Come up with a way for a module to say «I don’t exist»

While tooling support isn’t there yet, there is a way for stubs to indicate «the module only contains this function on this platform/version/implementation», using if branches like:

However, there is no way to indicate the complete absence of a module based on such a condition.

This is needed for tools to be able to correctly handle code like:

While it would be possible to add an entirely new set of directories for platform and also for implementation, this would grow quite quickly

Let stubs files indicate their builtin nature.

The current builtins vs stdlib distinction is not useful for checking purposes, only for stub-maintenance purposes. Though even for that purpose, it is lacking for third-party modules, and also for modules within a package (example: lxml is a pure-python package, but lxml.etree is implemented in C. I’m not sure if there are any stdlib builtin modules within a package though).

This should support the usual version and implementation checks (e.g. PyPy uses pure-python modules for many of CPython’s builtin modules).

Implement json.pyi for Python’s stdlib

See python/typing#182 for the discussion. The resulting type of things should be JSONType = t.Union[str, int, float, bool, None, t.Dict[str, t.Any], t.List[Any]] (which should end up in Python 3.6: http://bugs.python.org/issue26396).

No stubs for mysql

Tornado module for Python 2.7 broken locally in tests

Running with Python 3.5.1 on OS X, I get:

Types that don’t exist under their inspected name

There are several (overlapping) cases:

In some cases, later python versions do add a name for the type, but since we need to support all of them, we can’t rely on that.

json’s stubs are incomplete

OOT until Nov 30th

I’ll be out of town until after Thanksgiving. I’ll look at any new pull requests and/or issues once I get back.

Help wanted: stubs needed for `six.moves`

Some of these might be implemented for the opposite python version, or located in the wrong module for the given version.

Move typeshed to some more official place like github.com/python

miniunittest.py:9: error: «unittest» has no attribute «assertListEqual»

os.path should use AnyStr, not unicode

runtests.py trips over sqlalchemy

Is sqlalchemy still broken, like #14 seems to imply? How come Travis isn’t yelling at us?

What if some versions of a library have inline stubs?

It would be good to create a convention for this, but I don’t know how. Maybe we could solve it with some path magic?

Constructor signature for built-in file class is wrong (2.7 only)

You should be able to write

argparse.Namespace is more complicated than it seems

This gives these errors:

Now, ideally there would be some kind of plugin that understands the parser specification. But I’d be happy if it just didn’t complain about using unknown attributes of Namespace objects, while still verifying that the caller indeed passes something of that type (so I don’t want to just use Any ).

How to specify constants of type NoneType?

PEP 484 says «By default, None is an invalid value for any type». However, in the Python standard library there are class-level and module-level constants that are legitimately None.

Should we allow these to be declared using e.g. something like

Add tests for stubs

print’s flush argument is missing from builtins, I’d like to add it

In Python 3.3 and later, I can write this code:

I’m familiar with doing pull requests, and I’d like to add information about new print signature to typeshed. However, before I do, I’d like to learn how to contribute. Currently there is this file: /builtins/3/builtins.pyi

So from what I understand, I would be creating /builtins/3.3/builtins.pyi and in there I would add:

in place of the old one:

. but what about everything else? Should I add all other updates to builtins.pyi between 3 and 3.3 before I request a pull?

`Reversible` should be covariant.

Otherwise Sequence cannot inherit from it with a covariant type variable.

no library stub file for standard library module ‘fileinput’

Recommend Projects

A declarative, efficient, and flexible JavaScript library for building user interfaces.

Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

TensorFlow

An Open Source Machine Learning Framework for Everyone

Django

The Web framework for perfectionists with deadlines.

A PHP framework for web artisans

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

Some thing interesting about web. New door for the world.

server

A server is a program made to process requests and deliver data to clients.

Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

Visualization

Some thing interesting about visualization, use data art

Some thing interesting about game, make everyone happy.

Recently View Projects

typeshed

Collection of library stubs for Python, with static types

Discord

dardandemiri.github.io

This is my personal website with some of my finished projects, my blogging activity and much more info’s about me. Please feel free to mail me for anything you want.

Источник