1======================= 2Coding style for PyObjC 3======================= 4 5:authors: Ronald Oussoren, 6 Bill Bumgarner 7:contact: pyobjc-dev@lists.sourceforge.net 8:URL: http://pyobjc.sourceforge.net/ 9:copyright: 2002 The PyObjC Project 10 11Introduction 12------------ 13 14This document describes the coding style for PyObjC. Please use this style for 15new code and try apply this style to existing code while working on it. 16 17The management summary: 4-space indents in Python code, 1-TAB indents in C 18code. 19 20Python code 21----------- 22 23The coding style for core Python is used (see `PEP 8`_). For consistency with 24Cocoa we use mixed-case identifiers (like ``lookUpClass``). 25 26PyObjC extensions to Apple frameworks should be clearly marked as such, 27preferably by prefixing names with ``PyObjC`` or ``pyobjc``. This should make 28it clear to users where they should look for documentation of an item: The 29Apple documentation or ours. 30 31.. _`PEP 8`: http://www.python.org/peps/pep-0008.txt 32 33C code 34------ 35 36The coding style for core Python is used (see `PEP 7`_). We use ``PyObjC`` 37instead of ``Py`` as the prefix for globally visible symbols. 38 39All (Objective-)C files in ``Modules/objc/`` should include ``"pyobjc.h"`` as 40their first include. The (Objective-)C files in the wrappers for frameworks 41should include ``"pyobjc-api.h"`` and should not use other headers files from 42``pyobjc-core``. 43 44The ``setup.py`` for a framework wrapper should defer most work to 45``pyobjc_setup.py``, like so: 46 47.. code-block:: python 48 49 from pyobjc_setup import setup 50 51 setup( 52 name='pyobjc-framework-AddressBook', 53 version="2.3" 54 description = "Wrappers for the framework AddressBook on Mac OS X", 55 packages = [ "AddressBook" ], 56 install_requires = [ 57 'pyobjc-core>=2.3b1', 58 'pyobjc-framework-Cocoa>=2.3b1', 59 ], 60 ) 61 62The framework wrappers do *not* include a copy of ``pyobjc-api.h``, but 63dynamicly fetches that at build time. 64 65Documentation 66------------- 67 68All items exported by the objc module and all PyObjC extensions to Apple 69frameworks (the AppKit and Foundation modules) should be documented using 70docstrings. 71 72All documentation-- both standalone documents and docstrings-- should be 73marked up using reStructuredText_ [ReST]. 74 75ReST in DocStrings 76++++++++++++++++++ 77 78reStructuredText_ can be used in doc strings. ReST in DocStrings works 79exactly like a standalone ReST document, but the ReST is broken up slightly 80differently. 81 82To format the DocStrings to be ReST compatible, make the following 83changes/additions to the source. These examples were taken from source found 84in the DocUtils source tree. 85 86(1) Add appropriate ReST style fields to the top of the document as comments:: 87 88 # Author: David Goodger 89 # Contact: goodger@users.sourceforge.net 90 # Copyright: This module has been placed in the public domain. 91 92(2) Add a module level variable that indicates that ReST is used to format 93 the text contained in the docstrings:: 94 95 __docformat__ = 'reStructuredText' 96 97(3) Format all other DocStrings as one normally would in Python. Use ReST 98 style markup where appropriate. For example, bulleted lists and 99 sections might commonly appear in the module or class docstrings. The 100 docstrings for individual methods may use example blocks, hyperlinks, or 101 any other ReST markup. 102 103.. _reStructuredText: http://docutils.sourceforge.net/rst.html 104 105.. _`PEP 7`: http://www.python.org/peps/pep-0007.txt 106