Adding datastore Key.(to|from)_legacy_urlsafe. (#3491)

* Adding bare-minimum proto for converting legacy App Engine "Reference" pbs.

* Rough draft of working implementation of datastore Key.(to|from)_legacy_urlsafe.

Needs more tests but wanted to get the PR in front of reviewers ASAP.

* Adding implementation for datastore Key.to_legacy_urlsafe().

Also resolved some lint issues (line too long) and restructured
unit test to be able to re-use "stored" values.

* Adding _onestore_v3_pb2 to ignored files for flake8.

* Addressing @jonparrott feedback.

In particular:

- Just splitting on ~ when cleaning app strings
- Rewording to_legacy_urlsafe() docstring to invoke `ndb.Key(urlsafe=...)`
  and to restate the "returns" text
- Removing the _urlsafe_b64(decode|encode) micro-optimizations that
  were brought over from the ndb codebase

* Adding test coverage for helpers needed for Key.(to|from)_legacy_urlsafe.

* Adding LICENSE header to hand-written legacy GAE proto.

* Renaming _onestore_v3.proto --> _app_engine_key.proto.

Author: dhermes

packages/google-cloud-datastore/.coveragerc

@@ -2,6 +2,8 @@
 branch = True
 
 [report]
+omit =
+    _app_engine_key_pb2.py
 fail_under = 100
 show_missing = True
 exclude_lines =

packages/google-cloud-datastore/.flake8

@@ -1,5 +1,10 @@
 [flake8]
 exclude =
+  # Datastore includes generated code in the manual layer;
+  # do not lint this.
+  google/cloud/datastore/_app_engine_key_pb2.py,
+
+  # Standard linting exemptions.
   __pycache__,
   .git,
   *.pyc,

packages/google-cloud-datastore/google/cloud/datastore/_app_engine_key.proto

@@ -0,0 +1,30 @@
+// Copyright 2017 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto2";
+
+message Reference {
+  required string app = 13;
+  optional string name_space = 20;
+  required Path path = 14;
+  optional string database_id = 23;
+}
+
+message Path {
+  repeated group Element = 1 {
+    required string type = 2;
+    optional int64 id = 3;
+    optional string name = 4;
+  }
+}