gcloud 0.0.7 → 0.1.0

data/packages/gsutil/boto/docs/source/conf.py

@@ -1,32 +0,0 @@
-# -*- coding: utf-8 -*-
-
-import os
-import boto
-
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo']
-autoclass_content="both"
-templates_path = ['_templates']
-source_suffix = '.rst'
-master_doc = 'index'
-project = u'boto'
-copyright = u'2009,2010, Mitch Garnaat'
-version = boto.__version__
-exclude_trees = []
-pygments_style = 'sphinx'
-html_theme = 'boto_theme'
-html_theme_path = ["."]
-html_static_path = ['_static']
-htmlhelp_basename = 'botodoc'
-latex_documents = [
-  ('index', 'boto.tex', u'boto Documentation',
-   u'Mitch Garnaat', 'manual'),
-]
-intersphinx_mapping = {'http://docs.python.org/': None}
-
-try:
-    release = os.environ.get('SVN_REVISION', 'HEAD')
-    print release
-except Exception, e:
-    print e
-
-html_title = "boto v%s" % version

data/packages/gsutil/boto/docs/source/contributing.rst

@@ -1,204 +0,0 @@
-====================
-Contributing to Boto
-====================
-
-
-Setting Up a Development Environment
-====================================
-
-While not strictly required, it is highly recommended to do development
-in a virtualenv.  You can install virtualenv using pip::
-
-    $ pip install virtualenv
-
-Once the package is installed, you'll have a ``virtualenv`` command you can
-use to create a virtual environment::
-
-    $ virtualenv venv
-
-You can then activate the virtualenv::
-
-    $ . venv/bin/activate
-
-.. note::
-
-  You may also want to check out virtualenvwrapper_, which is a set of
-  extensions to virtualenv that makes it easy to manage multiple virtual
-  environments.
-
-A requirements.txt is included with boto which contains all the additional
-packages needed for boto development.  You can install these packages by
-running::
-
-    $ pip install -r requirements.txt
-
-
-Running the Tests
-=================
-
-All of the tests for boto are under the ``tests/`` directory. The tests for
-boto have been split into two main categories, unit and integration tests:
-
-* **unit** - These are tests that do not talk to any AWS services.  Anyone
-  should be able to run these tests without have any credentials
-  configured.  These are the types of tests that could be run in something
-  like a public CI server.  These tests tend to be fast.
-
-* **integration** - These are tests that will talk to AWS services, and
-  will typically require a boto config file with valid credentials.
-  Due to the nature of these tests, they tend to take a while to run.
-  Also keep in mind anyone who runs these tests will incur any usage
-  fees associated with the various AWS services.
-
-To run all the unit tests, cd to the ``tests/`` directory and run::
-
-    $ python test.py unit
-
-You should see output like this::
-
-    $ python test.py unit
-    ................................
-    ----------------------------------------------------------------------
-    Ran 32 tests in 0.075s
-
-    OK
-
-To run the integration tests, run::
-
-    $ python test.py integration
-
-Note that running the integration tests may take a while.
-
-Various integration tests have been tagged with service names to allow
-you to easily run tests by service type.  For example, to run the ec2
-integration tests you can run::
-
-    $ python test.py -t ec2
-
-You can specify the ``-t`` argument multiple times.  For example, to
-run the s3 and ec2 tests you can run::
-
-    $ python test.py -t ec2 -t s3
-
-.. warning::
-
-  In the examples above no top level directory was specified.  By default,
-  nose will assume the current working directory, so the above command is
-  equivalent to::
-
-      $ python test.py -t ec2 -t s3 .
-
-  Be sure that you are in the ``tests/`` directory when running the tests,
-  or explicitly specify the top level directory.  For example, if you in the
-  root directory of the boto repo, you could run the ec2 and s3 tests by
-  running::
-
-      $ python tests/test.py -t ec2 -t s3 tests/
-
-
-You can use nose's collect plugin to see what tests are associated with each
-service tag::
-
-    $ python tests.py -t s3 -t ec2 --with-id --collect -v
-
-
-Testing Details
----------------
-
-The ``tests/test.py`` script is a lightweight wrapper around nose_. In
-general, you should be able to run ``nosetests`` directly instead of
-``tests/test.py``.  The ``tests/unit`` and ``tests/integration`` args
-in the commands above were referring to directories.  The command line
-arguments are forwarded to nose when you use ``tests/test.py``.  For example,
-you can run::
-
-    $ python tests/test.py -x -vv tests/unit/cloudformation
-
-And the ``-x -vv tests/unit/cloudformation`` are forwarded to nose.  See
-the nose_ docs for the supported command line options, or run
-``nosetests --help``.
-
-The only thing that ``tests/test.py`` does before invoking nose is to
-inject an argument that specifies that any testcase tagged with "notdefault"
-should not be run.  A testcase may be tagged with "notdefault" if the test
-author does not want everyone to run the tests.  In general, there shouldn't be
-many of these tests, but some reasons a test may be tagged "notdefault"
-include:
-
-* An integration test that requires specific credentials.
-* An interactive test (the S3 MFA tests require you to type in the S/N and
-  code).
-
-Tagging is done using nose's tagging_ plugin.  To summarize, you can tag a
-specific testcase by setting an attribute on the object.  Nose provides
-an ``attr`` decorator for convenience::
-
-    from nose.plugins.attrib import attr
-
-    @attr('notdefault')
-    def test_s3_mfs():
-        pass
-
-You can then run these tests be specifying::
-
-    nosetests -a 'notdefault'
-
-Or you can exclude any tests tagged with 'notdefault' by running::
-
-    nosetests -a '!notdefault'
-
-Conceptually, ``tests/test.py`` is injecting the "-a !notdefault" arg
-into nosetests.
-
-
-Testing Supported Python Versions
-==================================
-
-Boto supports python 2.6 and 2.7. An easy way to verify functionality
-across multiple python versions is to use tox_. A tox.ini file is included
-with boto.  You can run tox with no args and it will automatically test
-all supported python versions::
-
-    $ tox
-    GLOB sdist-make: boto/setup.py
-    py26 sdist-reinst: boto/.tox/dist/boto-2.4.1.zip
-    py26 runtests: commands[0]
-    ................................
-    ----------------------------------------------------------------------
-    Ran 32 tests in 0.089s
-
-    OK
-    py27 sdist-reinst: boto/.tox/dist/boto-2.4.1.zip
-    py27 runtests: commands[0]
-    ................................
-    ----------------------------------------------------------------------
-    Ran 32 tests in 0.087s
-
-    OK
-    ____ summary ____
-      py26: commands succeeded
-      py27: commands succeeded
-      congratulations :)
-
-
-Writing Documentation
-=====================
-
-The boto docs use sphinx_ to generate documentation.  All of the docs are
-located in the ``docs/`` directory.  To generate the html documentation, cd
-into the docs directory and run ``make html``::
-
-    $ cd docs
-    $ make html
-
-The generated documentation will be in the ``docs/build/html`` directory.
-The source for the documentation is located in ``docs/source`` directory,
-and uses `restructured text`_ for the markup language.
-
-
-.. _nose: http://readthedocs.org/docs/nose/en/latest/
-.. _tagging: http://nose.readthedocs.org/en/latest/plugins/attrib.html
-.. _tox: http://tox.testrun.org/latest/
-.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/
-.. _sphinx: http://sphinx.pocoo.org/
-.. _restructured text: http://sphinx.pocoo.org/rest.html

data/packages/gsutil/boto/docs/source/documentation.rst

@@ -1,59 +0,0 @@
-.. _documentation:
-
-=======================
-About the Documentation
-=======================
-
-boto's documentation uses the Sphinx__ documentation system, which in turn is
-based on docutils__. The basic idea is that lightly-formatted plain-text
-documentation is transformed into HTML, PDF, and any other output format.
-
-__ http://sphinx.pocoo.org/
-__ http://docutils.sf.net/
-
-To actually build the documentation locally, you'll currently need to install
-Sphinx -- ``easy_install Sphinx`` should do the trick.
-
-Then, building the html is easy; just ``make html`` from the ``docs`` directory.
-
-To get started contributing, you'll want to read the `ReStructuredText
-Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
-that's used to manage metadata, indexing, and cross-references.
-
-__ http://sphinx.pocoo.org/rest.html
-__ http://sphinx.pocoo.org/markup/
-
-The main thing to keep in mind as you write and edit docs is that the more
-semantic markup you can add the better. So::
-
-    Import ``boto`` to your script...
-
-Isn't nearly as helpful as::
-
-    Add :mod:`boto` to your script...
-
-This is because Sphinx will generate a proper link for the latter, which greatly
-helps readers. There's basically no limit to the amount of useful markup you can
-add.
-
-
-The fabfile
------------
-
-There is a Fabric__ file that can be used to build and deploy the documentation
-to a webserver that you ssh access to.
-
-__ http://fabfile.org
-
-To build and deploy::
-
-    cd docs/
-    fab deploy:remote_path='/var/www/folder/whatever' --hosts=user@host
-
-This will get the latest code from subversion, add the revision number to the 
-docs conf.py file, call ``make html`` to build the documentation, then it will
-tarball it up and scp up to the host you specified and untarball it in the 
-folder you specified creating a symbolic link from the untarballed versioned
-folder to ``{remote_path}/boto-docs``.
-
-

data/packages/gsutil/boto/docs/source/dynamodb_tut.rst

@@ -1,339 +0,0 @@
-.. dynamodb_tut:
-
-============================================
-An Introduction to boto's DynamoDB interface
-============================================
-
-This tutorial focuses on the boto interface to AWS' DynamoDB_. This tutorial
-assumes that you have boto already downloaded and installed.
-
-.. _DynamoDB: http://aws.amazon.com/dynamodb/
-
-
-Creating a Connection
----------------------
-
-The first step in accessing DynamoDB is to create a connection to the service.
-To do so, the most straight forward way is the following::
-
-    >>> import boto
-    >>> conn = boto.connect_dynamodb(
-            aws_access_key_id='<YOUR_AWS_KEY_ID>',
-            aws_secret_access_key='<YOUR_AWS_SECRET_KEY>')
-    >>> conn
-    <boto.dynamodb.layer2.Layer2 object at 0x3fb3090>
-
-Bear in mind that if you have your credentials in boto config in your home
-directory, the two keyword arguments in the call above are not needed. More
-details on configuration can be found in :doc:`boto_config_tut`.
-
-The :py:func:`boto.connect_dynamodb` functions returns a
-:py:class:`boto.dynamodb.layer2.Layer2` instance, which is a high-level API
-for working with DynamoDB. Layer2 is a set of abstractions that sit atop
-the lower level :py:class:`boto.dynamodb.layer1.Layer1` API, which closely
-mirrors the Amazon DynamoDB API. For the purpose of this tutorial, we'll
-just be covering Layer2.
-
-
-Listing Tables
---------------
-
-Now that we have a DynamoDB connection object, we can then query for a list of
-existing tables in that region::
-
-    >>> conn.list_tables()
-    ['test-table', 'another-table']
-
-
-Creating Tables
----------------
-
-DynamoDB tables are created with the
-:py:meth:`Layer2.create_table <boto.dynamodb.layer2.Layer2.create_table>`
-method. While DynamoDB's items (a rough equivalent to a relational DB's row)
-don't have a fixed schema, you do need to create a schema for the table's
-hash key element, and the optional range key element. This is explained in
-greater detail in DynamoDB's `Data Model`_ documentation.
-
-We'll start by defining a schema that has a hash key and a range key that
-are both keys::
-
-    >>> message_table_schema = conn.create_schema(
-            hash_key_name='forum_name',
-            hash_key_proto_value=str,
-            range_key_name='subject',
-            range_key_proto_value=str
-        )
-
-The next few things to determine are table name and read/write throughput. We'll
-defer explaining throughput to the DynamoDB's `Provisioned Throughput`_ docs.
-
-We're now ready to create the table::
-
-    >>> table = conn.create_table(
-            name='messages',
-            schema=message_table_schema,
-            read_units=10,
-            write_units=10
-        )
-    >>> table
-    Table(messages)
-
-This returns a :py:class:`boto.dynamodb.table.Table` instance, which provides
-simple ways to create (put), update, and delete items.
-
-
-Getting a Table
----------------
-
-To retrieve an existing table, use
-:py:meth:`Layer2.get_table <boto.dynamodb.layer2.Layer2.get_table>`::
-
-    >>> conn.list_tables()
-    ['test-table', 'another-table', 'messages']
-    >>> table = conn.get_table('messages')
-    >>> table
-    Table(messages)
-
-:py:meth:`Layer2.get_table <boto.dynamodb.layer2.Layer2.get_table>`, like
-:py:meth:`Layer2.create_table <boto.dynamodb.layer2.Layer2.create_table>`,
-returns a :py:class:`boto.dynamodb.table.Table` instance.
-
-Keep in mind that :py:meth:`Layer2.get_table <boto.dynamodb.layer2.Layer2.get_table>`
-will make an API call to retrieve various attributes of the table including the
-creation time, the read and write capacity, and the table schema.  If you
-already know the schema, you can save an API call and create a
-:py:class:`boto.dynamodb.table.Table` object without making any calls to
-Amazon DynamoDB::
-
-    >>> table = conn.table_from_schema(
-        name='messages',
-        schema=message_table_schema)
-
-If you do this, the following fields will have ``None`` values:
-
-  * create_time
-  * status
-  * read_units
-  * write_units
-
-In addition, the ``item_count`` and ``size_bytes`` will be 0.
-If you create a table object directly from a schema object and
-decide later that you need to retrieve any of these additional
-attributes, you can use the
-:py:meth:`Table.refresh <boto.dynamodb.table.Table.refresh>` method::
-
-    >>> from boto.dynamodb.schema import Schema
-    >>> table = conn.table_from_schema(
-            name='messages',
-            schema=Schema.create(hash_key=('forum_name', 'S'),
-                                 range_key=('subject', 'S')))
-    >>> print table.write_units
-    None
-    >>> # Now we decide we need to know the write_units:
-    >>> table.refresh()
-    >>> print table.write_units
-    10
-
-
-The recommended best practice is to retrieve a table object once and
-use that object for the duration of your application. So, for example,
-instead of this::
-
-    class Application(object):
-        def __init__(self, layer2):
-            self._layer2 = layer2
-
-        def retrieve_item(self, table_name, key):
-            return self._layer2.get_table(table_name).get_item(key)
-
-You can do something like this instead::
-
-    class Application(object):
-        def __init__(self, layer2):
-            self._layer2 = layer2
-            self._tables_by_name = {}
-
-        def retrieve_item(self, table_name, key):
-            table = self._tables_by_name.get(table_name)
-            if table is None:
-                table = self._layer2.get_table(table_name)
-                self._tables_by_name[table_name] = table
-            return table.get_item(key)
-
-
-Describing Tables
------------------
-
-To get a complete description of a table, use
-:py:meth:`Layer2.describe_table <boto.dynamodb.layer2.Layer2.describe_table>`::
-
-    >>> conn.list_tables()
-    ['test-table', 'another-table', 'messages']
-    >>> conn.describe_table('messages')
-    {
-        'Table': {
-            'CreationDateTime': 1327117581.624,
-            'ItemCount': 0,
-            'KeySchema': {
-                'HashKeyElement': {
-                    'AttributeName': 'forum_name',
-                    'AttributeType': 'S'
-                },
-                'RangeKeyElement': {
-                    'AttributeName': 'subject',
-                    'AttributeType': 'S'
-                }
-            },
-            'ProvisionedThroughput': {
-                'ReadCapacityUnits': 10,
-                'WriteCapacityUnits': 10
-            },
-            'TableName': 'messages',
-            'TableSizeBytes': 0,
-            'TableStatus': 'ACTIVE'
-        }
-    }
-
-
-Adding Items
-------------
-
-Continuing on with our previously created ``messages`` table, adding an::
-
-    >>> table = conn.get_table('messages')
-    >>> item_data = {
-            'Body': 'http://url_to_lolcat.gif',
-            'SentBy': 'User A',
-            'ReceivedTime': '12/9/2011 11:36:03 PM',
-        }
-    >>> item = table.new_item(
-            # Our hash key is 'forum'
-            hash_key='LOLCat Forum',
-            # Our range key is 'subject'
-            range_key='Check this out!',
-            # This has the
-            attrs=item_data
-        )
-
-The
-:py:meth:`Table.new_item <boto.dynamodb.table.Table.new_item>` method creates
-a new :py:class:`boto.dynamodb.item.Item` instance with your specified
-hash key, range key, and attributes already set.
-:py:class:`Item <boto.dynamodb.item.Item>` is a :py:class:`dict` sub-class,
-meaning you can edit your data as such::
-
-    item['a_new_key'] = 'testing'
-    del item['a_new_key']
-
-After you are happy with the contents of the item, use
-:py:meth:`Item.put <boto.dynamodb.item.Item.put>` to commit it to DynamoDB::
-
-    >>> item.put()
-
-
-Retrieving Items
-----------------
-
-Now, let's check if it got added correctly. Since DynamoDB works under an
-'eventual consistency' mode, we need to specify that we wish a consistent read,
-as follows::
-
-    >>> table = conn.get_table('messages')
-    >>> item = table.get_item(
-            # Your hash key was 'forum_name'
-            hash_key='LOLCat Forum',
-            # Your range key was 'subject'
-            range_key='Check this out!'
-        )
-    >>> item
-    {
-        # Note that this was your hash key attribute (forum_name)
-        'forum_name': 'LOLCat Forum',
-        # This is your range key attribute (subject)
-        'subject': 'Check this out!'
-        'Body': 'http://url_to_lolcat.gif',
-        'ReceivedTime': '12/9/2011 11:36:03 PM',
-        'SentBy': 'User A',
-    }
-
-
-Updating Items
---------------
-
-To update an item's attributes, simply retrieve it, modify the value, then
-:py:meth:`Item.put <boto.dynamodb.item.Item.put>` it again::
-
-    >>> table = conn.get_table('messages')
-    >>> item = table.get_item(
-            hash_key='LOLCat Forum',
-            range_key='Check this out!'
-        )
-    >>> item['SentBy'] = 'User B'
-    >>> item.put()
-
-Working with Decimals
----------------------
-
-To avoid the loss of precision, you can stipulate that the
-``decimal.Decimal`` type be used for numeric values::
-
-    >>> import decimal
-    >>> conn.use_decimals()
-    >>> table = conn.get_table('messages')
-    >>> item = table.new_item(
-            hash_key='LOLCat Forum',
-            range_key='Check this out!'
-        )
-    >>> item['decimal_type'] = decimal.Decimal('1.12345678912345')
-    >>> item.put()
-    >>> print table.get_item('LOLCat Forum', 'Check this out!')
-    {u'forum_name': 'LOLCat Forum', u'decimal_type': Decimal('1.12345678912345'),
-     u'subject': 'Check this out!'}
-
-You can enable the usage of ``decimal.Decimal`` by using either the ``use_decimals``
-method, or by passing in the
-:py:class:`Dynamizer <boto.dynamodb.types.Dynamizer>` class for
-the ``dynamizer`` param::
-
-    >>> from boto.dynamodb.types import Dynamizer
-    >>> conn = boto.connect_dynamodb(dynamizer=Dynamizer)
-
-This mechanism can also be used if you want to customize the encoding/decoding
-process of DynamoDB types.
-
-
-Deleting Items
---------------
-
-To delete items, use the
-:py:meth:`Item.delete <boto.dynamodb.item.Item.delete>` method::
-
-    >>> table = conn.get_table('messages')
-    >>> item = table.get_item(
-            hash_key='LOLCat Forum',
-            range_key='Check this out!'
-        )
-    >>> item.delete()
-
-
-Deleting Tables
----------------
-
-.. WARNING::
-  Deleting a table will also **permanently** delete all of its contents without prompt. Use carefully.
-
-There are two easy ways to delete a table. Through your top-level
-:py:class:`Layer2 <boto.dynamodb.layer2.Layer2>` object::
-
-    >>> conn.delete_table(table)
-
-Or by getting the table, then using
-:py:meth:`Table.delete <boto.dynamodb.table.Table.delete>`::
-
-    >>> table = conn.get_table('messages')
-    >>> table.delete()
-
-
-.. _Data Model: http://docs.amazonwebservices.com/amazondynamodb/latest/developerguide/DataModel.html
-.. _Provisioned Throughput: http://docs.amazonwebservices.com/amazondynamodb/latest/developerguide/ProvisionedThroughputIntro.html