{"id":16463585,"url":"https://github.com/simon-ritchie/stubdoc","last_synced_at":"2025-07-06T21:06:23.188Z","repository":{"id":44134419,"uuid":"321323396","full_name":"simon-ritchie/stubdoc","owner":"simon-ritchie","description":null,"archived":false,"fork":false,"pushed_at":"2022-08-12T11:20:47.000Z","size":86,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-16T22:42:11.423Z","etag":null,"topics":["docstring","mypy","python","stub","stubs","typeannotations"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simon-ritchie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-14T11:13:22.000Z","updated_at":"2022-09-23T02:17:17.000Z","dependencies_parsed_at":"2022-08-31T02:00:18.175Z","dependency_job_id":null,"html_url":"https://github.com/simon-ritchie/stubdoc","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon-ritchie%2Fstubdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon-ritchie%2Fstubdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon-ritchie%2Fstubdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simon-ritchie%2Fstubdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simon-ritchie","download_url":"https://codeload.github.com/simon-ritchie/stubdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221849589,"owners_count":16891495,"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":["docstring","mypy","python","stub","stubs","typeannotations"],"created_at":"2024-10-11T11:14:53.666Z","updated_at":"2024-10-28T15:37:42.451Z","avatar_url":"https://github.com/simon-ritchie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# stubdoc\n\nstubdoc is a Python library that append docstring to stub files.\n\n# What problem will be solved by this library?\n\nmypy's stubgen command that create stub files does not append docstring. So if stub file exists and IDE prioritize stub's completion then docstring will not appear on IDE.\n\nSo that this library add docstring to stub files to display that.\n\nFor more mypy's stubgen command details, please see mypy documentation, [Automatic stub generation (stubgen)](https://mypy.readthedocs.io/en/stable/stubgen.html).\n\nFor example, suppose that the following code's module exists (`sample/sample.py`):\n\n```py\nfrom random import randint\n\nsample_int: int = 100\n\n\ndef sample_func(a: int, b: str) -\u003e bool:\n    \"\"\"\n    Lorem ipsum dolor sit amet, consectetur adipiscing elit,\n    ed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n\n    Parameters\n    ----------\n    a : int\n        Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n    b : str\n        ed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n\n    Returns\n    -------\n    c : bool\n        Ut enim ad minim veniam, quis nostrud exercitation.\n    \"\"\"\n    return True\n\n\nclass SampleClass:\n\n    def __init__(self) -\u003e None:\n        \"\"\"\n        Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n        \"\"\"\n\n    @property\n    def sample_property(self) -\u003e int:\n        \"\"\"\n        Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n\n        Returns\n        -------\n        d : int\n            ed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n        \"\"\"\n        return randint(0, 100)\n```\n\nmypy's stubgen command will generate stub files as follows (stubgen command will not add docstring):\n\n```py\nsample_int: int\n\ndef sample_func(a: int, b: str) -\u003e bool: ...\n\nclass SampleClass:\n    def __init__(self) -\u003e None: ...\n    @property\n    def sample_property(self) -\u003e int: ...\n```\n\nAnd then, this library's command will add the docstring to stub doc as follows, so IDE's code completion will show docstring:\n\n```py\nsample_int: int\n\ndef sample_func(a: int, b: str) -\u003e bool:\n    \"\"\"\n    Lorem ipsum dolor sit amet, consectetur adipiscing elit,\n    ed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n\n    Parameters\n    ----------\n    a : int\n        Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n    b : str\n        ed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n\n    Returns\n    -------\n    c : bool\n        Ut enim ad minim veniam, quis nostrud exercitation.\n    \"\"\"\n\nclass SampleClass:\n    def __init__(self) -\u003e None:\n        \"\"\"\n        Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n        \"\"\"\n    @property\n    def sample_property(self) -\u003e int:\n        \"\"\"\n        Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n\n        Returns\n        -------\n        d : int\n            ed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n        \"\"\"\n```\n\n# Installing\n\nInstallation via pip command is provided:\n\n```\n$ pip install stubdoc\n```\n\n# Dependencies\n\n- Supported Python 3.8 or later (tested on 3.8.5). Probably works on Python 3.6.x or later (but not tested).\n\n# Usage\n\nNotes: specified module need to be able to import. Stubdoc will replace paths to package path (e.g., 'sample/path.py' to 'sample.path'), so that paths argument can not be specified upper level directory or root directory (e.g., '/sample/path.py' or '../sample/path').\n\n```\nThis command will add docstring to stub file. Currently supported one-line stub implementation, like mypy's stubgen\ncommand, something as follows: def any_func(a: int, b: str) -\u003e None: ... If line break exists after colon, this\ncommand will not work correctly. Also not supported nested function, etc.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -m MODULE_PATH, --module_path MODULE_PATH\n                        Stub file's original module path. e.g., sample/path.py\n  -s STUB_PATH, --stub_path STUB_PATH\n                        Target stub file path. e.g., sample/path.pyi\n```\n\nCommand example:\n\n```\n$ stubdoc -m samples/sample.py -s out/samples/sample.pyi\n```\n\nor\n\n```\n$ stubdoc --module_path samples/sample.py --stub_path out/samples/sample.pyi\n```\n\nOr maybe Python interface is useful, like Django environment:\n\n```py\nfrom stubdoc import add_docstring_to_stubfile\n\nadd_docstring_to_stubfile(\n    original_module_path='sample/path.py',\n    stub_file_path='sample/path.pyi')\n```\n\n# Limitations\n\nThis library supported only one-line stub implementation, like this:\n\n```py\ndef sample_func(a: int, b: str) -\u003e bool: ...\n\nclass SampleClass:\n    def __init__(self) -\u003e None: ...\n    @property\n    def sample_property(self) -\u003e int: ...\n```\n\nNot supported line breaks after function's colon:\n\n```py\ndef sample_func(a: int, b: str) -\u003e bool:\n    ...\n\nclass SampleClass:\n    def __init__(self) -\u003e None:\n        ...\n    @property\n    def sample_property(self) -\u003e int:\n        pass\n```\n\nAlso not supported nested functions, like this (docstring will add to only top-level function):\n\n```py\ndef sample_func_1(a: int, b: str) -\u003e bool:\n    def sample_func_2(c: list) -\u003e None: ...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimon-ritchie%2Fstubdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimon-ritchie%2Fstubdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimon-ritchie%2Fstubdoc/lists"}