1/*!
2 * @header OC_PythonDictionary.h
3 * @abstract Objective-C proxy for Python dictionaries
4 * @discussion
5 *     This file defines the class that is used to proxy Python
6 *     dictionaries to Objective-C.
7 */
8
9#import "pyobjc.h"
10#import <Foundation/Foundation.h>
11
12/*!
13 * @class OC_PythonDictionary
14 * @abstract Objective-C proxy for Python dictonaries
15 * @discussion
16 *      Instances of this class are used as proxies for Python dicts when
17 *      these are passed to Objective-C functions/methods. Because this class
18 *      is a subclass of NSMutableDictonary Python dictionaries can be used
19 *      whereever instances of NSDictionary or NSMutableDictionary are expected.
20 *
21 *      NOTE: We currently only proxy real 'dict' objects this way, the generic
22 *      PyMapping_* API is not flexible enough, and most sequence als implement
23 *      the generic mapping interface to deal with slices.
24 */
25@interface OC_PythonDictionary : NSMutableDictionary
26{
27	PyObject* value;
28}
29
30/*!
31 * @method depythonifyObject:
32 * @abstract Create a new instance when appropriate
33 * @param value A python object
34 * @result Returns an autoreleased value or nil. Might set error in latter case.
35 *
36 * Caller must own the GIL
37 */
38+ depythonifyObject:(PyObject*)object;
39
40
41/*!
42 * @method newWithPythonObject:
43 * @abstract Create a new autoreleased proxy object
44 * @param value  A Python dict
45 * @result Returns an autoreleased proxy object for the Python dict
46 *
47 * The caller must own the GIL.
48 */
49+ newWithPythonObject:(PyObject*)value;
50
51/*!
52 * @method initWithPythonObject:
53 * @abstract Initialize a proxy object
54 * @param value  A Python dict
55 * @result Returns self
56 * @discussion
57 *    Makes the proxy object a proxy for the specified Python dict.
58 *
59 *    The caller must own the GIL.
60 */
61- initWithPythonObject:(PyObject*)value;
62
63/*!
64 * @method dealloc
65 * @abstract Deallocate the object
66 */
67- (void)dealloc;
68
69/*!
70 * @method dealloc
71 * @abstract Access the wrapped Python sequence
72 * @result  Returns a new reference to the wrapped Python sequence.
73 */
74- (PyObject*)__pyobjc_PythonObject__;
75
76/*!
77 * @method count
78 * @abstract Find the number of elements in the dictionary
79 * @result Returns the size of the wrapped Python dictionary
80 */
81- (NSUInteger)count;
82
83/*
84 * @method keyEnumerator
85 * @abstract Enumerate all keys in the wrapped dictionary
86 * @result Returns an NSEnumerator instance for iterating over the keys
87 */
88- (NSEnumerator*)keyEnumerator;
89
90/*
91 * @method setObject:forKey:
92 * @param object An object
93 * @param key    A key, must be hashable.
94 */
95- (void)setObject:(id)object forKey:(id)key;
96
97/*
98 * @method removeObjectForKey:
99 * @param key A key, must be hashable
100 */
101- (void)removeObjectForKey:(id)key;
102
103/*
104 * @method objectForKey:
105 * @param key A key
106 * @result Returns the object corresponding with key, or nil.
107 */
108- (id)objectForKey:(id)key;
109
110/*
111 * XXX - document these, internal
112 */
113-(BOOL)wrappedKey:(id*)keyPtr value:(id*)valuePtr atPosition:(Py_ssize_t*)positionPtr;
114-(int)depythonify:(PyObject*)v toId:(id*)datum;
115
116/* These two are only present to *disable* coding, not implement it */
117- (void)encodeWithCoder:(NSCoder*)coder;
118- initWithCoder:(NSCoder*)coder;
119
120@end /* interface OC_PythonDictionary */
121