René's URL Explorer Experiment


Title: More robust docstring support · Issue #1840 · python/mypy · GitHub

Open Graph Title: More robust docstring support · Issue #1840 · python/mypy

X Title: More robust docstring support · Issue #1840 · python/mypy

Description: Hi, I was perusing the mypy repo and I discovered that mypy can parse docstrings. That's great! The support, however, is currently pretty basic. For starters, mypy currently only supports the google standard. From looking at the code, my...

Open Graph Description: Hi, I was perusing the mypy repo and I discovered that mypy can parse docstrings. That's great! The support, however, is currently pretty basic. For starters, mypy currently only supports the googl...

X Description: Hi, I was perusing the mypy repo and I discovered that mypy can parse docstrings. That's great! The support, however, is currently pretty basic. For starters, mypy currently only supports the g...

Opengraph URL: https://github.com/python/mypy/issues/1840

X: @github

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"More robust docstring support","articleBody":"Hi,\nI was perusing the mypy repo and I discovered that mypy can parse docstrings.  That's great!  The support, however, is currently pretty basic.  For starters, mypy currently only supports the google standard.  From looking at the code, my instincts tell me that it might be somewhat fragile when exposed to a lot of real-world docstrings. \n\nFirst, my motivation for using docstrings to provide typing information is the following:\n1. Our company is already doing it throughout our codebase\n2. It's nice to include type info alongside the description of an argument, so even with PEP484 now in python 3.5, I'll continue to enforce the use of proper docstrings\n3. It works in both python 2 and 3\n\nAt this point, the python community semes to have settled on three docstring standards:\n- reStructuredText\n- google\n- numpy\n\nSphinx supports the first out-of-the-box, with the latter two supported via the very nifty [napolean extension](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/), which comes bundled in sphinx-contrib. It works by converting google and numpy docstrings into reStructuredText, which is then parsed using docutils.  Napolean is quite thorough, very battle-tested, and _just_ forgiving enough on docstring authors to be usable (supports `Return` as well as `Returns`, `Yield` as well as `Yields`).  Here's the [relevant code](https://bitbucket.org/birkenfeld/sphinx-contrib/src/197c13830fc8452c1438b00047945a172484c778/napoleon/sphinxcontrib/napoleon/docstring.py?at=default&fileviewer=file-view-default).  Also, handily enough, napolean already [supports PEP848-style type hints](https://bitbucket.org/birkenfeld/sphinx-contrib/issues/104/napoleon-conform-to-pep-484-type-hints-in).  It depends on `six` and [pockets](https://pypi.python.org/pypi/pockets/0.2) but the latter could easily be removed. \n\nMy thought was that we could leverage napolean and docutils to get rock-solid parsing of all 3 formats.  I'm assuming that adding dependencies to mypy is best avoided, so perhaps it can be installed as an `extras_require`.  e.g. `pip install mypy[docparse]`.  To avoid requiring all of sphinx, we could encourage the authors of napolean to provide the guts of their tool as a separate library (it used to be its own repo before it was consumed by sphinx-contrib). \n\nWhat do you think?  I'm glad to do all the work, including talking with the author of napolean, but I wanted to first see if this is something that the mypy team is open to.\n\nThanks!\n","author":{"url":"https://github.com/chadrik","@type":"Person","name":"chadrik"},"datePublished":"2016-07-09T22:27:46Z","url":"https://github.com/python/mypy/issues/1840"}

react-profiling0
react-import-mapreact,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322
route-pattern/_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format)
route-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:64624cdc-abd2-a85c-2099-b20df68b0dcf
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idA5AC:157BA1:B83F4A:F767AA:6B004DED
html-safe-nonce857d89ae1307bf5dab2b4c897180e67ee176d3c7e58620a9a250d8ef1045b08b
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBNUFDOjE1N0JBMTpCODNGNEE6Rjc2N0FBOjZCMDA0REVEIiwidmlzaXRvcl9pZCI6IjYxMjM3MDE2NzAyMDQ0Mjc3NTciLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmacf553fb785a676f324bc2351f3fa028d6507fbc50b698fa896525dda75ef04088
hovercard-subject-tagissue:164688654
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/mypy/1840/issue_layout
twitter:imagehttps://opengraph.githubassets.com/978c3b67c83a6b40a5392859a6a37e1a51513307eaf664132c98c56c60858ede/python/mypy/issues/1840
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/978c3b67c83a6b40a5392859a6a37e1a51513307eaf664132c98c56c60858ede/python/mypy/issues/1840
og:image:altHi, I was perusing the mypy repo and I discovered that mypy can parse docstrings. That's great! The support, however, is currently pretty basic. For starters, mypy currently only supports the googl...
og:image:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamechadrik
hostnamegithub.com
expected-hostnamegithub.com
Nonef9517bf360d46638a1e5e7daee7158842fe5ef43c9000afa0e127564a7c2f39b
turbo-cache-controlno-preview
go-importgithub.com/python/mypy git https://github.com/python/mypy.git
octolytics-dimension-user_id1525981
octolytics-dimension-user_loginpython
octolytics-dimension-repository_id7053637
octolytics-dimension-repository_nwopython/mypy
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id7053637
octolytics-dimension-repository_network_root_nwopython/mypy
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
releaseb27c5dde30676028abd5c5fc53ce5c9b625f8281
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/python/mypy/issues/1840#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython%2Fmypy%2Fissues%2F1840
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython%2Fmypy%2Fissues%2F1840
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=python%2Fmypy
Reloadhttps://github.com/python/mypy/issues/1840
Reloadhttps://github.com/python/mypy/issues/1840
Reloadhttps://github.com/python/mypy/issues/1840
pythonhttps://github.com/python
mypyhttps://github.com/python/mypy
Codehttps://github.com/python/mypy
Issues2.7k (2.7k)https://github.com/python/mypy/issues
Pull requests546 (546)https://github.com/python/mypy/pulls
Actionshttps://github.com/python/mypy/actions
Projectshttps://github.com/python/mypy/projects
Wikihttps://github.com/python/mypy/wiki
Security and qualityhttps://github.com/python/mypy/security
Insightshttps://github.com/python/mypy/insights
https://github.com/python/mypy
New issuehttps://github.com/login?return_to=https://github.com/python/mypy/issues/1840
New issuehttps://github.com/login?return_to=https://github.com/python/mypy/issues/1840
More robust docstring supporthttps://github.com/python/mypy/issues/1840#top
https://github.com/chadrik
chadrikhttps://github.com/chadrik
on Jul 9, 2016https://github.com/python/mypy/issues/1840#issue-164688654
napolean extensionhttps://sphinxcontrib-napoleon.readthedocs.io/en/latest/
relevant codehttps://bitbucket.org/birkenfeld/sphinx-contrib/src/197c13830fc8452c1438b00047945a172484c778/napoleon/sphinxcontrib/napoleon/docstring.py?at=default&fileviewer=file-view-default
supports PEP848-style type hintshttps://bitbucket.org/birkenfeld/sphinx-contrib/issues/104/napoleon-conform-to-pep-484-type-hints-in
pocketshttps://pypi.python.org/pypi/pockets/0.2
https://github.com/refi64
refi64https://github.com/refi64
on Jul 9, 2016https://github.com/python/mypy/issues/1840#issuecomment-231559452
Should we support type annotations in docstrings for Python 2 code? #612https://github.com/python/mypy/issues/612
Support annotations defined in docstrings #839https://github.com/python/mypy/issues/839
Supporting type from docstring  #1669https://github.com/python/mypy/issues/1669
https://github.com/chadrik
chadrikhttps://github.com/chadrik
on Jul 9, 2016https://github.com/python/mypy/issues/1840#issuecomment-231560588
https://github.com/chadrik
chadrikhttps://github.com/chadrik
on Jul 9, 2016https://github.com/python/mypy/issues/1840#issuecomment-231560899
https://github.com/gvanrossum
gvanrossumhttps://github.com/gvanrossum
on Jul 10, 2016https://github.com/python/mypy/issues/1840#issuecomment-231564751
https://github.com/chadrik
chadrikhttps://github.com/chadrik
on Jul 10, 2016https://github.com/python/mypy/issues/1840#issuecomment-231600391
in place of mypy.docstring.parse_docstringhttps://github.com/python/mypy/blob/master/mypy/parse.py#L865
https://github.com/gvanrossum
gvanrossumhttps://github.com/gvanrossum
on Jul 10, 2016https://github.com/python/mypy/issues/1840#issuecomment-231606687
…https://github.com/python/mypy/issues/1840
https://github.com/gvanrossum
gvanrossumhttps://github.com/gvanrossum
on Jul 10, 2016https://github.com/python/mypy/issues/1840#issuecomment-231607222
#1240https://github.com/python/mypy/issues/1240
gvanrossumhttps://github.com/gvanrossum
wontfixhttps://github.com/python/mypy/issues?q=state%3Aopen%20label%3A%22wontfix%22
on Jul 14, 2016https://github.com/python/mypy/issues/1840#event-723643880
https://github.com/gvanrossum
gvanrossumhttps://github.com/gvanrossum
on Jul 14, 2016https://github.com/python/mypy/issues/1840#issuecomment-232803177
gvanrossumhttps://github.com/gvanrossum
completedhttps://github.com/python/mypy/issues?q=is%3Aissue%20state%3Aclosed%20archived%3Afalse%20reason%3Acompleted
on Jul 14, 2016https://github.com/python/mypy/issues/1840#event-723644910
Sign up for freehttps://github.com/signup?return_to=https://github.com/python/mypy/issues/1840
Sign in to commenthttps://github.com/login?return_to=https://github.com/python/mypy/issues/1840
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.