initial copilot-instructions.md with type hints

Author: Justine Wezenaar

.github/copilot-instructions.md

@@ -0,0 +1,71 @@
+# Pandas Copilot Instructions
+
+## Project Overview
+`pandas` is an open source, BSD-licensed library providing high-performance, easy-to-use data structures and data analysis tools for the Python programming language.
+
+<!-- TODO: Add Sections for ## Root Folders and ## Core Architecture (pandas/ dir ) -->
+
+## Type Hints
+
+pandas strongly encourages the use of PEP 484 style type hints. New development should contain type hints and pull requests to annotate existing code are accepted as well!
+
+### Style Guidelines
+
+Type imports should follow the from `typing import ...` convention. Your code may be automatically re-written to use some modern constructs (e.g. using the built-in `list` instead of `typing.List`) by the pre-commit checks.
+
+In some cases in the code base classes may define class variables that shadow builtins. This causes an issue as described in Mypy 1775. The defensive solution here is to create an unambiguous alias of the builtin and use that without your annotation. For example, if you come across a definition like
+
+```
+class SomeClass1:
+    str = None
+```
+
+The appropriate way to annotate this would be as follows
+
+```
+str_type = str
+
+class SomeClass2:
+    str: str_type = None
+```
+In some cases you may be tempted to use `cast` from the typing module when you know better than the analyzer. This occurs particularly when using custom inference functions. For example
+
+```
+from typing import cast
+
+from pandas.core.dtypes.common import is_number
+
+def cannot_infer_bad(obj: Union[str, int, float]):
+
+    if is_number(obj):
+        ...
+    else:  # Reasonably only str objects would reach this but...
+        obj = cast(str, obj)  # Mypy complains without this!
+        return obj.upper()
+```
+The limitation here is that while a human can reasonably understand that `is_number` would catch the `int` and `float` types mypy cannot make that same inference just yet (see mypy  #5206. While the above works, the use of `cast` is strongly discouraged. Where applicable a refactor of the code to appease static analysis is preferable.)
+
+```
+def cannot_infer_good(obj: Union[str, int, float]):
+
+    if isinstance(obj, str):
+        return obj.upper()
+    else:
+        ...
+```
+With custom types and inference this is not always possible so exceptions are made, but every effort should be exhausted to avoid `cast` before going down such paths.
+
+### pandas-specific types
+
+Commonly used types specific to pandas will appear in pandas._typing and you should use these where applicable. This module is private for now but ultimately this should be exposed to third party libraries who want to implement type checking against pandas.
+
+For example, quite a few functions in pandas accept a `dtype` argument. This can be expressed as a string like `"object"`, a `numpy.dtype` like `np.int64` or even a pandas `ExtensionDtype` like `pd.CategoricalDtype`. Rather than burden the user with having to constantly annotate all of those options, this can simply be imported and reused from the pandas._typing module
+
+```
+from pandas._typing import Dtype
+
+def as_type(dtype: Dtype) -> ...:
+    ...
+```
+
+This module will ultimately house types for repeatedly used concepts like “path-like”, “array-like”, “numeric”, etc… and can also hold aliases for commonly appearing parameters like `axis`. Development of this module is active so be sure to refer to the source for the most up to date list of available types.