Metadata-Version: 2.4
Name: gmpy2-stubs
Version: 2.2.1.2
Summary: Type stubs (PEP 561) for gmpy2 2.2.1: GMP, MPFR, and MPC support.
Author-email: David Osipov <personal@david-osipov.vision>
Maintainer-email: David Osipov <personal@david-osipov.vision>
License: MIT
Project-URL: Homepage, https://github.com/DavidOsipov/gmpy2-stubs
Project-URL: Issues, https://github.com/DavidOsipov/gmpy2-stubs/issues
Project-URL: Source, https://github.com/DavidOsipov/gmpy2-stubs
Project-URL: Security Policy, https://github.com/DavidOsipov/gmpy2-stubs/blob/main/SECURITY.md
Project-URL: Personal Website, https://david-osipov.vision
Project-URL: LinkedIn, https://www.linkedin.com/in/david-osipov
Project-URL: GitHub Profile, https://github.com/DavidOsipov
Project-URL: ISNI, https://isni.org/isni/000000051802960X
Project-URL: ORCID, https://orcid.org/0009-0005-2713-9242
Project-URL: Telegram, https://telegram.me/david_osipov
Project-URL: Signal, https://signal.me/#eu/d68l1UjrWlGVRzbfkVM1bvQMNqCqiae9GM86P_af8ZK2o5E5YSNKbL4MyM9y-2WH
Keywords: gmpy2,stubs,type hints,typing,mypy,pyright,static analysis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Stubs Only
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gmpy2-stubs

[![PyPI version](https://badge.fury.io/py/gmpy2-stubs.svg?icon=si%3Apython&icon_color=%23ffffff)](https://badge.fury.io/py/gmpy2-stubs)
![PyPI - Downloads](https://img.shields.io/pypi/dm/gmpy2-stubs)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

Type stubs for the [gmpy2](https://pypi.org/project/gmpy2/) library (version 2.2.1).

gmpy2 is a C-coded Python extension module that supports multiple-precision arithmetic. It provides access to the GMP (GNU Multiple Precision Arithmetic Library), MPFR (Multiple-Precision Floating-Point Reliable Library), and MPC (Multiple-Precision Complex Library) libraries. gmpy2 itself does *not* include type hints. This package provides them.

## IMPORTANT CAVEAT: gmpy2 Runtime Behavior

**Please be aware:** The underlying `gmpy2` library, which these stubs provide type hints for, **can crash the Python interpreter in case of memory allocation failure.** This is due to the memory management behavior of the wrapped GMP library.

To mitigate this risk when using `gmpy2` in your code:
*   **Estimate the potential size of calculation results.**
*   **Prevent or handle calculations that could exhaust available system memory.**

Failure to account for this may lead to unexpected program termination.

## Installation

```bash
pip install gmpy2-stubs
```

or, if you'd like to use a specific version:

```bash
pip install gmpy2-stubs==2.2.1.2
```

## Usage

These stubs are automatically used by static type checkers like [mypy](https://mypy-lang.org/) and [pyright](https://github.com/microsoft/pyright) when you have both `gmpy2` and `gmpy2-stubs` installed. You do *not* need to import anything from `gmpy2-stubs` directly.

```python
import gmpy2

# Type hints are available here!
x = gmpy2.mpz(123)
y = gmpy2.sqrt(x)
print(y)
```

## Limitations: `inspect.signature()`

It's important to understand that these stubs are designed for *static* type checking.  They will *not* affect the behavior of runtime introspection tools like `inspect.signature()`.

gmpy2, like many C extension modules, does not provide complete runtime signature information.  The standard library's `inspect.signature()` function relies on information that is usually available for pure Python functions (like docstrings and argument annotations) but is often missing or incomplete for C extensions.

There have been discussions about improving this situation, including:

*   **gmpy2 issue #496:** [Type declarations to allow integration with type checking and linting tools](https://github.com/aleaxit/gmpy/issues/496) - Discusses the general problem and potential solutions (including this stub package!).
*   **CPython issue #121945:** [Use *.pyi stub files as source for the inspect.signature()](https://github.com/python/cpython/issues/121945) - A proposal to make `inspect.signature()` use stub files as a fallback, but this was **closed as not planned**.

Therefore, if you use `inspect.signature()` on gmpy2 functions, you will likely get a generic signature (e.g., `(*args, **kwargs)`) rather than a detailed one.  This is a limitation of the current Python introspection mechanisms, *not* a limitation of these stubs.  The stubs *will* provide full type information to static type checkers.

## Contributing

Contributions and improvements to these stubs are very welcome!  Please submit pull requests or open issues on the [GitHub repository](<YOUR GITHUB REPO URL HERE>).

## License

These stubs are licensed under the MIT License (see the `LICENSE` file). gmpy2 itself is licensed under the LGPLv3+ license.

## Author

David Osipov (personal@david-osipov.vision)

*   ISNI: [0000 0005 1802 960X](https://isni.org/isni/000000051802960X)
*   ORCID: [0009-0005-2713-9242](https://orcid.org/0009-0005-2713-9242)
*   PGP key: [https://openpgpkey.david-osipov.vision/.well-known/openpgpkey/david-osipov.vision/D3FC4983E500AC3F7F136EB80E55C4A47454E82E.asc](https://openpgpkey.david-osipov.vision/.well-known/openpgpkey/david-osipov.vision/D3FC4983E500AC3F7F136EB80E55C4A47454E82E.asc)
*   PGP fingerprint: D3FC 4983 E500 AC3F 7F13 6EB8 0E55 C4A4 7454 E82E
*   Website: [https://david-osipov.vision](https://david-osipov.vision)
*   LinkedIn: [https://www.linkedin.com/in/david-osipov/](https://www.linkedin.com/in/david-osipov/)

## Acknowledgements

Thanks to the gmpy2 developers for creating this powerful library!
