1. Ronald Oussoren
  2. pyobjc-3.0-unstable


Ronald Oussoren  committed 4f1e481

Some documentation tweaks

The real work is still forthcoming.

  • Participants
  • Parent commits 43ed41f
  • Branches core-cleanup

Comments (0)

Files changed (4)

File pyobjc-core/Doc/introspecting.rst

View file
+Introspecting PyObjC
+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
+.. _`issue #17053 in Python's tracker`: http://bugs.python.org/issue17053

File 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

File pyobjc-core/Doc/metadata/manual.rst

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

File pyobjc-core/Doc/serializing.rst

View file
 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__"
+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
+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
 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   |