Support python for bazel.

BUILD

@@ -463,6 +463,21 @@ java_library(
 # Python support
 ################################################################################
 
+# Hack:
+# protoc generated files contain imports like:
+#   "from google.protobuf.xxx import yyy"
+# However, the sources files of the python runtime are not directly under
+# "google/protobuf" (they are under python/google/protobuf).  We workaround
+# this by copying runtime source files into the desired location to workaround
+# the import issue. Ideally py_library should support something similiar to the
+# "include" attribute in cc_library to inject the PYTHON_PATH for all libraries
+# that depend on the target.
+#
+# If you use python protobuf as a third_party library in your bazel managed
+# project, please import the whole package to //google/protobuf in your
+# project. Otherwise, bazel disallows generated files out of the current
+# package, thus we won't be able to copy protobuf runtime files into
+# //google/protobuf/.
 copied_srcs(
     name = "python_srcs",
     srcs = glob(

protobuf.bzl

@@ -160,6 +160,15 @@ def copied_srcs(
         srcs,
         include,
         **kargs):
+  """Bazel rule to fix sources file to workaround with python path issues.
+
+  Args:
+    name: the name of the copied_srcs rule, which will be the name of the
+        generated filegroup.
+    srcs: the source files to be copied.
+    include: the expected import root of the source.
+    **kargs: extra arguments that will be passed into the filegroup.
+  """
   outs = [_RelativeOutputPath(s, include) for s in srcs]
 
   native.genrule(
@@ -185,6 +194,21 @@ def py_proto_library(
         include=None,
         protoc=":protoc",
         **kargs):
+  """Bazel rule to create a Python protobuf library from proto source files
+
+  Args:
+    name: the name of the py_proto_library.
+    srcs: the .proto files of the py_proto_library.
+    deps: a list of dependency labels; must be py_proto_library.
+    py_libs: a list of other py_library targets depended by the generated
+        py_library.
+    py_extra_srcs: extra source files that will be added to the output
+        py_library. This attribute is used for internal bootstrapping.
+    include: a string indicating the include path of the .proto files.
+    protoc: the label of the protocol compiler to generate the sources.
+    **kargs: other keyword arguments that are passed to cc_library.
+
+  """
   outs = _PyOuts(srcs)
   _proto_gen(
       name=name + "_genproto",
@@ -196,8 +220,9 @@ def py_proto_library(
       outs=outs,
   )
 
-  copied_srcs_name=name + "_copied_srcs"
   if include != None:
+    # Copy the output files to the desired location to make the import work.
+    copied_srcs_name=name + "_copied_srcs"
     copied_srcs(
         name=copied_srcs_name,
         srcs=outs,
@@ -214,9 +239,20 @@ def internal_protobuf_py_tests(
     name,
     modules=[],
     **kargs):
+  """Bazel rules to create batch tests for protobuf internal.
+
+  Args:
+    name: the name of the rule.
+    modules: a list of modules for tests. The macro will create a py_test for
+        each of the parameter with the source "google/protobuf/%s.py"
+    kargs: extra parameters that will be passed into the py_test.
+
+  """
   for m in modules:
+    s = _RelativeOutputPath(
+        "python/google/protobuf/internal/%s.py" % m, "python")
     native.py_test(
         name="py_%s" % m,
-        srcs=["google/protobuf/internal/%s.py" % m],
-        main="google/protobuf/internal/%s.py" % m,
+        srcs=[s],
+        main=s,
         **kargs)