{
    "info": {
        "author": "scnerd",
        "author_email": "scnerd@gmail.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": ".. image:: https://travis-ci.org/scnerd/pypragma.svg?branch=master\n    :target: https://travis-ci.org/scnerd/pypragma\n\n.. image:: https://coveralls.io/repos/github/scnerd/pypragma/badge.svg?branch=master\n    :target: https://coveralls.io/github/scnerd/pypragma?branch=master\n\n.. image:: https://readthedocs.org/projects/pypragma/badge/?version=latest\n    :target: http://pypragma.readthedocs.io/en/latest/?badge=latest\n    :alt: Documentation Status\n\nOverview\n========\n\nPyPragma is a set of tools for performing in-place code modification, inspired by compiler directives in C. These modifications are intended to make no functional changes to the execution of code. In C, this is used to increase code performance or make certain tradeoffs (often between the size of the binary and its execution speed). In Python, these changes are most applicable when leveraging code generation libraries (such as Numba or Tangent) where the use of certain Python features is disallowed. By transforming the code in-place, disallowed features can be converted to allowed syntax at runtime without sacrificing the dynamic nature of python code.\n\nFor example, with Numba, it is not possible to compile a function which dynamically references and calls other functions (e.g., you may not select a function from a list and then execute it, you may only call functions by their explicit name)::\n\n   fns = [sin, cos, tan]\n\n   @numba.jit\n   def call(i, x):\n      return fns[i](x)  # Not allowed, since it's unknown which function is getting called\n\nIf the dynamism is static by the time the function is defined, such as in this case, then these dynamic language features can be flattened to simpler features that such code generation libraries are more likely to support (e.g., the function can be extracted into a closure variable, then called directly by that name)::\n\n   fns = [sin, cos, tan]\n\n   fns_0 = fns[0]\n   fns_1 = fns[1]\n   fns_2 = fns[2]\n\n   @numba.jit\n   def call(i, x):\n      if i == 0:\n         return fns_0(x)\n      if i == 1:\n         return fns_1(x)\n      if i == 2:\n         return fns_2(x)\n\nSuch a modification can only be done by the programmer if the dynamic features are known *before* runtime, that is, if ``fns`` is dynamically computed, then this modification cannot be performed by the programmer, even though this example demonstrates the the original function is not inherently dynamic, it just appears so. PyPragma enables this transformation at runtime, which for this example function would look like::\n\n   fns = [sin, cos, tan]\n\n   @numba.jit\n   @pragma.deindex(fns, 'fns')\n   @pragma.unroll(num_fns=len(fns))\n   def call(i, x):\n      for j in range(num_fns):\n         if i == j:\n            return fns[j](x)  # Still dynamic call, but decorators convert to static\n\nThis example is converted, in place and at runtime, to exactly the unrolled code above.\n\n\nInstallation\n============\n\nAs usual, you have the choice of installing from PyPi::\n\n   pip install pragma\n\nor directly from Github::\n\n   pip install git+https://github.com/scnerd/pypragma\n\n\nUsage\n===========\n\nPyPragma has a small number of stackable decorators, each of which transforms a function in-place without changing its execution behavior. These can be imported as such::\n\n   import pragma\n\nEach decorator can be applied to a function using either the standard decorator syntax, or as a function call::\n\n   @pragma.unroll\n   def pows(i):\n      for x in range(3):\n         yield i ** x\n\n   pows(5)\n\n   # Is identical to...\n\n   def pows(i):\n      for x in range(3):\n         yield i ** x\n\n   pragma.unroll(pows)(5)\n\n   # Both of which become...\n\n   def pows(i):\n      yield i ** 0\n      yield i ** 1\n      yield i ** 2\n\n   pows(5)\n\nEach decorator can be used bare, as in the example above, or can be given initial parameters before decorating the given function. Any non-specified keyword arguments are added to the resulting function's closure as variables. In addition, the decorated function's closure is preserved, so external variables are also included. As a simple example, the above code could also be written as::\n\n   @pragma.unroll(num_pows=3)\n   def pows(i):\n      for x in range(num_pows):\n         yield i ** x\n\n   # Or...\n\n   num_pows = 3\n   @pragma.unroll\n   def pows(i):\n      for x in range(num_pows):\n         yield i ** x\n\nCertain keywords are reserved, of course, as will be defined in the documentation for each decorator. Additionally, the resulting function is an actual, proper Python function, and hence must adhere to Python syntax rules. As a result, some modifications depend upon using certain variable names, which may collide with other variable names used by your function. Every effort has been made to make this unlikely by using mangled variable names, but the possibility for collision remains.\n\nA side effect of the proper Python syntax is that functions can have their source code retrieved by any normal Pythonic reflection::\n\n   In [1]: @pragma.unroll(num_pows=3)\n      ...: def pows(i):\n      ...:    for x in range(num_pows):\n      ...:       yield i ** x\n      ...:\n\n   In [2]: pows??\n   Signature: pows(i)\n   Source:\n   def pows(i):\n       yield i ** 0\n       yield i ** 1\n       yield i ** 2\n   File:      /tmp/tmpmn5bza2j\n   Type:      function\n\nAs a utility, primarily for testing and debugging, the source code can be easily retrieved from each decorator *instead* of the transformed function by using the ``return_source=True`` argument.\n\nQuick Examples\n==============\n\nCollapse Literals\n+++++++++++++++++\n\n:doc:`Complete documentation <collapse_literals>`::\n\n   In [1]: @pragma.collapse_literals(x=5)\n      ...: def f(y):\n      ...:     z = x // 2\n      ...:     return y * 10**z\n      ...:\n\n   In [2]: f??\n   Signature: f(y)\n   Source:\n   def f(y):\n       z = 2\n       return y * 100\n\nDe-index Arrays\n+++++++++++++++\n\n:doc:`Complete documentation <deindex>`::\n\n   In [1]: fns = [math.sin, math.cos, math.tan]\n\n   In [2]: @pragma.deindex(fns, 'fns')\n      ...: def call(i, x):\n      ...:     if i == 0:\n      ...:         return fns[0](x)\n      ...:     if i == 1:\n      ...:         return fns[1](x)\n      ...:     if i == 2:\n      ...:         return fns[2](x)\n      ...:\n\n   In [3]: call??\n   Signature: call(i, x)\n   Source:\n   def call(i, x):\n       if i == 0:\n           return fns_0(x)\n       if i == 1:\n           return fns_1(x)\n       if i == 2:\n           return fns_2(x)\n\nNote that, while it's not evident from the above printed source code, each variable ``fns_X`` is assigned to the value of ``fns[X]`` at the time when the decoration occurs::\n\n   In [4]: call(0, math.pi)\n   Out[4]: 1.2246467991473532e-16  # AKA, sin(pi) = 0\n\n   In [5]: call(1, math.pi)\n   Out[5]: -1.0  # AKA, cos(pi) = -1\n\nUnroll\n++++++\n\n:doc:`Complete documentation <unroll>`::\n\n   In [1]: p_or_m = [1, -1]\n\n   In [2]: @pragma.unroll\n      ...: def f(x):\n      ...:     for j in range(3):\n      ...:         for sign in p_or_m:\n      ...:             yield sign * (x + j)\n      ...:\n\n   In [3]: f??\n   Signature: f(x)\n   Source:\n   def f(x):\n       yield 1 * (x + 0)\n       yield -1 * (x + 0)\n       yield 1 * (x + 1)\n       yield -1 * (x + 1)\n       yield 1 * (x + 2)\n       yield -1 * (x + 2)\n\nInline\n++++++\n\n:doc:`Complete documentation <inline>`::\n\n   In [1]: def sqr(x):\n      ...:     return x ** 2\n      ...:\n\n   In [2]: @pragma.inline(sqr)\n      ...: def sqr_sum(a, b):\n      ...:     return sqr(a) + sqr(b)\n      ...:\n\n   In [3]: sqr_sum??\n   Signature: sqr_sum(a, b)\n   Source:\n   def sqr_sum(a, b):\n       _sqr_0 = dict(x=a)  # Prepare for 'sqr(a)'\n       for ____ in [None]:  # Wrap function in block\n           _sqr_0['return'] = _sqr_0['x'] ** 2  # Compute returned value\n           break  # 'return'\n       _sqr_return_0 = _sqr_0.get('return', None)  # Extract the returned value\n       del _sqr_0  # Delete the arguments dictionary, the function call is finished\n       _sqr_0 = dict(x=b)  # Do the same thing for 'sqr(b)'\n       for ____ in [None]:\n           _sqr_0['return'] = _sqr_0['x'] ** 2\n           break\n       _sqr_return_1 = _sqr_0.get('return', None)\n       del _sqr_0\n       return _sqr_return_0 + _sqr_return_1  # Substitute the returned values for the function calls\n\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/scnerd/pypragma",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pragma",
        "package_url": "https://pypi.org/project/pragma/",
        "platform": "",
        "project_url": "https://pypi.org/project/pragma/",
        "project_urls": {
            "Homepage": "https://github.com/scnerd/pypragma"
        },
        "release_url": "https://pypi.org/project/pragma/0.1.0/",
        "requires_dist": [
            "miniutils",
            "astor"
        ],
        "requires_python": "",
        "summary": "Python code transformers that mimic pragma compiler directives",
        "version": "0.1.0"
    },
    "last_serial": 3626133,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "af09865dead875ba4cfd8473ed0f9972",
                    "sha256": "1201a7f588f69b3c8437dcd2ff9e34af759bb6e3edcdefed5783bf60ac88f8ac"
                },
                "downloads": -1,
                "filename": "pragma-0.1.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "af09865dead875ba4cfd8473ed0f9972",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 21774,
                "upload_time": "2018-02-28T18:13:18",
                "url": "https://files.pythonhosted.org/packages/92/f6/3340825614a946c01245fe9fa1b70ceba8f1abda668985e5b6da370c39c7/pragma-0.1.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "941da1b12bb0c1c953d8cffb713ec353",
                    "sha256": "8ab93cf129984b8329b8c7728102fa8708b1f5af00b843dfde06551b321cbefe"
                },
                "downloads": -1,
                "filename": "pragma-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "941da1b12bb0c1c953d8cffb713ec353",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15472,
                "upload_time": "2018-02-28T18:13:20",
                "url": "https://files.pythonhosted.org/packages/9b/55/bde483efa1d0e0dcca47a0263ec6ecd4cae1e228b6b37beb4512a8921561/pragma-0.1.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "af09865dead875ba4cfd8473ed0f9972",
                "sha256": "1201a7f588f69b3c8437dcd2ff9e34af759bb6e3edcdefed5783bf60ac88f8ac"
            },
            "downloads": -1,
            "filename": "pragma-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "af09865dead875ba4cfd8473ed0f9972",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 21774,
            "upload_time": "2018-02-28T18:13:18",
            "url": "https://files.pythonhosted.org/packages/92/f6/3340825614a946c01245fe9fa1b70ceba8f1abda668985e5b6da370c39c7/pragma-0.1.0-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "941da1b12bb0c1c953d8cffb713ec353",
                "sha256": "8ab93cf129984b8329b8c7728102fa8708b1f5af00b843dfde06551b321cbefe"
            },
            "downloads": -1,
            "filename": "pragma-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "941da1b12bb0c1c953d8cffb713ec353",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 15472,
            "upload_time": "2018-02-28T18:13:20",
            "url": "https://files.pythonhosted.org/packages/9b/55/bde483efa1d0e0dcca47a0263ec6ecd4cae1e228b6b37beb4512a8921561/pragma-0.1.0.tar.gz"
        }
    ]
}