Metadata-Version: 2.1
Name: ffilupa
Version: 4.0.0.dev2
Summary: A modern two-way bridge between Python and Lua
Home-page: https://github.com/TitanSnow/ffilupa
Author: TitanSnow
Author-email: tttnns1024@gmail.com
License: LGPLv3
Keywords: cffi,lua,binding
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Other Scripting Engines
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Requires-Python: ~=3.6
Requires-Dist: cffi (~=1.12)
Requires-Dist: packaging (~=19.0)
Requires-Dist: dataclasses (~=0.6) ; python_version == "3.6"

|banner|
========

.. |banner| image:: docs/banner.svg
           :target: https://github.com/TitanSnow/ffilupa
           :alt: ffilupa

.. image:: https://img.shields.io/travis/TitanSnow/ffilupa.svg?style=for-the-badge
  :target: https://travis-ci.org/TitanSnow/ffilupa
  :alt: build

.. image:: https://img.shields.io/codecov/c/github/TitanSnow/ffilupa.svg?style=for-the-badge
  :target: https://codecov.io/gh/TitanSnow/ffilupa
  :alt: coverage

.. image:: https://img.shields.io/pypi/v/ffilupa.svg?style=for-the-badge
  :target: https://pypi.org/project/ffilupa
  :alt: version

.. image:: https://img.shields.io/pypi/l/ffilupa.svg?style=for-the-badge
  :target: https://pypi.org/project/ffilupa
  :alt: license

A modern two-way bridge between Python and Lua.

.. contents:: **Contents**
  :depth: 1

Major Features
--------------

For Python Users
````````````````

* Integrate Lua into Python using CFFI_ as backend, which runs fast on both CPython and PyPy.
* Run multiple Lua runtimes in one Python process.
* Link to multiple lua libraries installed in system and use their luarocks_.
* Zero-copy data sharing between Python and Lua.
* Seamless operations on Lua objects.
* Hackable and extendable; customizable interacting behaviors.
* Parallel numerical calculation using Lua to break the limit of Python’s GIL.

.. _CFFI: http://cffi.rtfd.io
.. _luarocks: http://www.luarocks.org

For Lua Users
`````````````

* Enrich Lua’s abilities by using Python’s modules.
* Link to CPython and PyPy.
* Seamless operations on Python objects.

Above all, ffilupa has plenty of fun!

Why ffilupa
-----------

Compare to lupa_
````````````````

* lupa uses Cython as it’s backend, which is less friendly to PyPy and not extendable.
* lupa doesn’t support Lua as the host language, which means you can’t use it in a Lua program.
* lupa doesn’t support seamless operations on Lua objects.
* lupa is not under actively development.
* lupa inspired ffilupa a lot.

.. _lupa: https://github.com/scoder/lupa

Compare to LunaticPython_
`````````````````````````

* Well, LunaticPython is too old and out of development for a long time.
* LunaticPython doesn’t support multiple Lua runtimes.
* LunaticPython leaks new features.

.. _LunaticPython: http://labix.org/lunatic-python

Installation
------------

Before installing ffilupa, please check whether you have installed the development library of lua.
On Ubuntu, you can install ``liblua5.3-dev`` or ``liblua5.2-dev``::

    $ sudo apt install [liblua5.3-dev|liblua5.2-dev]

On Mac OS X, you can use Homebrew_::

    $ brew install lua pkg-config

.. _Homebrew: https://brew.sh

During installation, ffilupa will automatically find lua libraries through ``pkg-config``.

Make sure you have installed Python 3.5+ in your system,
including it’s development files and the suitable C compiler.
On Ubuntu::

    $ sudo apt install python3-dev

On Mac OS X::

    $ brew install python

You’d better install the dependencies of ffilupa::

    $ pip install cffi semantic_version

It’s optional; ffilupa will install them if you haven’t installed before.

Install stable version
``````````````````````
For Python Users
::::::::::::::::

::

    $ pip install ffilupa

Install development version from Git branch
```````````````````````````````````````````

For Python Users
::::::::::::::::

::

    $ pip install git+https://github.com/TitanSnow/ffilupa.git

For Lua Users
:::::::::::::

Make sure you have installed luarocks_.

::

    $ git clone https://github.com/TitanSnow/ffilupa.git
    $ cd ffilupa
    $ luarocks make

FAQ about installation
``````````````````````

How to deal with the exception ‘Required lua lib not found’?
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Please check the installation of Lua. ffilupa currently only supports Lua 5.2 and 5.3.
Then reinstall ffilupa in order to find the recently installed Lua libraries.

Does ffilupa support Windows?
:::::::::::::::::::::::::::::

ffilupa *can* support Windows, but not now. It might support Windows in next minor release.

Usage
-----

For Python Users
````````````````

A Brief Look
::::::::::::

.. code-block:: pycon

    >>> import ffilupa
    >>> lua = ffilupa.LuaRuntime()
    >>> lua_func = lua.eval('''
    ...     function(a, b) -- a plus b
    ...         return a + b
    ...     end
    ... ''')
    >>> lua_func(22, 33)
    55

Access Globals of Lua
:::::::::::::::::::::

.. code-block:: pycon

    >>> def greeting(name='World'): # greeting someone
    ...     print('Hello, {}!'.format(name))
    >>> lua._G.greeting = greeting
    >>> lua.execute('greeting()')
    Hello, World!
    >>> lua.execute('greeting("John")')
    Hello, John!

Zero-copy Data Sharing
::::::::::::::::::::::

.. code-block:: pycon

    >>> poem = {
    ...     'the': 'quick',
    ...     'brown': 'fox',
    ...     'jumps': 'over',
    ... }
    >>> lua_func = lua.eval('''
    ...     function(poem) -- finish the poem
    ...         poem['lazy'] = 'doges'
    ...     end
    ... ''')
    >>> lua_func(poem)
    >>> poem['lazy']
    'doges'

Deal with Lua Table
:::::::::::::::::::

.. code-block:: pycon

    >>> table = lua.table_from(poem)
    >>> lua_func = lua.eval('''
    ...     function(poem) -- shuffle the poem
    ...         local new_poem = {}
    ...         for k, v in pairs(poem) do
    ...             new_poem[v] = k
    ...         end
    ...         return new_poem
    ...     end
    ... ''')
    >>> new_poem = lua_func(table)
    >>> for k in sorted(new_poem):
    ...     print(k, new_poem[k], end=' ')
    doges lazy fox brown over jumps quick the 

For Lua Users
`````````````

A Brief Look
::::::::::::

.. code-block:: lua

    ffilupa = require 'ffilupa'
    Fraction = ffilupa.import_module('fractions').Fraction
    a = Fraction(1, 2)
    b = Fraction(1, 3)
    c = a + b    -- c == 5/6

Extend Lua’s Abilities
::::::::::::::::::::::

.. code-block:: lua

    Path = ffilupa.import_module('pathlib').Path
    p = Path('.')
    p = p / 'ffilupa'
    for _, filename in pairs(p:iterdir()) do
        print(filename)    -- print all filename in ./ffilupa
    end

Acknowledgements
----------------

* CFFI_
* lupa_


