1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 //
4 // Use of this source code is governed by a BSD-style
5 // license that can be found in the LICENSE file or at
6 // https://developers.google.com/open-source/licenses/bsd
7
8 // This file can be included by other C++ libraries, typically extension modules
9 // which want to interact with the Python Messages coming from the "cpp"
10 // implementation of protocol buffers.
11 //
12 // Usage:
13 // Declare a (probably static) variable to hold the API:
14 // const PyProto_API* py_proto_api;
15 // In some initialization function, write:
16 // py_proto_api = static_cast<const PyProto_API*>(PyCapsule_Import(
17 // PyProtoAPICapsuleName(), 0));
18 // if (!py_proto_api) { ...handle ImportError... }
19 // Then use the methods of the returned class:
20 // py_proto_api->GetMessagePointer(...);
21
22 #ifndef GOOGLE_PROTOBUF_PYTHON_PROTO_API_H__
23 #define GOOGLE_PROTOBUF_PYTHON_PROTO_API_H__
24
25 #define PY_SSIZE_T_CLEAN
26 #include <Python.h>
27
28 #include "google/protobuf/descriptor_database.h"
29 #include "google/protobuf/message.h"
30
31 namespace google {
32 namespace protobuf {
33 namespace python {
34
35 // Note on the implementation:
36 // This API is designed after
37 // https://docs.python.org/3/extending/extending.html#providing-a-c-api-for-an-extension-module
38 // The class below contains no mutable state, and all methods are "const";
39 // we use a C++ class instead of a C struct with functions pointers just because
40 // the code looks more readable.
41 struct PyProto_API {
42 // The API object is created at initialization time and never freed.
43 // This destructor is never called.
~PyProto_APIPyProto_API44 virtual ~PyProto_API() {}
45
46 // Operations on Messages.
47
48 // If the passed object is a Python Message, returns its internal pointer.
49 // Otherwise, returns NULL with an exception set.
50 virtual const Message* GetMessagePointer(PyObject* msg) const = 0;
51
52 // If the passed object is a Python Message, returns a mutable pointer.
53 // Otherwise, returns NULL with an exception set.
54 // This function will succeed only if there are no other Python objects
55 // pointing to the message, like submessages or repeated containers.
56 // With the current implementation, only empty messages are in this case.
57 virtual Message* GetMutableMessagePointer(PyObject* msg) const = 0;
58
59 // If the passed object is a Python Message Descriptor, returns its internal
60 // pointer.
61 // Otherwise, returns NULL with an exception set.
62 virtual const Descriptor* MessageDescriptor_AsDescriptor(
63 PyObject* desc) const = 0;
64
65 // If the passed object is a Python Enum Descriptor, returns its internal
66 // pointer.
67 // Otherwise, returns NULL with an exception set.
68 virtual const EnumDescriptor* EnumDescriptor_AsDescriptor(
69 PyObject* enum_desc) const = 0;
70
71 // Expose the underlying DescriptorPool and MessageFactory to enable C++ code
72 // to create Python-compatible message.
73 virtual const DescriptorPool* GetDefaultDescriptorPool() const = 0;
74 virtual MessageFactory* GetDefaultMessageFactory() const = 0;
75
76 // Allocate a new protocol buffer as a python object for the provided
77 // descriptor. This function works even if no Python module has been imported
78 // for the corresponding protocol buffer class.
79 // The factory is usually null; when provided, it is the MessageFactory which
80 // owns the Python class, and will be used to find and create Extensions for
81 // this message.
82 // When null is returned, a python error has already been set.
83 virtual PyObject* NewMessage(const Descriptor* descriptor,
84 PyObject* py_message_factory) const = 0;
85
86 // Allocate a new protocol buffer where the underlying object is owned by C++.
87 // The factory must currently be null. This function works even if no Python
88 // module has been imported for the corresponding protocol buffer class.
89 // When null is returned, a python error has already been set.
90 //
91 // Since this call returns a python object owned by C++, some operations
92 // are risky, and it must be used carefully. In particular:
93 // * Avoid modifying the returned object from the C++ side while there are
94 // existing python references to it or it's subobjects.
95 // * Avoid using python references to this object or any subobjects after the
96 // C++ object has been freed.
97 // * Calling this with the same C++ pointer will result in multiple distinct
98 // python objects referencing the same C++ object.
99 virtual PyObject* NewMessageOwnedExternally(
100 Message* msg, PyObject* py_message_factory) const = 0;
101
102 // Returns a new reference for the given DescriptorPool.
103 // The returned object does not manage the C++ DescriptorPool: it is the
104 // responsibility of the caller to keep it alive.
105 // As long as the returned Python DescriptorPool object is kept alive,
106 // functions that process C++ descriptors or messages created from this pool
107 // can work and return their Python counterparts.
108 virtual PyObject* DescriptorPool_FromPool(
109 const google::protobuf::DescriptorPool* pool) const = 0;
110 };
111
PyProtoAPICapsuleName()112 inline const char* PyProtoAPICapsuleName() {
113 static const char kCapsuleName[] = "google.protobuf.pyext._message.proto_API";
114 return kCapsuleName;
115 }
116
117 } // namespace python
118 } // namespace protobuf
119 } // namespace google
120
121 #endif // GOOGLE_PROTOBUF_PYTHON_PROTO_API_H__
122