Add how to install and use section to README

[rowoflo]

I am getting the common mypy error for my project.

error: Skipping analyzing "scipy.spatial.transform": module is installed, but missing library stubs or py.typed marker  [import]
note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
Found 1 error in 1 file (checked 3 source files)

I see that the scipy.spatial.transform library stubs are provided with this project. But I don't know how to install them.

I tried installing with pip in my 3.8.13 virtual environment

pip install git+https://github.com/microsoft/python-type-stubs.git 

but I get this error

Looking in indexes: https://pypi.org/simple, https://download.pytorch.org/whl/cu113
Collecting git+https://github.com/microsoft/python-type-stubs.git
  Cloning https://github.com/microsoft/python-type-stubs.git to /tmp/pip-req-build-8p0xrczh
  Running command git clone --filter=blob:none --quiet https://github.com/microsoft/python-type-stubs.git /tmp/pip-req-build-8p0xrczh
  Resolved https://github.com/microsoft/python-type-stubs.git to commit f3c68e1cf40ef6687e6d961489ced0da6516c77a
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  error: subprocess-exited-with-error

  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [14 lines of output]
      error: Multiple top-level packages discovered in a flat-layout: ['cv2', 'vispy', 'pygame', 'sklearn', 'skimage', 'lightgbm', 'networkx', 'pendulum', 'tenacity', 'openpyxl', 'matplotlib', 'sqlalchemy'].

      To avoid accidental inclusion of unwanted files or directories,
      setuptools will not proceed with this build.

      If you are trying to create a single distribution with multiple packages
      on purpose, you should not rely on automatic discovery.
      Instead, consider the following options:

      1. set up custom discovery (`find` directive with `include` or `exclude`)
      2. use a `src-layout`
      3. explicitly set `py_modules` or `packages` with a list of names

      To find more information, look for "package discovery" on setuptools docs.
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: subprocess-exited-with-error

× Getting requirements to build wheel did not run successfully.
│ exit code: 1
╰─> See above for output.

note: This error originates from a subprocess, and is likely not a problem with pip.

What is the recommended way to install python-type-stubs and are there any pointers for using it?

It would be great if this information could be added to the README.

[debonte]

@rowoflo, which type checker are you using?

[rowoflo]

I am using mypy.

[tmke8]

I don't think the project is meant to be installed. But if you want to install it, you can add your own setup.py to it.

If you only want the scipy stubs, it would be something like:

"""Package setup"""
from setuptools import setup

with open("README.md", "r") as fh:
    long_description = fh.read()

setup(
    name="python-type-stubs",
    version="0.1.0",
    url="https://github.com/microsoft/python-type-stubs",
    author="microsoft",
    description="A set of type stubs for popular Python packages.",
    license="MIT License",
    long_description=long_description,
    long_description_content_type="text/markdown",
    package_data={
        "scipy-stubs": ["*.pyi", "**/*.pyi", "**/**/*.pyi", "**/**/**/*.pyi"],
    },
    packages=[
        "scipy-stubs",
    ],
    python_requires=">=3.8",
    zip_safe=False,
)

If you fork the repository, add this setup.py and then install it with pip install git+https://github.com... then it should work.

[debonte]

These stubs are shipped with Pylance and we use this repo as a way to collaborate with users on them.

@tmke8 is right that these stubs aren't pip installable at the moment, though we have toyed with the idea, especially as a way for Pyright users to more easily consume them. If any Pyright users happen upon this issue, see the recently added instructions here.

[thezealousfool]

Anyone coming here looking for instructions to use these stubs with mypy:

1. Clone this repo - I did it to ~/.config/mypy/python-type-stubs:

mkdir -p ~/.config/mypy/python-type-stubs && git clone https://github.com/microsoft/python-type-stubs.git ~/.config/mypy/python-type-stubs

2. Just export an environment variable in .bashrc, or anywhere else as per to preference:

export MYPYPATH=~/.config/mypy/python-type-stubs/

To confirm that things should work run ls $MYPYPATH and you should see the different project folders:

cv2         networkx  pygame         skimage     sympy-stubs  transformers-stubs  CODE_OF_CONDUCT.md  pyproject.toml          SECURITY.md
lightgbm    openpyxl  scipy-stubs    sklearn     tenacity     utils               CONTRIBUTING.md     pyrighttestconfig.json
matplotlib  pendulum  seaborn-stubs  sqlalchemy  tests        vispy               LICENSE             README.md

[debonte]

@Avasam just addressed this in #338. Please take a look at the new README section and let us know if it works for you.