Metadata-Version: 2.4
Name: annotate
Version: 2.1.1
Summary: Decorator to set a function's __annotations__ like Py3.
Author-email: Adam Karpierz <adam@karpierz.net>
Maintainer-email: Adam Karpierz <adam@karpierz.net>
License-Expression: Zlib
Project-URL: Homepage, https://pypi.org/project/annotate/
Project-URL: Documentation, https://karpierz.github.io/annotate/
Project-URL: History, https://karpierz.github.io/annotate/CHANGES.html
Project-URL: Download, https://pypi.org/project/annotate/
Project-URL: Repository, https://github.com/karpierz/annotate
Project-URL: Tracker, https://github.com/karpierz/annotate/issues
Project-URL: Sponsoring, https://www.paypal.com/donate/?hosted_button_id=FX8L7CJUGLW7S
Keywords: annotate,typing,decorator
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: Polish
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4.0.0,>=3.10.0
Description-Content-Type: text/x-rst; charset=UTF-8
License-File: LICENSE
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: pkg-about>=2.1.0
Dynamic: license-file

annotate
========

Function annotations.

Overview
========

**@annotate**

| Decorator to set a function's __annotations__ like Py3.
| https://www.python.org/dev/peps/pep-3107/

`PyPI record`_.

`Documentation`_.

Examples
--------

.. code:: python

  from typing   import Optional, Tuple, Union, Sequence
  from annotate import annotate

  import jni

  from .lib         import cached
  from .jobjectbase import JObjectBase
  from .jclass      import JClass
  from .jobject     import JObject


  class JArray(JObjectBase):
      """Java Array"""

      @classmethod
      @annotate('JArray', size=Union[int, long])
      def newBooleanArray(cls, size):
          ...
      ...
      @classmethod
      @annotate('JArray', size=Union[int, long])
      def newDoubleArray(cls, size):
          ...
      @classmethod
      @annotate('JArray', size=Union[int, long])
      def newStringArray(cls, size):
          ...
      @classmethod
      @annotate('JArray', size=Union[int, long], component_class=JClass)
      def newObjectArray(cls, size, component_class):
          ...

      @annotate(jenv=jni.JNIEnv, jarr=jni.jarray, borrowed=bool)
      def __init__(self, jenv, jarr, borrowed=False):
          ...

      def __hash__(self):
          return super(JArray, self).__hash__()

      def __len__(self):
          return self.getLength()

      @annotate(JObject, borrowed=bool)
      def asObject(self, borrowed=False):
          ...

      @cached
      @annotate(int)
      def getLength(self):
          ...

      @annotate(bool, idx=int)
      def getBoolean(self, idx):
          ...
      ...
      @annotate(float, idx=int)
      def getDouble(self, idx):
          ...
      @annotate(Optional[str], idx=int)
      def getString(self, idx):
          ...
      @annotate(Optional[JObject], idx=int)
      def getObject(self, idx):
          ...

      @annotate(idx=int, val=bool)
      def setBoolean(self, idx, val):
          ...
      @annotate(idx=int, val=str)
      def setChar(self, idx, val):
          ...
      ...
      @annotate(idx=int, val=Union[int, long])
      def setLong(self, idx, val):
          ...
      @annotate(idx=int, val=float)
      def setDouble(self, idx, val):
          ...
      @annotate(idx=int, val=Optional[str])
      def setString(self, idx, val):
          ...
      @annotate(idx=int, val=Optional[JObject])
      def setObject(self, idx, val):
          ...

      @annotate('JArray', start=int, stop=int, step=int)
      def getBooleanSlice(self, start, stop, step):
          ...
      ...
      @annotate('JArray', start=int, stop=int, step=int)
      def getDoubleSlice(self, start, stop, step):
          ...
      @annotate('JArray', start=int, stop=int, step=int)
      def getStringSlice(self, start, stop, step):
          ...
      @annotate('JArray', start=int, stop=int, step=int)
      def getObjectSlice(self, start, stop, step):
          ...

      @annotate(start=int, stop=int, step=int, val=Sequence[bool])
      def setBooleanSlice(self, start, stop, step, val):
          ...
      @annotate(start=int, stop=int, step=int, val=Union[Sequence[str], str])
      def setCharSlice(self, start, stop, step, val):
          ...
      @annotate(start=int, stop=int, step=int,
                val=Union[Sequence[Union[int,bytes]], (bytes, bytearray)])
      def setByteSlice(self, start, stop, step, val):
          ...
      ...
      @annotate(start=int, stop=int, step=int, val=Sequence[float])
      def setDoubleSlice(self, start, stop, step, val):
          ...
      @annotate(start=int, stop=int, step=int, val=Sequence[Optional[str]])
      def setStringSlice(self, start, stop, step, val):
          ...
      @annotate(start=int, stop=int, step=int, val=Sequence[Optional[JObject]])
      def setObjectSlice(self, start, stop, step, val):
          ...

      @annotate(Tuple)
      def getBooleanBuffer(self):
          with self.jvm as (jvm, jenv):
              is_copy = jni.jboolean()
              return jenv.GetBooleanArrayElements(self._jobj, is_copy), jni.sizeof(jni.jboolean), b"B", is_copy
      ...
      @annotate(Tuple)
      def getDoubleBuffer(self):
          with self.jvm as (jvm, jenv):
              is_copy = jni.jboolean()
              return jenv.GetDoubleArrayElements(self._jobj, is_copy), jni.sizeof(jni.jdouble), b"d", is_copy

      @annotate(buf=object)
      def releaseBooleanBuffer(self, buf):
          with self.jvm as (jvm, jenv):
              jenv.ReleaseBooleanArrayElements(self._jobj, jni.cast(buf, jni.POINTER(jni.jboolean)))
      ...
      @annotate(buf=object)
      def releaseDoubleBuffer(self, buf):
          with self.jvm as (jvm, jenv):
              jenv.ReleaseDoubleArrayElements(self._jobj, jni.cast(buf, jni.POINTER(jni.jdouble)))

Installation
============

Prerequisites:

+ Python 3.10 or higher

  * https://www.python.org/

+ pip

  * https://pypi.org/project/pip/

To install run:

  .. parsed-literal::

    python -m pip install --upgrade |package|

Development
===========

Prerequisites:

+ Development is strictly based on *nox*. To install it run::

    python -m pip install --upgrade nox

Visit `Development page`_.

Installation from sources:

clone the sources:

  .. parsed-literal::

    git clone |respository| |package|

and run:

  .. parsed-literal::

    python -m pip install ./|package|

or on development mode:

  .. parsed-literal::

    python -m pip install --editable ./|package|

License
=======

  | |copyright|
  | Licensed under the zlib/libpng License
  | https://opensource.org/license/zlib
  | Please refer to the accompanying LICENSE file.

Authors
=======

* Adam Karpierz <adam@karpierz.net>

Sponsoring
==========

| If you would like to sponsor the development of this project, your contribution
  is greatly appreciated.
| As I am now retired, any support helps me dedicate more time to maintaining and
  improving this work.

`Donate`_

.. |package| replace:: annotate
.. |package_bold| replace:: **annotate**
.. |copyright| replace:: Copyright (c) 2012-2026 Adam Karpierz
.. |respository| replace:: https://github.com/karpierz/annotate
.. _Development page: https://github.com/karpierz/annotate
.. _PyPI record: https://pypi.org/project/annotate/
.. _Documentation: https://karpierz.github.io/annotate/
.. _Donate: https://www.paypal.com/donate/?hosted_button_id=FX8L7CJUGLW7S
