# -*- coding: utf-8 -*-
# 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.
"""Additional help about object versioning."""

from __future__ import absolute_import
from __future__ import print_function
from __future__ import division
from __future__ import unicode_literals

from gslib.help_provider import HelpProvider

_DETAILED_HELP_TEXT = ("""
<B>OVERVIEW</B>
  Versioning-enabled buckets maintain noncurrent versions of objects, providing
  a way to un-delete data that you accidentally deleted, or to retrieve older
  versions of your data. Noncurrent objects are ignored by gsutil commands
  unless you indicate it should do otherwise by setting a relevant command flag
  or by including a specific generation number in your command. For example,
  wildcards like ``*`` and ``**`` do not, by themselves, act on noncurrent
  object versions.
  
  When using gsutil cp, you cannot specify a version-specific URL as the
  destination, because writes to Cloud Storage always create a new version.
  Trying to specify a version-specific URL as the destination of ``gsutil cp``
  results in an error. When you specify a noncurrent object as a source in a
  copy command, you always create a new object version and retain the original
  (even when using the command to restore a live version). You can use the 
  ``gsutil mv`` command to simultaneously restore an object version and remove
  the noncurrent copy that was used as the source.

  You can turn versioning on or off for a bucket at any time. Turning
  versioning off leaves existing object versions in place and simply causes
  the bucket to delete the existing live version of the object whenever a new
  version is uploaded.

  Regardless of whether you have enabled versioning on a bucket, every object
  has two associated positive integer fields:

  - the generation, which is updated when a new object replaces an existing
    object with the same name. Note that there is no guarantee that generation
    numbers increase for successive versions, only that each new version has a
    unique generation number.
  - the metageneration, which identifies the metadata generation. It starts
    at 1; is updated every time the metadata (e.g., ACL or Content-Type) for a
    given content generation is updated; and gets reset when the generation
    number changes.

  Of these two integers, only the generation is used when working with versioned
  data. Both generation and metageneration can be used with concurrency control.
  
  To learn more about versioning and concurrency, see the following documentation:
  
  - `Overview of Object Versioning
    <https://cloud.google.com/storage/docs/object-versioning>`_
  - `Guide for using Object Versioning
    <https://cloud.google.com/storage/docs/using-object-versioning>`_
  - The `reference page for the gsutil versioning command
    <https://cloud.google.com/storage/docs/gsutil/commands/versioning>`_
  - `Request preconditions
    <https://cloud.google.com/storage/docs/request-preconditions>`_
""")


class CommandOptions(HelpProvider):
  """Additional help about object versioning."""

  # Help specification. See help_provider.py for documentation.
  help_spec = HelpProvider.HelpSpec(
      help_name='versions',
      help_name_aliases=['concurrency', 'concurrency control'],
      help_type='additional_help',
      help_one_line_summary='Object Versioning and Concurrency Control',
      help_text=_DETAILED_HELP_TEXT,
      subcommand_help_text={},
  )