Merge branch 'main' into fix/replace-repeated-deepcopy-with-attribute…

…-lookup
googleapis · Apr 29, 2022 · dec4d6f · dec4d6f
2 parents 51ee0ad + cf3240f
commit dec4d6f
Show file tree

Hide file tree

Showing 51 changed files with 1,224 additions and 128 deletions.
diff --git a/.github/release-please.yml b/.github/release-please.yml
@@ -1 +1,2 @@
 releaseType: python
+handleGHRelease: true
diff --git a/.github/release-trigger.yml b/.github/release-trigger.yml
@@ -0,0 +1,2 @@
+enabled: true
+
diff --git a/.github/sync-repo-settings.yaml b/.github/sync-repo-settings.yaml
@@ -2,7 +2,7 @@ rebaseMergeAllowed: false
 squashMergeAllowed: true
 mergeCommitAllowed: false
 branchProtectionRules:
-- pattern: master
+- pattern: main
   isAdminEnforced: true
   requiredStatusCheckContexts:
     - 'style-check'

diff --git a/.github/workflows/pypi-upload.yaml b/.github/workflows/pypi-upload.yaml
@@ -10,7 +10,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v3
       with:
         python-version: '3.x'
     - name: Install dependencies

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -14,28 +14,28 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
-        uses: styfle/[email protected].0
+        uses: styfle/[email protected].1
         with:
           access_token: ${{ github.token }}
       - uses: actions/checkout@v2
       - name: Set up Python 3.8
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: 3.8
       - name: Install black
-        run: pip install black==19.10b0
+        run: pip install black==22.3.0
       - name: Check diff
         run: black --diff --check .
   docs:
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
-        uses: styfle/[email protected].0
+        uses: styfle/[email protected].1
         with:
           access_token: ${{ github.token }}
       - uses: actions/checkout@v2
       - name: Set up Python 3.8
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: 3.8
       - name: Install nox.
@@ -46,16 +46,16 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: [3.6, 3.7, 3.8, 3.9]
+        python: ['3.6', '3.7', '3.8', '3.9', '3.10']
         variant: ['', cpp]
     steps:
       - name: Cancel Previous Runs
-        uses: styfle/[email protected].0
+        uses: styfle/[email protected].1
         with:
           access_token: ${{ github.token }}
       - uses: actions/checkout@v2
       - name: Set up Python ${{ matrix.python }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: ${{ matrix.python }}
       - name: Install nox and codecov.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,101 @@
 # Changelog
 
+### [1.20.3](https://github.com/googleapis/proto-plus-python/compare/v1.20.2...v1.20.3) (2022-02-18)
+
+
+### Bug Fixes
+
+* additional logic to mitigate collisions with reserved terms ([#301](https://github.com/googleapis/proto-plus-python/issues/301)) ([c9a77df](https://github.com/googleapis/proto-plus-python/commit/c9a77df58e93a87952470d809538a08103644364))
+
+### [1.20.2](https://github.com/googleapis/proto-plus-python/compare/v1.20.1...v1.20.2) (2022-02-17)
+
+
+### Bug Fixes
+
+* dir(proto.Message) does not raise ([#302](https://github.com/googleapis/proto-plus-python/issues/302)) ([80dcce9](https://github.com/googleapis/proto-plus-python/commit/80dcce9099e630a6217792b6b3a14213add690e6))
+
+### [1.20.1](https://github.com/googleapis/proto-plus-python/compare/v1.20.0...v1.20.1) (2022-02-14)
+
+
+### Bug Fixes
+
+* mitigate collisions in field names ([#295](https://github.com/googleapis/proto-plus-python/issues/295)) ([158ae99](https://github.com/googleapis/proto-plus-python/commit/158ae995aa4fdf6239c864a41f5df5575a3c30b3))
+
+## [1.20.0](https://github.com/googleapis/proto-plus-python/compare/v1.19.9...v1.20.0) (2022-02-07)
+
+
+### Features
+
+* add custom __dir__ for messages and message classes ([#289](https://github.com/googleapis/proto-plus-python/issues/289)) ([35e019e](https://github.com/googleapis/proto-plus-python/commit/35e019eb8155c1e4067b326804e3e7e86f85b6a8))
+
+
+### Bug Fixes
+
+* workaround for buggy pytest ([#291](https://github.com/googleapis/proto-plus-python/issues/291)) ([28aa3b2](https://github.com/googleapis/proto-plus-python/commit/28aa3b2b325d2ba262f35cfc8d20e1f5fbdcf883))
+
+### [1.19.9](https://github.com/googleapis/proto-plus-python/compare/v1.19.8...v1.19.9) (2022-01-25)
+
+
+### Bug Fixes
+
+* add pickling support to proto messages ([#280](https://github.com/googleapis/proto-plus-python/issues/280)) ([2b7be35](https://github.com/googleapis/proto-plus-python/commit/2b7be3563f9fc2a4649a5e14d7653b85020c566f))
+
+### [1.19.8](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.7...v1.19.8) (2021-11-09)
+
+
+### Documentation
+
+* fix typos ([#277](https://www.github.com/googleapis/proto-plus-python/issues/277)) ([e3b71e8](https://www.github.com/googleapis/proto-plus-python/commit/e3b71e8b2a81a5abb5af666c9625facb1814a609))
+
+### [1.19.7](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.6...v1.19.7) (2021-10-27)
+
+
+### Bug Fixes
+
+* restore allowing None as value for stringy ints ([#272](https://www.github.com/googleapis/proto-plus-python/issues/272)) ([a8991d7](https://www.github.com/googleapis/proto-plus-python/commit/a8991d71ff455093fbfef142f9140d3f2928195f))
+
+### [1.19.6](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.5...v1.19.6) (2021-10-25)
+
+
+### Bug Fixes
+
+* setting 64bit fields from strings supported ([#267](https://www.github.com/googleapis/proto-plus-python/issues/267)) ([ea7b911](https://www.github.com/googleapis/proto-plus-python/commit/ea7b91100114f5c3d40d41320b045568ac9a68f9))
+
+### [1.19.5](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.4...v1.19.5) (2021-10-11)
+
+
+### Documentation
+
+* Clarify semantics of multiple oneof variants passed to msg ctor ([#263](https://www.github.com/googleapis/proto-plus-python/issues/263)) ([6f8a5b2](https://www.github.com/googleapis/proto-plus-python/commit/6f8a5b2098e4f6748945c53bda3d5821e62e5a0a))
+
+### [1.19.4](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.3...v1.19.4) (2021-10-08)
+
+
+### Documentation
+
+* clarify that proto plus messages are not pickleable ([#260](https://www.github.com/googleapis/proto-plus-python/issues/260)) ([6e691dc](https://www.github.com/googleapis/proto-plus-python/commit/6e691dc27b1e540ef0661597fd89ece8f0155c97))
+
+### [1.19.3](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.2...v1.19.3) (2021-10-07)
+
+
+### Bug Fixes
+
+* setting bytes field from python string base64 decodes before assignment ([#255](https://www.github.com/googleapis/proto-plus-python/issues/255)) ([b6f3eb6](https://www.github.com/googleapis/proto-plus-python/commit/b6f3eb6575484748126170997b8c98512763ea66))
+
+### [1.19.2](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.1...v1.19.2) (2021-09-29)
+
+
+### Bug Fixes
+
+* ensure enums are hashable ([#252](https://www.github.com/googleapis/proto-plus-python/issues/252)) ([232341b](https://www.github.com/googleapis/proto-plus-python/commit/232341b4f4902fba1b3597bb1e1618b8f320374b))
+
+### [1.19.1](https://www.github.com/googleapis/proto-plus-python/compare/v1.19.0...v1.19.1) (2021-09-29)
+
+
+### Bug Fixes
+
+* ensure enums are incomparable w other enum types ([#248](https://www.github.com/googleapis/proto-plus-python/issues/248)) ([5927c14](https://www.github.com/googleapis/proto-plus-python/commit/5927c1400f400b3213c9b92e7a37c3c3a1abd681))
+
 ## [1.19.0](https://www.github.com/googleapis/proto-plus-python/compare/v1.18.1...v1.19.0) (2021-06-29)
 
 

diff --git a/docs/fields.rst b/docs/fields.rst
@@ -151,6 +151,33 @@ a string (which should match for all fields within the oneof):
     have consecutive field numbers, but they must be declared in consecutive
     order.
 
+.. warning::
+
+   If a message is constructed with multiple variants of a single ``oneof`` passed
+   to its constructor, the **last** keyword/value pair passed will be the final
+   value set.
+
+   This is consistent with PEP-468_, which specifies the order that keyword args
+   are seen by called functions, and with the regular protocol buffers runtime,
+   which exhibits the same behavior.
+
+   Example:
+
+   .. code-block:: python
+
+      import proto
+
+      class Song(proto.Message):
+          name = proto.Field(proto.STRING, number=1, oneof="identifier")
+          database_id = proto.Field(proto.STRING, number=2, oneof="identifier")
+
+      s = Song(name="Canon in D minor", database_id="b5a37aad3")
+      assert "database_id" in s and "name" not in s
+
+      s = Song(database_id="e6aa708c7e", name="Little Fugue")
+      assert "name" in s and "database_id" not in s
+
+
 
 Optional fields
 ---------------
@@ -199,5 +226,4 @@ information.
 
 .. _documentation: https://github.com/protocolbuffers/protobuf/blob/v3.12.0/docs/field_presence.md
 
-
-
+.. _PEP-468: https://www.python.org/dev/peps/pep-0468/
diff --git a/docs/marshal.rst b/docs/marshal.rst
@@ -44,7 +44,35 @@ Protocol buffer type                Python type             Nullable
     If you *write* a timestamp field using a Python ``datetime`` value,
     any existing nanosecond precision will be overwritten.
 
+.. note::
+
+   Setting a ``bytes`` field from a string value will first base64 decode the string.
+   This is necessary to preserve the original protobuf semantics when converting between
+   Python dicts and proto messages.
+   Converting a message containing a bytes field to a dict will
+   base64 encode the bytes field and yield a value of type str.
+
+.. code-block:: python
+
+  import proto
+  from google.protobuf.json_format import ParseDict
+
+  class MyMessage(proto.Message):
+      data = proto.Field(proto.BYTES, number=1)
+
+  msg = MyMessage(data=b"this is a message")
+  msg_dict = MyMessage.to_dict(msg)
+
+  # Note: the value is the base64 encoded string of the bytes field.
+  # It has a type of str, NOT bytes.
+  assert type(msg_dict['data']) == str
+
+  msg_pb = ParseDict(msg_dict, MyMessage.pb())
+  msg_two = MyMessage(msg_dict)
 
+  assert msg == msg_pb == msg_two
+      
+  
 Wrapper types
 -------------
 

diff --git a/docs/messages.rst b/docs/messages.rst
@@ -129,7 +129,7 @@ just as if it were a regular python object.
       song.composer = composer
       composer.given_name = "Carl"
 
-      # 'composer' is STILL not a referene to song.composer.
+      # 'composer' is STILL not a reference to song.composer.
       assert song.composer.given_name == "Wilhelm"
 
       # It does work in reverse, though,
@@ -243,3 +243,35 @@ already allows construction from mapping types.
    song_dict = Song.to_dict(song)
 
    new_song = Song(song_dict)
+
+.. note::
+
+   Although Python's pickling protocol has known issues when used with
+   untrusted collaborators, some frameworks do use it for communication
+   between trusted hosts.  To support such frameworks, protobuf messages
+   **can** be pickled and unpickled, although the preferred mechanism for
+   serializing proto messages is :meth:`~.Message.serialize`.
+
+   Multiprocessing example:
+
+   .. code-block:: python
+
+       import proto
+       from multiprocessing import Pool
+
+       class Composer(proto.Message):
+          name = proto.Field(proto.STRING, number=1)
+          genre = proto.Field(proto.STRING, number=2)
+
+       composers = [Composer(name=n) for n in ["Bach", "Mozart", "Brahms", "Strauss"]]
+
+       with multiprocessing.Pool(2) as p:
+          def add_genre(comp_bytes):
+              composer = Composer.deserialize(comp_bytes)
+              composer.genre = "classical"
+              return Composer.serialize(composer)
+
+       updated_composers = [
+          Composer.deserialize(comp_bytes)
+          for comp_bytes in p.map(add_genre, (Composer.serialize(comp) for comp in composers))
+       ]
diff --git a/noxfile.py b/noxfile.py
@@ -22,7 +22,16 @@
 CURRENT_DIRECTORY = pathlib.Path(__file__).parent.absolute()
 
 
-@nox.session(python=["3.6", "3.7", "3.8", "3.9"])
+PYTHON_VERSIONS = [
+    "3.6",
+    "3.7",
+    "3.8",
+    "3.9",
+    "3.10",
+]
+
+
+@nox.session(python=PYTHON_VERSIONS)
 def unit(session, proto="python"):
     """Run the unit test suite."""
 
@@ -54,12 +63,13 @@ def unit(session, proto="python"):
 # Check if protobuf has released wheels for new python versions
 # https://pypi.org/project/protobuf/#files
 # This list will generally be shorter than 'unit'
-@nox.session(python=["3.6", "3.7", "3.8", "3.9"])
+@nox.session(python=PYTHON_VERSIONS)
 def unitcpp(session):
     return unit(session, proto="cpp")
 
 
-@nox.session(python="3.7")
+# Just use the most recent version for docs
+@nox.session(python=PYTHON_VERSIONS[-1])
 def docs(session):
     """Build the docs."""
 

diff --git a/proto/_file_info.py b/proto/_file_info.py
@@ -40,7 +40,9 @@ def maybe_add_descriptor(cls, filename, package):
         if not descriptor:
             descriptor = cls.registry[filename] = cls(
                 descriptor=descriptor_pb2.FileDescriptorProto(
-                    name=filename, package=package, syntax="proto3",
+                    name=filename,
+                    package=package,
+                    syntax="proto3",
                 ),
                 enums=collections.OrderedDict(),
                 messages=collections.OrderedDict(),

diff --git a/proto/datetime_helpers.py b/proto/datetime_helpers.py
@@ -63,7 +63,7 @@ def _to_rfc3339(value, ignore_zone=True):
             datetime object is ignored and the datetime is treated as UTC.
 
     Returns:
-        str: The RFC3339 formated string representing the datetime.
+        str: The RFC3339 formatted string representing the datetime.
     """
     if not ignore_zone and value.tzinfo is not None:
         # Convert to UTC and remove the time zone info.
@@ -97,7 +97,7 @@ def replace(self, *args, **kw):
         new values by whichever keyword arguments are specified. For example,
         if d == date(2002, 12, 31), then
         d.replace(day=26) == date(2002, 12, 26).
-        NOTE: nanosecond and microsecond are mutually exclusive arguemnts.
+        NOTE: nanosecond and microsecond are mutually exclusive arguments.
         """
 
         ms_provided = "microsecond" in kw
@@ -171,7 +171,7 @@ def from_rfc3339(cls, stamp):
             nanos = 0
         else:
             scale = 9 - len(fraction)
-            nanos = int(fraction) * (10 ** scale)
+            nanos = int(fraction) * (10**scale)
         return cls(
             bare.year,
             bare.month,