8000 docs: explain how to use repeated struct.Value (#148) · googleapis/proto-plus-python@9634ea8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 9634ea8

Browse files
busunkim96busunkim96
authored
docs: explain how to use repeated struct.Value (#148)
Closes #104 Explain how to set fields of repeated struct.Value Add datetime_helpers to reference docs Add wrap, to_json, and from_json to reference docs Fetch correct package version for docs/conf.py
1 parent 5236895 commit 9634ea8

File tree

5 files changed

+49
-7
lines changed

5 files changed

+49
-7
lines changed

‎docs/conf.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,19 @@
1515
import os
1616
import sys
1717

18+
import pkg_resources
19+
20+
1821
sys.path.insert(0, os.path.abspath(".."))
1922

2023

2124
# -- Project information -----------------------------------------------------
2225

2326
project = "Proto Plus for Python"
2427
copyright = "2018, Google LLC"
25-
author = "Luke Sneeringer"
28+
author = "Google LLC"
2629

27-
# The short X.Y version
28-
version = "0.1.0"
29-
# The full version, including alpha/beta/rc tags
30-
release = "0.1.0"
30+
version = pkg_resources.get_distribution("proto-plus").version
3131

3232

3333
# -- General configuration ---------------------------------------------------

‎docs/fields.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,36 @@ Declare them in Python using the :class:`~.RepeatedField` class:
5656
publisher = proto.Field(proto.STRING, number=2)
5757
5858
59+
.. note::
60+
61+
Elements **must** be appended individually for repeated fields of `struct.Value`.
62+
63+
.. code-block:: python
64+
65+
class Row(proto.Message):
66+
values = proto.RepeatedField(proto.MESSAGE, number=1, message=struct.Value,)
67+
68+
>>> row = Row()
69+
>>> values = [struct_pb2.Value(string_value="hello")]
70+
>>> for v in values:
71+
>>> row.values.append(v)
72+
73+
Direct assignment will result in an error.
74+
75+
.. code-block:: python
76+
77+
class Row(proto.Message):
78+
values = proto.RepeatedField(proto.MESSAGE, number=1, message=struct.Value,)
79+
80+
>>> row = Row()
81+
>>> row.values = [struct_pb2.Value(string_value="hello")]
82+
Traceback (most recent call last):
83+
File "<stdin>", line 1, in <module>
84+
File "/usr/local/google/home/busunkim/github/python-automl/.nox/unit-3-8/lib/python3.8/site-packages/proto/message.py", line 543, in __setattr__
85+
self._pb.MergeFrom(self._meta.pb(**{key: pb_value}))
86+
TypeError: Value must be iterable
87+
88+
5989
Map fields
6090
----------
6191

@@ -168,3 +198,6 @@ one-variant ``oneof``. See the protocolbuffers documentation_ for more
168198
information.
169199

170200
.. _documentation: https://github.com/protocolbuffers/protobuf/blob/v3.12.0/docs/field_presence.md
201+
202+
203+

‎docs/reference/datetime_helpers.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Datetime Helpers
2+
----------------
3+
4+
.. automodule:: proto.datetime_helpers
5+
:members:

‎docs/reference/index.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,16 @@ Reference
44
Below is a reference for the major classes and functions within this
55
module.
66

7-
It is split into two main sections:
8-
97
- The :doc:`message` section (which uses the ``message`` and ``fields``
108
modules) handles constructing messages.
119
- The :doc:`marshal` module handles translating between internal protocol
1210
buffer instances and idiomatic equivalents.
11+
- The :doc:`datetime_helpers` has datetime related helpers to maintain
12+
nanosecond precision.
1313

1414
.. toctree::
1515
:maxdepth: 2
1616

1717
message
1818
marshal
19+
datetime_helpers

‎docs/reference/message.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,11 @@ Message and Field
55
:members:
66

77
.. automethod:: pb
8+
.. automethod:: wrap
89
.. automethod:: serialize
910
.. automethod:: deserialize
11+
.. automethod:: to_json
12+
.. automethod:: from_json
1013

1114

1215
.. automodule:: proto.fields

0 commit comments

Comments
 (0)
0