Vendor typeguard 2.13.3 (#142)

* Vendor typeguard 2.13.3 in its original form.

This package will however need to be edited to work in parallel with other installations of typeguard.

* Inject code theoretically compatible with another injection from another typeguard version.

* Allow typeguard to be installed at same time.

If typeguard is not installed separately, process the packages listed under --typeguard-packages using the vendored typeguard. Otherwise, process only what is listed in --stp-typeguard-packages and leave the --typeguard-packages option to be processed by the installed version of typeguard. To avoid the ambiguity of double processing, an exception is raised if a package is listed in both options.

* Remove namespace changes to vendored code, keep only the updated import change.

This partially reverts commit ea01297.

* Use external typeguard if compatible

* Remove accidentally commited config file

* Add excludes to all static tool configs

* Update github build workflow

* Fix type annotation incompatible with Python 3.8

* Add some more tests to the github build workflow

* Update reference to typechecked decorator in notebook

* Update docs to recommend safer --stp-typeguard-packages pytest option

* add documentation

---------

Co-authored-by: nanne-aben <[email protected]>

.github/workflows/build.yml

@@ -21,6 +21,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
           pip install -r requirements-dev.txt
+          pip install -e .
       - name: Lint with isort
         run: isort --check .
       - name: Lint with black
@@ -33,7 +34,7 @@ jobs:
         run: mypy .
       - name: Test with pytest
         run: |
-          coverage run -m pytest --typeguard-packages=strictly_typed_pandas,tests
+          coverage run -m pytest --stp-typeguard-packages=tests
           coverage report -m
       - name: Run notebooks
         run: |
@@ -42,3 +43,15 @@ jobs:
             cp $FILE .
             jupyter nbconvert --to notebook $BASE --execute
           done
+      - name: Run pytest with --typeguard-packages for backwards compatibility
+        run: |
+          pytest --typeguard-packages=tests
+      - name: Run pytest with compatible typeguard installed
+        run: |
+          pip install typeguard==2.13.2
+          pytest --typeguard-packages=tests
+          pytest --stp-typeguard-packages=tests
+      - name: Run pytest with incompatible typeguard installed
+        run: |
+          pip install typeguard==4.1.5
+          pytest --stp-typeguard-packages=tests

.pre-commit-config.yaml

@@ -1,3 +1,4 @@
+exclude: '^strictly_typed_pandas/_vendor'
 repos:
 - repo: local
   hooks:
@@ -25,7 +26,7 @@ repos:
     types: [python]
   - id: pytest
     name: pytest
-    entry: coverage run -m pytest --typeguard-packages=strictly_typed_pandas,tests
+    entry: coverage run -m pytest --typeguard-packages=tests
     language: system
     types: [python]
     pass_filenames: false

README.rst

@@ -35,11 +35,11 @@ Where `DataSet`:
 
 The `DataSet[Schema]` annotations are compatible with:
     * `mypy` for type checking during linting-time (i.e. while you write your code).
-    * `typeguard` for type checking during run-time (i.e. while you run your unit tests).
+    * `typeguard` (<v3.0) for type checking during run-time (i.e. while you run your unit tests).
 
 To get the most out of `strictly_typed_pandas`, be sure to:
     * set up `mypy` in your IDE.
-    * run your unit tests with `pytest --typeguard-packages=foo.bar` (where `foo.bar` is your package name).
+    * run your unit tests with `pytest --stp-typeguard-packages=foo.bar` (where `foo.bar` is your package name).
 
 Installation
 ============

docs/source/getting_started.ipynb

@@ -423,7 +423,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from typeguard import typechecked\n",
+    "from strictly_typed_pandas.typeguard import typechecked\n",
     "\n",
     "\n",
     "@typechecked\n",
@@ -452,7 +452,7 @@
    "source": [
     "Alright, we now caught the error dead in its tracks! \n",
     "\n",
-    "We can improve this with one more step: instead of adding the `@typechecked` decorator to every function by hand (which could be error prone), `typeguard` can do this automatically when running the unit tests. To do this, simply run your unit tests using `pytest --typeguard-packages=foo.bar` (where `foo.bar` is your package name)\n",
+    "We can improve this with one more step: instead of adding the `@typechecked` decorator to every function by hand (which could be error prone), `typeguard` can do this automatically when running the unit tests. To do this, simply run your unit tests using `pytest --stp-typeguard-packages=foo.bar` (where `foo.bar` is your package name)\n",
     "\n",
     "## Conclusions\n",
     "\n",
@@ -500,7 +500,7 @@
     "\n",
     "* set up `mypy` in your IDE.\n",
     "\n",
-    "* run your unit tests with `pytest --typeguard-packages=foo.bar` (where `foo.bar` is your package name)."
+    "* run your unit tests with `pytest --stp-typeguard-packages=foo.bar` (where `foo.bar` is your package name)."
    ]
   },
   {

docs/source/index.rst

@@ -11,5 +11,6 @@
    getting_started
    advanced
    deepdive_into_dtypes
+   typeguard
    api
    contributing

docs/source/typeguard.md

@@ -0,0 +1,98 @@
+# Typeguard
+
+We use typeguard in strictly typed pandas to as an additional runtime check, as described in earlier sections. As per typeguard 3.0.0, a number of breaking changes were introduced, which we couldn't reconcile with strictly typed pandas. Other packages that depend on typeguard 2.13.3 are in a similar situation.
+
+However, the `typeguard<=2.13.3` requirement became problematic over time, as it meant people could not use strictly typed pandas together with packages that depend on `typeguard>=3.0.0`. For this reason, we have decided to vendor typeguard in `strictly_typed_pandas==0.2.0`, meaning that we include typeguard within the strictly typed pandas code base, rather than having it as a dependency. 
+
+In this document, we outline how you can use typeguard with `strictly_typed_pandas>=0.2.0`.
+
+## With typeguard 2.13.3 (backwards compatibility)
+
+To support backwards compatibility, we allow you to use typeguard with `strictly_typed_pandas>=0.2.0` by simply installing `typeguard==2.13.3`, without any other changes required. This can be done by running:
+
+```bash
+pip install typeguard==2.13.3
+```
+
+You can use all functionality from typeguard as before:
+
+### Decorator
+
+```python
+from typeguard import typechecked
+
+@typechecked
+def foo(df: DataSet[Person]) -> DataSet[Person]:
+    ...
+```
+
+### Import hook
+
+```python
+from typeguard import install_import_hook
+
+install_import_hook('my_app')
+from my_app import some_module  # import only AFTER installing the hook, or it won't take effect
+```
+
+### Pytest plugin
+
+```bash
+pytest --typeguard-packages=my_app
+```
+
+## With the vendored typeguard version (recommended)
+
+We recommend that you use the vendored typeguard version, as it is the most future-proof solution. 
+
+### Decorator
+
+You can use the vendored version as follows:
+```python
+from strictly_typed_pandas.typeguard import typechecked
+
+@typechecked
+def foo(df: DataSet[Person]) -> DataSet[Person]:
+    ...
+```
+
+If you also want to use a second typeguard version in your project (e.g. `typeguard>=3.0.0`), you can pip install that version and then you can use the following:
+```python
+from typeguard import typechecked as typechecked_vanilla
+
+@typechecked_vanilla
+def foo(a: int) -> int:
+    ...
+```
+Note that `@typechecked_vanilla` will not work with strictly typed pandas types; you can only use it for projects that do not use strictly typed pandas.
+
+### Import hook
+
+The import hook is currently not supported in the vendored version. It should be possible to add support for this, but we have not done so yet. If you would like to use the import hook, please open an issue.
+
+Of course, you can still use the import hook with the vanilla version, as follows:
+```python
+from typeguard import install_import_hook
+
+install_import_hook('my_app')
+from my_app import some_module  # import only AFTER installing the hook, or it won't take effect
+```
+
+### Pytest plugin
+
+To use the vendored version of the pytest plugin, you can use the following:
+```bash
+pytest --stp-typeguard-packages=my_app
+```
+
+If you also want to use a second typeguard version in your project (e.g. `typeguard>=3.0.0`), you can pip install that version and then you can use the following:
+```bash
+pytest --typeguard-packages=my_other_app
+```
+
+You can also use them at the same time:
+```bash
+pytest --stp-typeguard-packages=my_app --typeguard-packages=my_other_app
+```
+
+Please don't define the same package in both flags, this will raise an error.

pyproject.toml

@@ -1,7 +1,19 @@
 [tool.black]
 line-length = 100
+force-exclude = ["strictly_typed_pandas/_vendor/*"]
 
 [tool.isort]
 profile = "black"
 line_length = 100
+extend_skip_glob = ["strictly_typed_pandas/_vendor/*"]
 
+[tool.mypy]
+exclude = ['strictly_typed_pandas/_vendor/.*']
+
+[[tool.mypy.overrides]]
+module="strictly_typed_pandas._vendor.*"
+follow_imports = 'skip'
+
+[[tool.mypy.overrides]]
+module="typeguard"
+ignore_missing_imports = true

requirements.txt

@@ -1,4 +1,3 @@
 numpy<=1.26.3
 pandas<=2.1.4
 pandas-stubs<=2.1.4.231227
-typeguard<=2.13.3

setup.py

@@ -28,4 +28,9 @@ def get_long_description():
     version_config=True,
     setup_requires=["setuptools-git-versioning"],
     package_data={"strictly_typed_pandas": ["py.typed"]},
+    entry_points={
+        "pytest11": [
+            "strictly_typed_pandas = strictly_typed_pandas.pytest_plugin",
+        ],
+    },
 )

strictly_typed_pandas/_vendor/typeguard-2.13.3.dist-info/INSTALLER

@@ -0,0 +1 @@
+pip

strictly_typed_pandas/_vendor/typeguard-2.13.3.dist-info/LICENSE

@@ -0,0 +1,19 @@
+This is the MIT license: http://www.opensource.org/licenses/mit-license.php
+
+Copyright (c) Alex Grönholm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

strictly_typed_pandas/_vendor/typeguard-2.13.3.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: typeguard
+Version: 2.13.3
+Summary: Run-time type checker for Python
+Home-page: UNKNOWN
+Author: Alex Grönholm
+Author-email: [email protected]
+License: MIT
+Project-URL: Documentation, https://typeguard.readthedocs.io/en/latest/
+Project-URL: Change log, https://typeguard.readthedocs.io/en/latest/versionhistory.html
+Project-URL: Source code, https://github.com/agronholm/typeguard
+Project-URL: Issue tracker, https://github.com/agronholm/typeguard/issues
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.5.3
+License-File: LICENSE
+Provides-Extra: doc
+Requires-Dist: sphinx-rtd-theme ; extra == 'doc'
+Requires-Dist: sphinx-autodoc-typehints (>=1.2.0) ; extra == 'doc'
+Provides-Extra: test
+Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: typing-extensions ; extra == 'test'
+Requires-Dist: mypy ; (platform_python_implementation != "PyPy") and extra == 'test'
+
+.. image:: https://travis-ci.com/agronholm/typeguard.svg?branch=master
+  :target: https://travis-ci.com/agronholm/typeguard
+  :alt: Build Status
+.. image:: https://coveralls.io/repos/agronholm/typeguard/badge.svg?branch=master&service=github
+  :target: https://coveralls.io/github/agronholm/typeguard?branch=master
+  :alt: Code Coverage
+.. image:: https://readthedocs.org/projects/typeguard/badge/?version=latest
+  :target: https://typeguard.readthedocs.io/en/latest/?badge=latest
+
+This library provides run-time type checking for functions defined with
+`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ argument (and return) type annotations.
+
+Four principal ways to do type checking are provided, each with its pros and cons:
+
+#. the ``check_argument_types()`` and ``check_return_type()`` functions:
+
+   * debugger friendly (except when running with the pydev debugger with the C extension installed)
+   * does not work reliably with dynamically defined type hints (e.g. in nested functions)
+#. the ``@typechecked`` decorator:
+
+   * automatically type checks yields and sends of returned generators (regular and async)
+   * adds an extra frame to the call stack for every call to a decorated function
+#. the stack profiler hook (``with TypeChecker('packagename'):``) (deprecated):
+
+   * emits warnings instead of raising ``TypeError``
+   * requires very few modifications to the code
+   * multiple TypeCheckers can be stacked/nested
+   * does not work reliably with dynamically defined type hints (e.g. in nested functions)
+   * may cause problems with badly behaving debuggers or profilers
+   * cannot distinguish between an exception being raised and a ``None`` being returned
+#. the import hook (``typeguard.importhook.install_import_hook()``):
+
+   * automatically annotates classes and functions with ``@typechecked`` on import
+   * no code changes required in target modules
+   * requires imports of modules you need to check to be deferred until after the import hook has
+     been installed
+   * may clash with other import hooks
+
+See the documentation_ for further instructions.
+
+.. _documentation: https://typeguard.readthedocs.io/en/latest/
+
+

strictly_typed_pandas/_vendor/typeguard-2.13.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+typeguard-2.13.3.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+typeguard-2.13.3.dist-info/LICENSE,sha256=YWP3mH37ONa8MgzitwsvArhivEESZRbVUu8c1DJH51g,1130
+typeguard-2.13.3.dist-info/METADATA,sha256=rrszCBWMnpJt2j9D8QqPgS1kQUFdTu5exwvCVkB0cIY,3591
+typeguard-2.13.3.dist-info/RECORD,,
+typeguard-2.13.3.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typeguard-2.13.3.dist-info/WHEEL,sha256=ewwEueio1C2XeHTvT17n8dZUJgOvyCWCt0WVNLClP9o,92
+typeguard-2.13.3.dist-info/entry_points.txt,sha256=uBVT0tmiav9LH4v6cq0GIl7TYz07TqFHniXP6zCfHbY,48
+typeguard-2.13.3.dist-info/top_level.txt,sha256=4z28AhuDodwRS_c1J_l8H51t5QuwfTseskYzlxp6grs,10
+typeguard/__init__.py,sha256=7LyyccpyAXgyd3WO2j1GXCWDdyasGjmA9v9DeydHR70,49186
+typeguard/__pycache__/__init__.cpython-311.pyc,,
+typeguard/__pycache__/importhook.cpython-311.pyc,,
+typeguard/__pycache__/pytest_plugin.cpython-311.pyc,,
+typeguard/importhook.py,sha256=nv3-M2SZ4cHxJBakslR_7w73YpT6Lit67txi7H7-xGM,5601
+typeguard/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typeguard/pytest_plugin.py,sha256=T1wfao9RMZ-fQ31bA_gmkoOtHEmXk3o1s0Nty5ZrFnw,917

strictly_typed_pandas/_vendor/typeguard-2.13.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.37.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

strictly_typed_pandas/_vendor/typeguard-2.13.3.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+typeguard = typeguard.pytest_plugin
+

strictly_typed_pandas/_vendor/typeguard-2.13.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+typeguard