Metadata-Version: 2.1
Name: fullofeels
Version: 1.6.1
Summary: Creates C code skeleton for handcrafted Python extension modules
Home-page: https://hg.sr.ht/~hfisher/fullofeels
Author: H Fisher
Author-email: hugo.fisher@gmail.com
License: UNKNOWN
Description: 
        # Full of Eels
        
        
        FullOfEels is an assistant program to generate the skeleton code for
        a handcrafted artisanal Python module to be implemented in native C.
        
        It is not a replacement for SWIG or SIP. If you have an existing C/C++
        library and want to create a Python wrapper with the same API, either
        of those will do just fine.
        
        FullOfEels works in the opposite direction. You start by specifying
        the Python API that you want: module, classes, methods, and functions.
        This program will create the initial .h/.c files for you, generating
        empty C functions with argument parsing code, struct definitions for
        the object and type, module init function ... all the the boring but
        necessary bits. You then fill them out with working C code.
        
        How do you specify the Python API you want? By writing it in Python.
        You create a module that defines _what_ the functions and classes will
        be, with all the arguments and methods, but none of the code that
        defines _how_ it works - methods and functions should all just `pass`.
        FullOfEels keeps docstrings and some globals, but actual statements
        are discarded.
        
        (OK, not entirely true. You can use functions and return statements
        to specify a bit more information about arguments and results, but
        you don't have to use them. See REFERENCE.)
        
        Why might you prefer this? Because you can design a more Pythonic API.
        The great advantage of SWIG/SIP is that the API is already known and
        (ideally) documentation exists. The disadvantage is that you're just
        recreating a C/C++ API in Python, and that programmers will have to
        be able to understand C/C++ to understand the documentation. There are
        times when this is the best solution. Fullofeels is for when it isn't.
        
        Written by Hugh(Hugo) Fisher, Canberra Australia, 2016-now. <br>
        Released under MIT license <br>
        All feedback welcome: hugo.fisher@gmail.com (Yes, hugo not hugh)
        
        
        ### Example
        
        The Python "Extending Python with C or C++" web pages
        start by creating a spam module with a single `system()` function.
        With fullOfEels you start this by writing `spam.py` which is just
        
            def system(command):
                """Execute a shell command."""
                pass
        
        Then you run
        
            python -m fullofeels -print spam.py
        
        which will create
        
            spam.h
            spam.c
            setup.py
        
        Look inside and you'll see all the skeleton code needed for the complete
        Python extension module. Run
        
            python setup.py build_ext --inplace
        
        and you will have a valid module. From your Python interpreter you can
        import it and invoke the `spam.system("hello")` function, which will just
        print out the function name and arguments (specified by the -print CLI option).
        
        Because fullOfEeels is an assistant, not an automated solution, you still
        need to fill in the function body yourself to make it do anything useful.
        
        
        For the "Defining New Types" web example you would write noddy.py:
        
            class Noddy(object):
                """Noddy objects"""
        
                def __new__(cls):
                    pass
        
                def __init__(self, first, last, number):
                    pass
        
                def __del__(self):
                    pass
        
                def name(self):
                    """Return the name, combining the first and last name"""
                    return str
        
        and again run fullOfEels on it. The generated C code will have the all
        the code necessary to declare and initialize the Noddy type structure.
        As before you could build this module, import it, and even create Noddy
        objects. But without additional code they won't do anything and won't
        have any attributes or properties.
        
        
        ### TODO
        
        Heap allocated types
        
        Look at new Python C API for 3.10+
        
        
        ### Tested on
        
            Python 2.7  Fedora Core 24, MacOS 10.14 XCode 11
            Python 3.5  Fedora Core 24
            Python 3.6  Windows 8.1 MSVC 2017
            Python 3.7  Fedora Core 31, Windows 10 MSVC 2019
            Python 3.9  Fedora Core 31
        
        
        ### Versions
        
        1.5 Jan 2019        Replace separate program with -m fullofeels package
        
        1.4 Nov 2017        Generate setup.py for module
        
        1.3 Oct 2017        Properties on class become C fields in object struct
        
        1.2 Feb 2017        Can specify argument types for PyArg_ParseTuple
        
        1.1 Nov 2016        Special slots for collections, numbers, buffer interface
        
        1.0 Apr 2016        Modules, objects, classes, methods
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=2.7
Description-Content-Type: text/markdown
