Paper over custom command limitations

The custom gRPC bdist command depends on numerous undocumented and
private behaviors of setuptools, wheel, distutils, etc. One such is the
ordering of generated distribution targets. We paper over this under the
assumption that the command will only be useful for gRPC devs, and
document with a command description a contractual obligation of users of
the command.

1 files changed, 10 insertions, 0 deletions

diff --git a/src/python/grpcio/commands.py b/src/python/grpcio/commands.py
index 1561bbf05e..eb5cbb34f0 100644
--- a/src/python/grpcio/commands.py
+++ b/src/python/grpcio/commands.py
@@ -187,7 +187,17 @@ class Install(install.install, WheelNameMixin):
 class BdistWheelCustomName(bdist_wheel.bdist_wheel, WheelNameMixin):
   """Thin wrapper around the bdist command to build with our custom name."""
 
+  description = ("Create a gRPC custom-named wheel distribution. "
+                 "Cannot be run with any other distribution-related command.")
+
   def run(self):
+    # TODO(atash): if the hack we use to support Linux binaries becomes
+    # 'supported' (i.e.
+    # https://bitbucket.org/pypa/pypi/issues/120/binary-wheels-for-linux-are-not-supported
+    # is not solved and we see users beginning to use this command, ill-advised
+    # as that may be) consider making the following capable of running with
+    # other distribution-related commands. Currently it depends on the (AFAIK
+    # undocumented, private) ordering of the distribution files.
     bdist_wheel.bdist_wheel.run(self)
     output = self.distribution.dist_files[-1][2]
     target = os.path.join(self.dist_dir, '{}.whl'.format(self.wheel_name(True)))