Tanguy Le Carrour <tanguy@bioneland.org> writes:

> * gnu/packages/python-xyz.scm (python-flake8-pyi): New variable.

[...]
  
> +(define-public python-flake8-pyi
> +  (package
> +    (name "python-flake8-pyi")
> +    (version "20.5.0")
> +    (source
> +     (origin
> +       (method url-fetch)
> +       (uri (pypi-uri "flake8-pyi" version))
> +       (sha256
> +        (base32
> +         "1zpq4s9kp8w95pccmhhyyx1ff2zhnidcf1zb3xs46lzcx9plvnzk"))))
> +    (build-system python-build-system)
> +    (propagated-inputs
> +     `(("python-attrs" ,python-attrs)
> +       ("python-flake8" ,python-flake8)
> +       ("python-pyflakes" ,python-pyflakes)))
> +    (home-page "https://github.com/ambv/flake8-pyi")
> +    (synopsis
> +      "A plugin for Flake8 that provides specializations for type hinting stub files.")

No punctuation or article (you probably got that by now).  :-)

> +    (description
> +     "A plugin for Flake8 that provides specializations for type hinting stub files,
> +especially interesting for linting typeshed.  1) Adds the .pyi extension to
> +the default value of the --filename command-line argument to Flake8.  This means
> +stubs are linted by default with this plugin enabled, without needing to explicitly list
> +every file.  2) Modifies PyFlakes runs for .pyi files to defer checking type annotation
> +expressions after the entire file has been read.  This enables support for first-class
> +forward references that stub files use.")

And full sentence, i.e. "This package contains a plugin ...".  Also
@file{.pyi}.

The 1) and 2) reads "weird" to me, maybe they can be cut off and just
use the text?  Or perhaps they should be on separate lines, perhaps with
@enumerate or similar?