gcloud 0.0.4 → 0.0.6

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

@@ -0,0 +1,139 @@
+# 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>
+  We're open to incorporating gsutil code changes authored by users. Here
+  are some guidelines:
+
+  1. Before we can accept code submissions, we have to jump a couple of legal
+     hurdles. Please fill out either the individual or corporate Contributor
+     License Agreement:
+       - If you are an individual writing original source code and you're
+         sure you own the intellectual property,
+         then you'll need to sign an individual CLA
+         (http://code.google.com/legal/individual-cla-v1.0.html).
+       - If you work for a company that wants to allow you to contribute your
+         work to gsutil, then you'll need to sign a corporate CLA
+         (http://code.google.com/legal/corporate-cla-v1.0.html)
+
+     Follow either of the two links above to access the appropriate CLA and
+     instructions for how to sign and return it. Once we receive it, we'll
+     add you to the official list of contributors and be able to accept
+     your patches.
+
+  2. If you found a bug or have an idea for a feature enhancement, we suggest
+     you check http://code.google.com/p/gsutil/issues/list to see if it has
+     already been reported by another user. From there you can also add yourself
+     to the Cc list for an issue, so you will find out about any developments.
+
+  3. It's usually worthwhile to send email to gs-team@google.com about your
+     idea before sending actual code. Often we can discuss the idea and help
+     propose things that could save you later revision work.
+
+  4. We tend to avoid adding command line options that are of use to only
+     a very small fraction of users, especially if there's some other way
+     to accommodate such needs. Adding such options complicates the code and
+     also adds overhead to users having to read through an "alphabet soup"
+     list of option documentation.
+
+  5. While gsutil has a number of features specific to Google Cloud Storage,
+     it can also be used with other cloud storage providers. We're open to
+     including changes for making gsutil support features specific to other
+     providers, as long as those changes don't make gsutil work worse for Google
+     Cloud Storage. If you do make such changes we recommend including someone
+     with knowledge of the specific provider as a code reviewer (see below).
+
+  6. You can check out the gsutil code from svn  - see
+     http://code.google.com/p/gsutil/source/checkout. Then change directories
+     into gsutil/src, and check out the boto code from github:
+
+       git clone git://github.com/boto/boto.git
+
+  7. Please make sure to run all tests against your modified code. To
+     do this, change directories into the gsutil top-level directory and run:
+
+       ./gsutil test
+
+     The above tests take a long time to run because they send many requests to
+     the production service. The gsutil test command has a -u argument that will
+     only run unit tests. These run quickly, as they are executed with an
+     in-memory mock storage service implementation. To run only the unit tests,
+     run:
+
+       ./gsutil test -u
+
+    If you made mods to boto please run the boto tests. For these tests you
+    need to use HMAC credentials (from gsutil config -a), because the current
+    boto test suite doesn't import the OAuth2 handler. You'll also need to
+    install some python modules: change directories into the top-level gsutil
+    directory and run:
+
+      pip install -qr boto/requirements.txt
+
+    (You probably need to run this commad using sudo.)
+    Make sure each of the individual installations succeeded. If they don't
+    you may need to run individual ones again, e.g.,
+
+      pip install unittest2
+
+    Then ensure your .boto file has HMAC credentials defined (the boto tests
+    don't load the OAUTH2 plugin), and then change directories into boto/tests
+    and run:
+
+      python test.py unit
+      python test.py -t s3 -t gs -t ssl
+
+  8. Please consider contributing test code for your change, especially if the
+     change impacts any of the core gsutil code (like the gsutil cp command).
+
+  9. When it's time to send us code, please use the Rietveld code review tool
+     rather than simply sending us a code patch. Do this as follows:
+      - check out the gsutil code from at
+        http://code.google.com/p/gsutil/source/checkout and apply your changes
+        in the checked out directory.
+      - download the "upload.py" script from
+        http://code.google.com/p/rietveld/wiki/UploadPyUsage
+      - run upload.py from the above gsutil svn directory.
+      - click the codereview.appspot.com link it generates, click "Edit Issue",
+        and add mfschwartz@google.com as a reviewer, and Cc gs-team@google.com.
+      - click Publish+Mail Comments.
+""")
+
+
+
+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 : 'dev',
+    # List of help name aliases.
+    HELP_NAME_ALIASES : ['development', 'developer', 'code', 'mods',
+                         'software'],
+    # Type of help:
+    HELP_TYPE : HelpType.ADDITIONAL_HELP,
+    # One line summary of this help.
+    HELP_ONE_LINE_SUMMARY : 'Making modifications to gsutil',
+    # The full help text.
+    HELP_TEXT : _detailed_help_text,
+  }

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

@@ -0,0 +1,186 @@
+# 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 OF METADATA</B>
+  Objects can have associated metadata, which control aspects of how
+  GET requests are handled, including Content-Type, Cache-Control,
+  Content-Disposition, and Content-Encoding (discussed in more detail in
+  the subsections below). In addition, you can set custom metadata that
+  can be used by applications (e.g., tagging that particular objects possess
+  some property).
+
+  There are two ways to set metadata on objects:
+
+    - at upload time you can specify one or more headers to associate with
+      objects, using the gsutil -h option.  For example, the following command
+      would cause gsutil to set the Content-Type and Cache-Control for each
+      of the files being uploaded:
+
+        gsutil -h "Content-Type:text/html" -h "Cache-Control:public, max-age=3600" cp -r images gs://bucket/images
+
+      Note that -h is an option on the gsutil command, not the cp sub-command.
+
+    - You can set or remove metadata fields from already uploaded objects using
+      the gsutil setmeta command. See "gsutil help setmeta".
+
+  More details about specific pieces of metadata are discussed below.
+
+
+<B>CONTENT TYPE</B>
+  The most commonly set metadata is Content-Type (also known as MIME type),
+  which allows browsers to render the object properly. 
+  gsutil sets the Content-Type
+  automatically at upload time, based on each filename extension. For
+  example, uploading files with names ending in .txt will set Content-Type
+  to text/plain. If you're running gsutil on Linux or MacOS and would prefer
+  to have content type set based on naming plus content examination, see the
+  use_magicfile configuration variable in the gsutil/boto configuration file
+  (See also "gsutil help config"). In general, using use_magicfile is more
+  robust and configurable, but is not available on Windows.
+
+  If you specify a -h header when uploading content (like the example gsutil
+  command given in the previous section), it overrides the Content-Type that
+  would have been set based on filename extension or content.  This can be
+  useful if the Content-Type detection algorithm doesn't work as desired
+  for some of your files.
+
+  You can also completely suppress content type detection in gsutil, by
+  specifying an empty string on the Content-Type header:
+
+    gsutil -h 'Content-Type:' cp -r images gs://bucket/images
+
+  In this case, the Google Cloud Storage service will attempt to detect
+  the content type. In general this approach will work better than using
+  filename extension-based content detection in gsutil, because the list of
+  filename extensions is kept more current in the server-side content detection
+  system than in the Python library upon which gsutil content type detection
+  depends. (For example, at the time of writing this, the filename extension
+  ".webp" was recognized by the server-side content detection system, but
+  not by gsutil.)
+
+
+<B>CACHE-CONTROL</B>
+  Another commonly set piece of metadata is Cache-Control, which allows
+  you to control whether and for how long browser and Internet caches are
+  allowed to cache your objects. Cache-Control only applies to objects with
+  a public-read ACL. Non-public data are not cacheable.
+
+  Here's an example of uploading an object set to allow caching:
+
+    gsutil -h "Cache-Control:public,max-age=3600" cp -a public-read -r html gs://bucket/html
+
+  This command would upload all files in the html directory (and subdirectories)
+  and make them publicly readable and cacheable, with cache expiration of
+  one hour.
+
+  Note that if you allow caching, at download time you may see older versions
+  of objects after uploading a newer replacement object. Note also that because
+  objects can be cached at various places on the Internet there is no way to
+  force a cached object to expire globally (unlike the way you can force your
+  browser to refresh its cache).
+
+
+<B>CONTENT-ENCODING</B>
+  You could specify Content-Encoding to indicate that an object is compressed,
+  using a command like:
+
+    gsutil -h "Content-Encoding:gzip" cp *.gz gs://bucket/compressed
+
+  Note that Google Cloud Storage does not compress or decompress objects. If
+  you use this header to specify a compression type or compression algorithm
+  (for example, deflate), Google Cloud Storage preserves the header but does
+  not compress or decompress the object.  Instead, you need to ensure that
+  the files have been compressed using the specified Content-Encoding before
+  using gsutil to upload them.
+
+  For compressible content, using Content-Encoding:gzip saves network and
+  storage costs, and improves content serving performance (since most browsers
+  are able to decompress objects served this way).
+
+  Note also that gsutil provides an easy way to cause content to be compressed
+  and stored with Content-Encoding:gzip: see the -z option in "gsutil help cp".
+
+
+<B>CONTENT-DISPOSITION</B>
+  You can set Content-Disposition on your objects, to specify presentation
+  information about the data being transmitted. Here's an example:
+
+    gsutil -h 'Content-Disposition:attachment; filename=filename.ext' \\
+      cp -r attachments gs://bucket/attachments
+
+  Setting the Content-Disposition allows you to control presentation style
+  of the content, for example determining whether an attachment should be
+  automatically displayed vs should require some form of action from the user to
+  open it.  See http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1
+  for more details about the meaning of Content-Disposition.
+
+
+<B>CUSTOM METADATA</B>
+  You can add your own custom metadata (e.g,. for use by your application)
+  to an object by setting a header that starts with "x-goog-meta", for example:
+
+    gsutil -h x-goog-meta-reviewer:jane cp mycode.java gs://bucket/reviews
+
+  You can add multiple differently named custom metadata fields to each object.
+
+
+<B>SETTABLE FIELDS; FIELD VALUES</B>
+  You can't set some metadata fields, such as ETag and Content-Length. The
+  fields you can set are:
+    - Cache-Control
+    - Content-Disposition
+    - Content-Encoding
+    - Content-Language
+    - Content-MD5
+    - Content-Type
+    - Any field starting with X-GOOG-META- (i.e., custom metadata).
+
+  Header names are case-insensitive.
+
+  X-GOOG-META- fields can have data set to arbitrary Unicode values. All
+  other fields must have ASCII values.
+
+
+<B>VIEWING CURRENTLY SET METADATA</B>
+  You can see what metadata is currently set on an object by using:
+
+    gsutil ls -L gs://the_bucket/the_object
+""")
+
+
+class CommandOptions(HelpProvider):
+  """Additional help about object metadata."""
+
+  help_spec = {
+    # Name of command or auxiliary help info for which this help applies.
+    HELP_NAME : 'metadata',
+    # List of help name aliases.
+    HELP_NAME_ALIASES : ['cache-control', 'caching', 'content type',
+                         'mime type', 'mime', 'type'],
+    # Type of help:
+    HELP_TYPE : HelpType.ADDITIONAL_HELP,
+    # One line summary of this help.
+    HELP_ONE_LINE_SUMMARY : 'Working with object metadata',
+    # The full help text.
+    HELP_TEXT : _detailed_help_text,
+  }

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

@@ -0,0 +1,173 @@
+# 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>BUCKET NAME REQUIREMENTS</B>
+  Google Cloud Storage has a single namespace, so you will not be allowed
+  to create a bucket with a name already in use by another user. You can,
+  however, carve out parts of the bucket name space corresponding to your
+  company's domain name (see "DOMAIN NAMED BUCKETS").
+
+  Bucket names must conform to standard DNS naming conventions. This is
+  because a bucket name can appear in a DNS record as part of a CNAME
+  redirect. In addition to meeting DNS naming requirements, Google Cloud
+  Storage imposes other requirements on bucket naming. At a minimum, your
+  bucket names must meet the following requirements:
+
+    - Bucket names must contain only lowercase letters, numbers, dashes (-), and
+      dots (.).
+
+    - Bucket names must start and end with a number or letter.
+
+    - Bucket names must contain 3 to 63 characters. Names containing dots can
+      contain up to 222 characters, but each dot-separated component can be
+      no longer than 63 characters.
+
+    - Bucket names cannot be represented as an IPv4 address in dotted-decimal
+      notation (for example, 192.168.5.4).
+
+    - Bucket names cannot begin with the "goog" prefix.
+
+    - For DNS compliance, you should not have a period adjacent to another
+      period or dash. For example, ".." or "-." or ".-" are not acceptable.
+
+
+<B>OBJECT NAME REQUIREMENTS</B>
+  Object names can contain any sequence of Unicode characters, of length 1-1024
+  bytes when UTF-8 encoded. Object names must not contain CarriageReturn,
+  CarriageReturnLineFeed, or the XML-disallowed surrogate blocks (xFFFE
+  or xFFFF).
+
+  We highly recommend that you avoid using control characters that are illegal
+  in XML 1.0 in your object names. These characters will cause XML listing
+  issues when you try to list your objects.
+
+
+<B>DOMAIN NAMED BUCKETS</B>
+  You can carve out parts of the Google Cloud Storage bucket name space
+  by creating buckets with domain names (like "example.com").
+
+  Before you can create a bucket name containing one or more '.' characters,
+  the following rules apply:
+  - If the name is a syntactically valid DNS name ending with a
+    currently-recognized top-level domain (such as .com), you will be required
+    to verify domain ownership.
+  - Otherwise you will be disallowed from creating the bucket.
+
+  If your project needs to use a domain-named bucket, you need to have
+  a team member both verify the domain and create the bucket. This is
+  because Google Cloud Storage checks for domain ownership against the
+  user who creates the bucket, so the user who creates the bucket must
+  also be verified as an owner or manager of the domain.
+
+  To verify as the owner or manager of a domain, use the Google Webmaster
+  Tools verification process. The Webmaster Tools verification process
+  provides three methods for verifying an owner or manager of a domain:
+
+  1. Adding a special Meta tag to a site's homepage.
+  2. Uploading a special HTML file to a site.
+  3. Adding a DNS TXT record to a domain's DNS configuration.
+
+  Meta tag verification and HTML file verification are easier to perform and
+  are probably adequate for most situations. DNS TXT record verification is
+  a domain-based verification method that is useful in situations where a
+  site wants to tightly control who can create domain-named buckets. Once
+  a site creates a DNS TXT record to verify ownership of a domain, it takes
+  precedence over meta tag and HTML file verification. For example, you might
+  have two IT staff members who are responsible for managing your site, called
+  "example.com." If they complete the DNS TXT record verification, only they
+  would be able to create buckets called "example.com", "reports.example.com",
+  "downloads.example.com", and other domain-named buckets.
+
+  Site-Based Verification
+
+  If you have administrative control over the HTML files that make up a site,
+  you can use one of the site-based verification methods to verify that you
+  control or own a site. When you do this, Google Cloud Storage lets you
+  create buckets representing the verified site and any sub-sites - provided
+  nobody has used the DNS TXT record method to verify domain ownership of a
+  parent of the site.
+
+  As an example, assume that nobody has used the DNS TXT record method to verify
+  ownership of the following domains: abc.def.example.com, def.example.com,
+  and example.com. In this case, Google Cloud Storage lets you create a bucket
+  named abc.def.example.com if you verify that you own or control any of the
+  following sites:
+
+  http://abc.def.example.com
+  http://def.example.com
+  http://example.com
+
+  Domain-Based Verification
+
+  If you have administrative control over a domain's DNS configuration, you can
+  use the DNS TXT record verification method to verify that you own or control a
+  domain. When you use the domain-based verification method to verify that you
+  own or control a domain, Google Cloud Storage lets you create buckets that
+  represent any subdomain under the verified domain. Furthermore, Google Cloud
+  Storage prevents anybody else from creating buckets under that domain unless
+  you add their name to the list of verified domain owners or they have verified
+  their domain ownership by using the DNS TXT record verification method.
+
+  For example, if you use the DNS TXT record verification method to verify your
+  ownership of the domain example.com, Google Cloud Storage will let you create
+  bucket names that represent any subdomain under the example.com domain, such
+  as abc.def.example.com, example.com/music/jazz, or abc.example.com/music/jazz.
+
+  Using the DNS TXT record method to verify domain ownership supersedes
+  verification by site-based verification methods. For example, if you
+  use the Meta tag method or HTML file method to verify domain ownership
+  of http://example.com, but someone else uses the DNS TXT record method
+  to verify ownership of the example.com domain, Google Cloud Storage will
+  not allow you to create a bucket named example.com. To create the bucket
+  example.com, the domain owner who used the DNS TXT method to verify domain
+  ownership must add you to the list of verified domain owners for example.com.
+
+  The DNS TXT record verification method is particularly useful if you manage
+  a domain for a large organization that has numerous subdomains because it
+  lets you control who can create buckets representing those domain names.
+
+  Note: If you use the DNS TXT record verification method to verify ownership of
+  a domain, you cannot create a CNAME record for that domain. RFC 1034 disallows
+  inclusion of any other resource records if there is a CNAME resource record
+  present. If you want to create a CNAME resource record for a domain, you must
+  use the Meta tag verification method or the HTML file verification method.
+
+
+""")
+
+
+class CommandOptions(HelpProvider):
+  """Additional help about gsutil object and bucket naming."""
+
+  help_spec = {
+    # Name of command or auxiliary help info for which this help applies.
+    HELP_NAME : 'naming',
+    # List of help name aliases.
+    HELP_NAME_ALIASES : ['domain', 'limits', 'name', 'names'],
+    # Type of help:
+    HELP_TYPE : HelpType.ADDITIONAL_HELP,
+    # One line summary of this help.
+    HELP_ONE_LINE_SUMMARY : 'Object and bucket naming',
+    # The full help text.
+    HELP_TEXT : _detailed_help_text,
+  }