{"id":13542285,"url":"https://github.com/JetBrains/python-skeletons","last_synced_at":"2025-04-02T09:33:29.516Z","repository":{"id":857733,"uuid":"12543092","full_name":"JetBrains/python-skeletons","owner":"JetBrains","description":"The python-skeltons repo is deprecated: use PEP 484 and Typeshed instead","archived":true,"fork":false,"pushed_at":"2021-11-20T10:41:04.000Z","size":224,"stargazers_count":134,"open_issues_count":0,"forks_count":52,"subscribers_count":60,"default_branch":"master","last_synced_at":"2025-02-19T13:47:12.563Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JetBrains.png","metadata":{"files":{"readme":"README-obsolete.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-09-02T15:23:03.000Z","updated_at":"2024-08-29T07:23:54.000Z","dependencies_parsed_at":"2022-08-06T10:01:11.465Z","dependency_job_id":null,"html_url":"https://github.com/JetBrains/python-skeletons","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetBrains%2Fpython-skeletons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetBrains%2Fpython-skeletons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetBrains%2Fpython-skeletons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JetBrains%2Fpython-skeletons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JetBrains","download_url":"https://codeload.github.com/JetBrains/python-skeletons/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246789318,"owners_count":20834274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T10:01:04.050Z","updated_at":"2025-04-02T09:33:28.932Z","avatar_url":"https://github.com/JetBrains.png","language":"Python","funding_links":[],"categories":["Python","Python  ##"],"sub_categories":[],"readme":"_The python-skeletons repository is *deprecated*. Use PEP 484 and Typeshed\ninsetead._\n\n\n\nPython skeletons are Python files that contain API definitions of existing\nlibraries extended for static analysis tools.\n\nRationale\n---------\n\nPython is a dynamic language less suitable for static code analysis than static\nlanguages like C or Java. Although Python static analysis tools can extract\nsome information from Python source code without executing it, this information\nis often very shallow and incomplete.\n\nDynamic features of Python are very useful for user code. But using these\nfeatures in APIs of third-party libraries and the standard library is not\nalways a good idea. Tools (and users, in fact) need clear definitions of APIs.\nOften library API definitions are quite static and easy to grasp (defined\nusing `class`, `def`), but types of function parameters and return values\nusually are not specified. Sometimes API definitions involve metaprogramming.\n\nAs there is not enough information in API definition code of libraries,\ndevelopers of static analysis tools collect extended API data themselves and\nstore it in their own formats. For example, PyLint uses imperative AST\ntransformations of API modules in order to extend them with hard-coded data.\nPyCharm extends APIs via its proprietary database of declarative type\nannotations. The absence of a common extended API information format makes it\nhard for developers and users of tools to collect and share data.\n\n\nProposal\n--------\n\nThe proposal is to create a common database of extended API definitions as a\ncollection of Python files called skeletons. Static analysis tools already\nunderstand Python code, so it should be easy to start extracting API\ndefinitions from these Python skeleton files. Regular function and class\ndefinitions can be extended with additional docstrings and decorators, e.g. for\nproviding types of function parameters and return values. Static analysis tools\nmay use a subset of information contained in skeleton files needed for their\noperation. Using Python files instead of a custom API definition format will\nalso make it easier for users to populate the skeletons database.\n\nDeclarative Python API definitions for static analysis tools cannot cover all\ndynamic tricks used in real APIs of libraries: some of them still require\nlibrary-specific code analysis. Nevertheless the skeletons database is enough\nfor many libraries.\n\nThe proposed [python-skeletons](https://github.com/JetBrains/python-skeletons)\nrepository is hosted on GitHub.\n\n\nConventions\n-----------\n\nSkeletons should contain syntactically correct Python code, preferably compatible\nwith Python 2.6-3.3.\n\nSkeletons should respect [PEP-8](http://www.python.org/dev/peps/pep-0008/) and\n[PEP-257](http://www.python.org/dev/peps/pep-0257/) style guides.\n\nIf you need to reference the members of the original module of a skeleton, you\nshould import it explicitly. For example, in a skeleton for the `foo` module:\n\n```python\nimport foo\n\n\nclass C(foo.B):\n    def bar():\n        \"\"\"Do bar and return Bar.\n\n        :rtype: foo.Bar\n        \"\"\"\n        return foo.Bar()\n```\nModules can be referenced in docstring without explicit imports.\n\nThe body of a function in a skeleton file should consist of a single `return`\nstatement that returns a simple value of the declared return type (e.g. `0`\nfor `int`, `False` for `bool`, `Foo()` for `Foo`). If the function returns\nsomething non-trivial, its may consist of a `pass` statement.\n\n\n### Types\n\nThere is no standard notation for specifying types in Python code. We would\nlike this standard to emerge, see the related work below.\n\nThe current understanding is that a standard for optional type annotations in\nPython could use the syntax of function annotations in Python 3 and decorators\nas a fallback in Python 2. The type system should be relatively simple, but it\nhas to include parametric (generic) types for collections and probably more.\n\nAs a temporary solution, we propose a simple way of specifying types in\nskeletons using Sphinx docstrings using the following notation:\n\n    Foo                # Class Foo visible in the current scope\n    x.y.Bar            # Class Bar from x.y module\n    Foo | Bar          # Foo or Bar\n    (Foo, Bar)         # Tuple of Foo and Bar\n    list[Foo]          # List of Foo elements\n    dict[Foo, Bar]     # Dict from Foo to Bar\n    T                  # Generic type (T-Z are reserved for generics)\n    T \u003c= Foo           # Generic type with upper bound Foo\n    Foo[T]             # Foo parameterized with T\n    (Foo, Bar) -\u003e Baz  # Function of Foo and Bar that returns Baz\n\nThere are several shortcuts available:\n\n    unknown            # Unknown type\n    None               # type(None)\n    string             # Py2: str | unicode, Py3: str\n    bytestring         # Py2: str | unicode, Py3: bytes\n    bytes              # Py2: str, Py3: bytes\n    unicode            # Py2: unicode, Py3: str\n\nThe syntax is a subject to change. It is almost compatible to Python (except\nfunction types), but its semantics differs from Python (no `|`, no implicitly\nvisible names, no generic types). So you cannot use these expressions in\nPython 3 function annotations.\n\nIf you want to create a parameterized class, you should define its parameters\nin the mock return type of a constructor:\n\n```python\nclass C(object):\n    \"\"\"Some collection C that can contain values of T.\"\"\"\n\n    def __init__(self, value):\n        \"\"\"Initialize C.\n\n        :type value: T\n        :rtype: C[T]\n        \"\"\"\n        pass\n\n    def get(self):\n        \"\"\"Return the contained value.\n\n        :rtype: T\n        \"\"\"\n        pass\n```\n\n\n### Versioning\n\nThe recommended way of checking the version of Python is:\n\n```python\nimport sys\n\n\nif sys.version_info \u003e= (2, 7) and sys.version_info \u003c (3,):\n    def from_27_until_30():\n        pass\n```\n\nA skeleton should document the most recently released version of a library. Use\ndeprecation warnings for functions that have been removed from the API.\n\nSkeletons for built-in symbols is an exception. There are two modules:\n`__builtin__` for Python 2 and `builtins` for Python 3.\n\n\nRelated Work\n------------\n\nThe JavaScript community is also interested in formalizing API definitions and\nspecifying types. They have come up with several JavaScript dialects that\nsupport optional types: TypeScript, Dart. There is a JavaScript initiative\nsimilar to the proposed Python skeletons called\n[DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped). The idea is\nto use TypeScript API stubs for various JavaScript libraries.\n\nThere are many approaches to specifying types in Python, none of them is widely\nadopted at the moment:\n\n* A series of old (2005) posts by GvR:\n  [1](http://www.artima.com/weblogs/viewpost.jsp?thread=85551),\n  [2](http://www.artima.com/weblogs/viewpost.jsp?thread=86641),\n  [3](http://www.artima.com/weblogs/viewpost.jsp?thread=87182)\n* String-based [python-rightarrow](https://github.com/kennknowles/python-rightarrow)\n  library\n* Expression-based [typeannotations](https://github.com/ceronman/typeannotations)\n  library for Python 3\n* [mypy](http://www.mypy-lang.org/) Python dialect\n* [pytypes](https://github.com/pytypes/pytypes): Optional typing for Python proposal\n* [Proposal: Use mypy syntax for function annotations](https://mail.python.org/pipermail/python-ideas/2014-August/028618.html) by GvR\n\nSee also the notes on function annotations in\n[PEP-8](http://www.python.org/dev/peps/pep-0008/).\n\n\nPyCharm / IntelliJ\n------------------\n\nPyCharm 3 and the Python plugin 3.x for IntelliJ can extract the following\ninformation from the skeletons:\n\n* Parameters of functions and methods\n* Return types and parameter types of functions and methods\n* Types of assignment targets\n* Extra module members\n* Extra class members\n* TODO\n\nPyCharm 3 comes with a snapshot of the Python skeletons repository (Python\nplugin 3.0.1 for IntelliJ still doesn't include this repository). You\n**should not** modify it, because it will be updated with the PyCharm / Python\nplugin for IntelliJ installation. If you want to change the skeletons, clone\nthe skeletons GitHub repository into your PyCharm/IntelliJ config directory:\n\n```bash\ncd \u003cconfig directory\u003e\ngit clone https://github.com/JetBrains/python-skeletons.git\n```\n\nwhere `\u003cconfig directory\u003e` is:\n\n* PyCharm\n    * Mac OS X: `~/Library/Preferences/PyCharmXX`\n    * Linux: `~/.PyCharmXX/config`\n    * Windows: `\u003cUser home\u003e\\.PyCharmXX\\config`\n* IntelliJ\n    * Mac OS X: `~/Library/Preferences/IntelliJIdeaXX`\n    * Linux: `~/.IntelliJIdeaXX/config`\n    * Windows: `\u003cUser home\u003e\\.IntelliJIdeaXX\\config`\n\nPlease send your PyCharm/IntelliJ-related bug reports and feature requests to\n[PyCharm issue tracker](https://youtrack.jetbrains.com/issues/PY).\n\n\nFeedback\n--------\n\nIf you want to contribute, send your pull requests to the Python skeletons\nrepository on GitHub. Please make sure, that you follow the conventions above.\n\nUse [code-quality](http://mail.python.org/mailman/listinfo/code-quality)\nmailing list to discuss Python skeletons.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJetBrains%2Fpython-skeletons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJetBrains%2Fpython-skeletons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJetBrains%2Fpython-skeletons/lists"}