googlecloud 0.0.4 → 0.0.6

data/packages/gsutil/boto/tox.ini

@@ -0,0 +1,8 @@
+[tox]
+envlist = py26,py27
+
+
+[testenv]
+commands =
+    pip install -qr requirements.txt
+    python tests/test.py tests/unit

data/packages/gsutil/gslib/README

@@ -0,0 +1,5 @@
+This directory contains library code used by gsutil. Users are cautioned not
+to write programs that call the internal interfaces defined in here; these
+interfaces were defined only for use by gsutil, and are subject to change
+without notice. Moreover, Google supports this library only when used by
+gsutil, not when the library interfaces are called directly by other programs.

data/packages/gsutil/gslib/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2010 Google Inc. All Rights Reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish, dis-
+# tribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the fol-
+# lowing conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
+# ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+# SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+"""Package marker file."""

data/packages/gsutil/gslib/addlhelp/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2012 Google Inc. All Rights Reserved.
+#
+# 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.
+
+"""Package marker file."""

data/packages/gsutil/gslib/addlhelp/acls.py

@@ -0,0 +1,234 @@
+# Copyright 2012 Google Inc. All Rights Reserved.
+#
+# 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.
+
+from gslib.help_provider import HELP_NAME
+from gslib.help_provider import HELP_NAME_ALIASES
+from gslib.help_provider import HELP_ONE_LINE_SUMMARY
+from gslib.help_provider import HelpProvider
+from gslib.help_provider import HELP_TEXT
+from gslib.help_provider import HelpType
+from gslib.help_provider import HELP_TYPE
+
+_detailed_help_text = ("""
+<B>OVERVIEW</B>
+  Access Control Lists (ACLs) allow you to control who can read and write
+  your data, and who can read and write the ACLs themselves.
+
+  If not specified at the time an object is uploaded (e.g., via the gsutil cp
+  -a option), objects will be created with a default object ACL set on the
+  bucket (see "gsutil help setdefacl"). You can replace the ACL on an object
+  or bucket using the gsutil setacl command (see "gsutil help setacl"), or
+  modify the existing ACL using the gsutil chacl command (see "gsutil help
+  chacl").
+
+
+<B>BUCKET VS OBJECT ACLS</B>
+  In Google Cloud Storage, the bucket ACL works as follows:
+
+    - Users granted READ access are allowed to list the bucket contents.
+
+    - Users granted WRITE access are allowed READ access and also are
+      allowed to write and delete objects in that bucket -- including
+      overwriting previously written objects.
+
+    - Users granted FULL_CONTROL access are allowed WRITE access and also
+      are allowed to read and write the bucket's ACL.
+
+  The object ACL works as follows:
+
+    - Users granted READ access are allowed to read the object's data and
+      metadata.
+
+    - Users granted FULL_CONTROL access are allowed READ access and also
+      are allowed to read and write the object's ACL.
+
+  A couple of points are worth noting, that sometimes surprise users:
+
+  1. There is no WRITE access for objects; attempting to set an ACL with WRITE
+     permission for an object will result in an error.
+
+  2. The bucket ACL plays no role in determining who can read objects; only the
+     object ACL matters for that purpose. This is different from how things
+     work in Linux file systems, where both the file and directory permission
+     control file read access. It also means, for example, that someone with
+     FULL_CONTROL over the bucket may not have read access to objects in
+     the bucket.  This is by design, and supports useful cases. For example,
+     you might want to set up bucket ownership so that a small group of
+     administrators have FULL_CONTROL on the bucket (with the ability to
+     delete data to control storage costs), but not grant those users read
+     access to the object data (which might be sensitive data that should
+     only be accessed by a different specific group of users).
+
+
+<B>CANNED ACLS</B>
+  The simplest way to set an ACL on a bucket or object is using a "canned
+  ACL". The available canned ACLs are:
+
+  project-private            Gives permission to the project team based on their
+                             roles. Anyone who is part of the team has READ
+                             permission, and project owners and project editors
+                             have FULL_CONTROL permission. This is the default
+                             ACL for newly created buckets. This is also the
+                             default ACL for newly created objects unless the
+                             default object ACL for that bucket has been
+                             changed. For more details see
+                             "gsutil help projects".
+
+  private                    Gives the requester (and only the requester)
+                             FULL_CONTROL permission for a bucket or object.
+
+  public-read                Gives the requester FULL_CONTROL permission and
+                             gives all users READ permission. When you apply
+                             this to an object, anyone on the Internet can
+                             read the object without authenticating.
+
+  public-read-write          Gives the requester FULL_CONTROL permission and
+                             gives all users READ and WRITE permission. This
+                             ACL applies only to buckets.
+
+  authenticated-read         Gives the requester FULL_CONTROL permission and
+                             gives all authenticated Google account holders
+                             READ permission.
+
+  bucket-owner-read          Gives the requester FULL_CONTROL permission and
+                             gives the bucket owner READ permission. This is
+                             used only with objects.
+
+  bucket-owner-full-control  Gives the requester FULL_CONTROL permission and
+                             gives the bucket owner FULL_CONTROL
+                             permission. This is used only with objects.
+
+
+<B>ACL XML</B>
+  When you use a canned ACL, it is translated into an XML representation
+  that can later be retrieved and edited to specify more fine-grained
+  detail about who can read and write buckets and objects. By running
+  the gsutil getacl command you can retrieve the ACL XML, and edit it to
+  customize the permissions.
+
+  As an example, if you create an object in a bucket that has no default
+  object ACL set and then retrieve the ACL on the object, it will look
+  something like this:
+
+  <AccessControlList>
+    <Owner>
+      <ID>
+        00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7
+      </ID>
+    </Owner>
+    <Entries>
+      <Entry>
+        <Scope type="GroupById">
+          <ID>
+            00b4903a9740e42c29800f53bd5a9a62a2f96eb3f64a4313a115df3f3a776bf7
+          </ID>
+        </Scope>
+        <Permission>
+          FULL_CONTROL
+        </Permission>
+      </Entry>
+      <Entry>
+        <Scope type="GroupById">
+          <ID>
+            00b4903a977fd817e9da167bc81306489181a110456bb635f466d71cf90a0d51
+          </ID>
+        </Scope>
+        <Permission>
+          FULL_CONTROL
+        </Permission>
+      </Entry>
+      <Entry>
+        <Scope type="GroupById">
+          <ID>
+            00b4903a974898cc8fc309f2f2835308ba3d3df1b889d3fc7e33e187d52d8e71
+          </ID>
+        </Scope>
+        <Permission>
+          READ
+        </Permission>
+      </Entry>
+    </Entries>
+  </AccessControlList>
+
+  The ACL consists of an Owner element and a collection of Entry elements,
+  each of which specifies a Scope and a Permission. Scopes are the way you
+  specify an individual or group of individuals, and Permissions specify what
+  access they're permitted.
+
+  This particular ACL grants FULL_CONTROL to two groups (which means members
+  of those groups are allowed to read the object and read and write the ACL),
+  and READ permission to a third group. The project groups are (in order)
+  the owners group, editors group, and viewers group.
+
+  The 64 digit hex identifiers used in this ACL are called canonical IDs,
+  and are used to identify predefined groups associated with the project that
+  owns the bucket. For more information about project groups, see "gsutil
+  help projects".
+
+  Here's an example of an ACL specified using the GroupByEmail and GroupByDomain
+  scopes:
+
+  <AccessControlList>
+    <Entries>
+      <Entry>
+        <Permission>
+          FULL_CONTROL
+        </Permission>
+        <Scope type="GroupByEmail">
+          <EmailAddress>travel-companion-owners@googlegroups.com</EmailAddress>
+        </Scope>
+      </Entry>
+      <Entry>
+        <Permission>
+          READ
+        </Permission>
+        <Scope type="GroupByDomain">
+          <Domain>example.com</Domain>
+        </Scope>
+      </Entry>
+    </Entries>
+  </AccessControlList>
+
+  This ACL grants members of an email group FULL_CONTROL, and grants READ
+  access to any user in a domain (which must be a Google Apps for Business
+  domain). By applying email group grants to a collection of objects
+  you can edit access control for large numbers of objects at once via
+  http://groups.google.com. That way, for example, you can easily and quickly
+  change access to a group of company objects when employees join and leave
+  your company (i.e., without having to individually change ACLs across
+  potentially millions of objects).
+
+
+<B>SHARING SCENARIOS</B>
+  For more detailed examples how to achieve various useful sharing use
+  cases see https://developers.google.com/storage/docs/collaboration
+""")
+
+
+class CommandOptions(HelpProvider):
+  """Additional help about Access Control Lists."""
+
+  help_spec = {
+    # Name of command or auxiliary help info for which this help applies.
+    HELP_NAME : 'acls',
+    # List of help name aliases.
+    HELP_NAME_ALIASES : ['acl', 'ACL', 'access control', 'access control list',
+                         'authorization', 'canned', 'canned acl'],
+    # Type of help:
+    HELP_TYPE : HelpType.ADDITIONAL_HELP,
+    # One line summary of this help.
+    HELP_ONE_LINE_SUMMARY : 'Working with Access Control Lists',
+    # The full help text.
+    HELP_TEXT : _detailed_help_text,
+  }

data/packages/gsutil/gslib/addlhelp/anon.py

@@ -0,0 +1,57 @@
+# Copyright 2012 Google Inc. All Rights Reserved.
+#
+# 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.
+
+from gslib.help_provider import HELP_NAME
+from gslib.help_provider import HELP_NAME_ALIASES
+from gslib.help_provider import HELP_ONE_LINE_SUMMARY
+from gslib.help_provider import HelpProvider
+from gslib.help_provider import HELP_TEXT
+from gslib.help_provider import HelpType
+from gslib.help_provider import HELP_TYPE
+
+_detailed_help_text = ("""
+<B>OVERVIEW</B>
+  gsutil users can access publicly readable data without obtaining
+  credentials. For example, the gs://uspto-pair bucket contains a number
+  of publicly readable objects, so any user can run the following command
+  without first obtaining credentials:
+
+    gsutil ls gs://uspto-pair/applications/0800401*
+
+  Users can similarly download objects they find via the above gsutil ls
+  command.
+
+  If a user without credentials attempts to access protected data using gsutil,
+  they will be prompted to run "gsutil config" to obtain credentials.
+
+  See "gsutil help acls" for more details about data protection.
+""")
+
+
+class CommandOptions(HelpProvider):
+  """Additional help about Access Control Lists."""
+
+  help_spec = {
+    # Name of command or auxiliary help info for which this help applies.
+    HELP_NAME : 'anon',
+    # List of help name aliases.
+    HELP_NAME_ALIASES : ['anonymous', 'public'],
+    # Type of help:
+    HELP_TYPE : HelpType.ADDITIONAL_HELP,
+    # One line summary of this help.
+    HELP_ONE_LINE_SUMMARY :
+        'Accessing public data without obtaining credentials',
+    # The full help text.
+    HELP_TEXT : _detailed_help_text,
+  }

data/packages/gsutil/gslib/addlhelp/command_opts.py

@@ -0,0 +1,116 @@
+# Copyright 2012 Google Inc. All Rights Reserved.
+#
+# 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.
+
+from gslib.help_provider import HELP_NAME
+from gslib.help_provider import HELP_NAME_ALIASES
+from gslib.help_provider import HELP_ONE_LINE_SUMMARY
+from gslib.help_provider import HelpProvider
+from gslib.help_provider import HELP_TEXT
+from gslib.help_provider import HelpType
+from gslib.help_provider import HELP_TYPE
+
+_detailed_help_text = ("""
+<B>SYNOPSIS</B>
+  Top-level gsutil Options
+
+
+<B>DESCRIPTION</B>
+  gsutil supports separate options for the top-level gsutil command and
+  the individual sub-commands (like cp, rm, etc.) The top-level options
+  control behavior of gsutil that apply across commands. For example, in
+  the command:
+
+    gsutil -m cp -p file gs://bucket/obj
+
+  the -m option applies to gsutil, while the -p option applies to the cp
+  sub-command.
+
+
+<B>OPTIONS</B>
+  -d          Shows HTTP requests/headers.
+
+  -D          Shows HTTP requests/headers plus additional debug info needed when
+              posting support requests.
+
+  -DD         Shows HTTP requests/headers plus additional debug info plus HTTP
+              upstream payload.
+
+  -h          Allows you to specify additional HTTP headers, for example:
+
+                gsutil -h "Cache-Control:public,max-age=3600" \\
+                       -h "Content-Type:text/html" cp ...
+
+              Note that you need to quote the headers/values that
+              contain spaces (such as "Content-Disposition: attachment;
+              filename=filename.ext"), to avoid having the shell split them
+              into separate arguments.
+
+              Note that because the -h option allows you to specify any HTTP
+              header, it is both powerful and potentially dangerous:
+                - It is powerful because it allows you to specify headers that
+                  gsutil doesn't currently know about (e.g., to request
+                  service features from a different storage service provider
+                  than Google); or to override the values gsutil would normally
+                  send with different values.
+                - It is potentially dangerous because you can specify headers
+                  that cause gsutil to send invalid requests, or that in
+                  other ways change the behavior of requests.
+              Thus, you should be sure you understand the underlying storage
+              service HTTP API (and what impact the headers you specify will
+              have) before using the gsutil -h option.
+
+              See also "gsutil help setmeta" for the ability to set metadata
+              fields on objects after they have been uploaded.
+
+  -m          Causes supported operations (cp, mv, rm, setacl, setmeta) to run
+              in parallel. This can significantly improve performance if you are
+              uploading, downloading, moving, removing, or changing ACLs on
+              a large number of files over a fast network connection.
+
+              gsutil performs the specified operation using a combination of
+              multi-threading and multi-processing, using a number of threads
+              and processors determined by the parallel_thread_count and
+              parallel_process_count values set in the boto configuration
+              file. You might want to experiment with these value, as the
+              best value can vary based on a number of factors, including
+              network speed, number of CPUs, and available memory.
+
+              Using the -m option may make your performance worse if you
+              are using a slower network, such as the typical network speeds
+              offered by non-business home network plans.
+
+              If a download or upload operation using parallel transfer fails
+              before the entire transfer is complete (e.g. failing after 300 of
+              1000 files have been transferred), you will need to restart the
+              entire transfer.
+
+  -s          Tells gsutil to use a simulated storage provider (for testing).
+""")
+
+
+class CommandOptions(HelpProvider):
+  """Additional help about gsutil command-level options."""
+
+  help_spec = {
+    # Name of command or auxiliary help info for which this help applies.
+    HELP_NAME : 'options',
+    # List of help name aliases.
+    HELP_NAME_ALIASES : ['arg', 'args', 'cli', 'opt', 'opts'],
+    # Type of help:
+    HELP_TYPE : HelpType.ADDITIONAL_HELP,
+    # One line summary of this help.
+    HELP_ONE_LINE_SUMMARY : 'gsutil-level command line options',
+    # The full help text.
+    HELP_TEXT : _detailed_help_text,
+  }