Commits

Ronald Oussoren committed 4f1e481

Some documentation tweaks

The real work is still forthcoming.

Comments (0)

Files changed (4)

pyobjc-core/Doc/introspecting.rst

+Introspecting PyObjC
+====================
+
+Introduction
+------------
+
+The normal introspection facilities can be used to introspect
+Objective-C classes as well. This document describes some
+differences between Objective-C classes and normal Python
+classes that might cause confusion, as well as some additional
+introspection mechanisms.
+
+Using :func:`dir`
+------------------
+
+The :func:`dir` function is used to check which attributes
+are available on a class or instance, and can be used without
+problem on Objective-C classes.
+
+There is a significant difference between regular Python
+classes and Objective-C classes w.r.t. class methods:
+Objective-C class methods are methods defined on a meta
+class, and do not use the :func:`classmethod` decorator.
+Because of this ``dir(NSObject)`` only lists instance methods,
+and not class methods, use ``dir(type(NSObject))`` to list
+the class methods of an Objective-C class.
+
+.. note::
+
+   Class methods are methods on a meta class because Objective-C
+   classes can have class- and instance-methods with the same
+   name, for example ``+[NSObject description]`` and
+   ``-[NSObject description]``.
+
+
+Using :mod:`pydoc` or :func:`help`
+----------------------------------
+
+:mod:`Pydoc <pydoc>`, and the :func:`help` function in the
+interactive interpreter, can introspect Objective-C classes,
+but might not give as much information as you'd like.
+
+As with :func:`dir`, class methods are not mentioned in the
+documentation for a class, and it is not yet clear if it is
+possible to teach :mod:`pydoc` to list methods on the metaclass.
+
+The prototype of methods lists ``...`` instead of an actual
+argument list. That's due to a limitation in :mod:`pydoc` w.r.t.
+functions implemented in C. The documentation string does list
+a full prototype, and information about arguments.
+
+.. note::
+
+   This may be fixed for Python 3.4, see
+   `issue #17053 in Python's tracker`_.
+
+
+Function and method metadata
+----------------------------
+
+Objective-C methods and functions have an ``__metadata__`` method
+that can be used to retrieve the information that the bridge
+has about a specific method or function.
+
+The result of this function is a copy of a :ref:`metadata dictionary <metadata-dictionary>`.
+
+
+Type attributes
+---------------
+
+The struct and opaque pointer types created by PyObjC have
+a ``__typestr__`` attribute. This attribute contains the Objective-C
+type encoding for variables of this type.
+
+
+Introspecting instance variables
+--------------------------------
+
+The functions :func:`listInstanceVariables`, :func:`getInstanceVariable`
+and :func:`setInstanceVariable` can be used to introspect, and
+change, instance variables of arbitrary Objective-C objects,
+irrespecitive of whether or not those variables are public.
+
+This can be useful during debugging, or when exploring the internals
+of a framework implementation, but shouldn't be used in production code:
+instance variables aren't part of public API and could therefore change
+without notice between releases. Changing instance variables can
+break class invariants and might cause misbehavior (including hard
+crashes).
+
+.. _`issue #17053 in Python's tracker`: http://bugs.python.org/issue17053

pyobjc-core/Doc/introspecting.txt

-Introspecting PyObjC
-====================
-
-* explain dir(NSObject) vs. dir(type(NSObject))
-
-* metadata introspection (and use)
-
-* listing instance variables, its use and warnings
-
-* protocols

pyobjc-core/Doc/metadata/manual.rst

      Loading metadata using compiled files
 
 
+.. metadata-dictionary:
+
 Metadata dictionaries
 ---------------------
 

pyobjc-core/Doc/serializing.rst

 preferably the former). At this time it is not possible to
 encode Cocoa objects using the :mod:`pickle` module.
 
-.. todo::
-
-   Explain why it is not possible to pickle Cocoa objects.
-
 Pickling support for Cocoa objects
 ----------------------------------
 
 It is currently not possible to serialize a arbitrary Cocoa
 object into a :mod:`pickle` archive due to slight
-incompatibilities in the overal serialization mechanism.
+incompatibilities in the overal serialization mechanism when
+dealing with possibly circular data structures.
 
 It is possible to pickle a Python subclass of a Cocoa
 class when that Python class implements the "__reduce__"
-hook.
+for "__reduce_ex__" hook (as documented in the documentation
+for the :mod:`pickle` module).
+
 
 NSCoding support for Python objects
 -----------------------------------
 "initWithCoder:" and "encodeWithCoder:" to serialize the object
 state.
 
+The serialization of archives with only builtin Python types and Cocoa
+objects is compatible with archiving the corresponding Cocoa objects.
+Because of this, these archives (both normal and keyed) can be read
+back by Objective-C programs, which means such archives could be used
+for inter-process communication. However, keep in mind that archives
+can contain arbitrary objects and reading back archives might not
+be secure when the other process cannot be trusted.
+
 .. note::
 
    In Mac OS X 10.8, an likely other OSX releases as well, the
    Cocoa collection classes cannot properly archive and unarchive
-   object graphs with cycles between collections.
+   object graphs with cycles between collections (like the
+   code below).
+
+   .. sourcecode:: python
+
+      a = []
+      a.append(a)
 
    Because of this serializing the graph below with an NSArchiver
    will result in a grabled datastructure when read back. The
    same will be true when archiving with NSKeyedArchiver and
    reading the archive back in pure Objective-C.
 
-   .. sourcecode:: python
-
-      a = []
-      a.append(a)
-
    This is an unfortunate limitation in Cocoa that PyObjC cannot
    paper over.
 
 The format used for serializing Python objects has changed a couple
 of times. Because of this it is not always possible to read back
 archives created with a newer version of PyObjC using older versions
-of PyObjC.
+of PyObjC. As of PyObjC 3.0 there is a fairly good test suite for
+the NSCoding support in PyObjC and the intention is to not introduce
+futher backward incompatble changes for keyed archiving, and only
+introduce changes for non-keyed archiver when there are no other
+solutions.
 
 The following table lists the changes in the encoding, with "forward compatible" meaning
 that this version of PyObjC can read older archives, and "backward compatible" meaning that older
   | *Version* | *Backward*  |br|   | *Forward* |br|     | *Notes*                              |
   |           | *compatible*       | *compatbile*       |                                      |
   +===========+====================+====================+======================================+
-  |           |                    |                    | TODO: check C code                   |
-  |           |                    |                    |                                      |
-  +-----------+--------------------+--------------------+--------------------------------------+
   | 2.5       | Yes                | Maybe              | Encoding of pure python objects      |
   |           |                    |                    | other than those with explicit       |
   |           |                    |                    | support in PyObjC was broken for a   |