Commits

Virgil Dupras committed bceec2e

v1.0.0

Comments (0)

Files changed (5)

 Changes
 =======
 
+Version 1.0.0 -- 2012/01/16
+---------------------------
+
+* Added support for protocols.
+* Added support for __init__ method wrapping.
+* Added ``bool`` and ``pyref`` argument types.
+* Added support for creating a p2o instance that wraps a pre-existing objc instance.
+* Added exception checking.
+* Added GIL locking.
+* Added inheritance support.
+* Added multiple class wrapping in the same p2o module.
+
 Version 0.1.1 -- 2012/01/08
 ---------------------------
 
+Copyright (c) 2012, Hardcoded Software Inc., http://www.hardcoded.net
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    * Neither the name of Hardcoded Software Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 include README
 include CHANGES
+include LICENSE
 include objp/data/*
 dynamic calls to methods on runtime, ObjP generates static code. It generates either Objective-C
 interfaces to Python code or Python modules to interface Objective-C code.
 
-At the moment, the library is exceedingly rudimentary, but it works for simple cases. One of these
-cases is in demos/simple. To build and run this demo do (Python 3.2+ required)::
+The library is exceedingly simple and it's intended that way. Unlike PyObjC, there's no way ObjP
+could possibly wrap the whole Cocoa framework, there's way too many things to support. ObjP is made
+to allow you to bridge your own code.
 
+Also note that ObjP works on Python 3.2 and up.
+
+The best way to learn how to use ObjP is, I think, to look at an example. There are many of them in
+the 'demos' subfolder. These are built using ``waf`` (it's already included in here, no need to
+install it). For example, if you want to build the ``simple`` demo, do::
+
+    $ cd demos/simple
     $ ./waf configure build
     $ cd build
     $ ./HelloWorld
 
 That programs calls a simple Python script from Objective-C, and that python script itself calls
-an Objective-C class.
+an Objective-C class.
+
+Usage
+-----
+
+There are two types of bridge: Objective-C class wrapping a Python class (o2p) and Python class
+wrapping an Objective-C class (p2o).
+
+To generate an o2p wrapper, you need a target class. Moreover, for this class' methods to be
+wrapped, you need to have its arguments and return value correctly annotated (You can browse the
+demos for good examples of how to do it). This is an example of a correctly annotated class::
+
+    class Foo:
+        def hello_(self, name: str) -> str:
+            return "Hello {}".format(name)
+
+To wrap this class, you'll use ``objp.o2p.generate_objc_code()`` in this fashion::
+
+    import foo
+    import objp.o2p
+    objp.o2p.generate_objc_code(foo.Foo, 'destfolder')
+
+This will generate "Foo.h|m" as well as "ObjP.h|m" in "destfolder". These source files directly
+use the Python API and have no other dependencies.
+
+To generate a p2o wrapper, you either need an Objective-C header file containing an interface or
+protocol or a Python class describing that interface::
+
+    @interface Foo: NSObject {}
+    - (NSString *)hello:(NSString *)name;
+    @end
+
+To generate a python wrapper from this, you can do::
+
+    import objp.p2o
+    objp.p2o.generate_python_proxy_code(['Foo.h'], 'destfolder/Foo.m')
+
+This will generate the code for a Python extension module wrapping ``Foo``. The name of the
+extension module is determined by the name of the destination source file. You can wrap more than
+one class in the same unit::
+
+    objp.p2o.generate_python_proxy_code(['Foo.h', 'Bar.h'], 'destfolder/mywrappers.m')
+
+Method name conversion
+----------------------
+
+ObjP follows PyObjC's convention for converting method names. The ":" character being illegal in
+Python method names, they're replaced by underscores. Thus, a method
+``- (BOOL)foo:(NSInteger)arg1 bar:(NSString *)arg2;`` is converted to
+``def foo_bar_(self, arg1: int, arg2: str) -> bool:`` and vice versa.
+
+Note that if your method's argument count doesn't correspond to the number of underscores in your
+method name, objp will issue a warning and ignore the method.
+
+Argument Types
+--------------
+
+Only a few argument types are supported by ObjP, the goal being to keep the project simple.
+
+* ``int/NSInteger``
+* ``str/NSString*``
+* ``bool/BOOL``
+* ``list/NSArray*``
+* ``dict/NSDictionary*``
+
+ObjP also supports ``object`` which dynamically converts the argument depending on its type and
+returns an ``NSObject`` subclass (which means that ``int`` and ``bool` convert to ``NSNumber``
+instead of converting to ``NSInteger`` and ``BOOL``). This type of conversion is used to convert
+the contents of ``list`` and ``dict`` (it's impossible to have an NSArray directly containing
+``BOOL``).
+
+Another special argument type is ``pyref`` (which you must import from ``objp.util`` in your code)
+which simply passes the ``PyObject*`` instance around without converting it.
+
+Utilities
+---------
+
+``objp.util`` contains the ``pyref`` argument type, but it also contains two useful method
+decorators: ``dontwrap`` and ``objcname``. A method decorated with ``dontwrap`` will be ignored by
+the code generator, and a method decorated with ``@objcname('some:selector:')`` will use this name
+for generating objc code instead of the automatically generated name.
 
 setup(
     name='objp',
-    version='0.1.1',
+    version='1.0.0',
     author='Hardcoded Software',
     author_email='hsoft@hardcoded.net',
     packages=['objp'],
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.