diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 9d74e61450e4..41a2727dfa41 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -309,6 +309,45 @@ we have customized (e.g. rewriting imports) for our library: - ``67b06019549a4db8168ff4c5171c9d701ac94a15`` - ``f4a53ee64fad5f3d7f29a0341e6a72a060edfcc2`` +Supported Python Versions +------------------------- + +We support: + +- `Python 2.6`_ +- `Python 2.7`_ + +We plan to support: + +- `Python 3.3`_ +- `Python 3.4`_ + +.. _Python 2.6: https://docs.python.org/2.6/ +.. _Python 2.7: https://docs.python.org/2.7/ +.. _Python 3.3: https://docs.python.org/3.3/ +.. _Python 3.4: https://docs.python.org/3.4/ + +Supported versions can be found in our ``tox.ini`` `config`_. + +.. _config: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/tox.ini + +We explicitly decided not to support `Python 2.5`_ due to `decreased usage`_ +and lack of continuous integration `support`_. + +.. _Python 2.5: https://docs.python.org/2.5/ +.. _decreased usage: https://caremad.io/2013/10/a-look-at-pypi-downloads/ +.. _support: http://blog.travis-ci.com/2013-11-18-upcoming-build-environment-updates/ + +We also explicitly decided to support Python 3 beginning with version +3.3. Reasons for this include: + +- Encouraging use of newest versions of Python 3 +- Taking the lead of prominent open-source `projects`_ +- `Unicode literal support`_ which allows for a cleaner codebase that + works in both Python 2 and Python 3 + +.. _projects: http://flask.pocoo.org/docs/0.10/python3/ +.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ Contributor License Agreements ------------------------------ diff --git a/README.rst b/README.rst index cdd306903198..c7a8eafa39a3 100644 --- a/README.rst +++ b/README.rst @@ -1,39 +1,31 @@ Google Cloud Python Client ========================== -Python idiomatic client for Google Cloud Platform services. + Python idiomatic client for `Google Cloud Platform`_ services. -|build| |coverage| |pypi| -------------------------- +.. _Google Cloud Platform: https://cloud.google.com/ + +|pypi| |build| |coverage| - `Homepage`_ +- `API Documentation`_ .. _Homepage: https://googlecloudplatform.github.io/gcloud-python/ +.. _API Documentation: http://googlecloudplatform.github.io/gcloud-python/latest/ This client supports the following Google Cloud Platform services: - `Google Cloud Datastore`_ - `Google Cloud Storage`_ -.. _Google Cloud Datastore: https://cloud.google.com/products/cloud-datastore/ -.. _Google Cloud Storage: https://cloud.google.com/products/cloud-storage/ +.. _Google Cloud Datastore: https://cloud.google.com/datastore/ +.. _Google Cloud Storage: https://cloud.google.com/storage/ If you need support for other Google APIs, check out the `Google APIs Python Client library`_. .. _Google APIs Python Client library: https://github.com/google/google-api-python-client -Versioning ----------- - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -It is currently in major version zero (``0.y.z``), which means that anything -may change at any time and the public API should not be considered -stable. - Quickstart ---------- @@ -41,6 +33,13 @@ Quickstart $ pip install gcloud +Example Applications +-------------------- + +- `gcloud-python-expenses-demo`_ - A sample expenses demo using Cloud Datastore and Cloud Storage + +.. _gcloud-python-expenses-demo: https://github.com/GoogleCloudPlatform/gcloud-python-expenses-demo + Google Cloud Datastore ---------------------- @@ -50,25 +49,33 @@ your users and supports ACID transactions, high availability of reads and writes, strong consistency for reads and ancestor queries, and eventual consistency for all other queries. -.. _Cloud Datastore: https://developers.google.com/datastore/ +.. _Cloud Datastore: https://cloud.google.com/datastore/docs See the `Google Cloud Datastore docs`_ for more details on how to activate Cloud Datastore for your project. -.. _Google Cloud Datastore docs: https://developers.google.com/datastore/docs/activate +.. _Google Cloud Datastore docs: https://cloud.google.com/datastore/docs/activate See the ``gcloud-python`` API `datastore documentation`_ to learn how to interact with the Cloud Datastore using this Client Library. -.. _datastore documentation: https://googlecloudplatform.github.io/gcloud-python/datastore-api.html +.. _datastore documentation: https://googlecloudplatform.github.io/gcloud-python/latest/datastore-api.html .. code:: python from gcloud import datastore datastore.set_defaults() - # Then do other things... - query = datastore.Query(kind='EntityKind') + # Create, populate and persist an entity entity = datastore.Entity(key=datastore.Key('EntityKind')) + entity.update({ + 'foo': u'bar', + 'baz': 1337, + 'qux': False, + }) + # Then query for entities + query = datastore.Query(kind='EntityKind') + for result in query.fetch(): + print result Google Cloud Storage -------------------- @@ -77,23 +84,23 @@ Google `Cloud Storage`_ allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download. -.. _Cloud Storage: https://developers.google.com/storage/ +.. _Cloud Storage: https://cloud.google.com/storage/docs You need to create a Google Cloud Storage bucket to use this client library. Follow the steps on the `Google Cloud Storage docs`_ to learn how to create a bucket. -.. _Google Cloud Storage docs: https://developers.google.com/storage/docs/cloud-console#_creatingbuckets +.. _Google Cloud Storage docs: https://cloud.google.com/storage/docs/cloud-console#_creatingbuckets See the ``gcloud-python`` API `storage documentation`_ to learn how to connect to Cloud Storage using this Client Library. -.. _storage documentation: https://googlecloudplatform.github.io/gcloud-python/storage-api.html +.. _storage documentation: https://googlecloudplatform.github.io/gcloud-python/latest/storage-api.html .. code:: python - import gcloud.storage - bucket = gcloud.storage.get_bucket('bucket-id-here', 'project-id') + from gcloud import storage + bucket = storage.get_bucket('bucket-id-here', 'project-id') # Then do other things... blob = bucket.get_blob('/remote/path/to/file.txt') print blob.download_as_string() @@ -109,45 +116,29 @@ See `CONTRIBUTING`_ for more information on how to get started. .. _CONTRIBUTING: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/CONTRIBUTING.rst -Supported Python Versions +Python Versions ------------------------- -We support: - -- `Python 2.6`_ -- `Python 2.7`_ - -We plan to support: - -- `Python 3.3`_ -- `Python 3.4`_ +We support `Python 2.6`_ and `Python 2.7`_ and plan to support `Python 3.3`_ and +`Python 3.4`_. For more information, see `Supported Python Versions`_ in +``CONTRIBUTING``. .. _Python 2.6: https://docs.python.org/2.6/ .. _Python 2.7: https://docs.python.org/2.7/ .. _Python 3.3: https://docs.python.org/3.3/ .. _Python 3.4: https://docs.python.org/3.4/ +.. _Supported Python Versions: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/CONTRIBUTING.rst#supported-python-versions -Supported versions can be found in our ``tox.ini`` `config`_. - -.. _config: https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/tox.ini - -We explicitly decided not to support `Python 2.5`_ due to `decreased usage`_ -and lack of continuous integration `support`_. - -.. _Python 2.5: https://docs.python.org/2.5/ -.. _decreased usage: https://caremad.io/2013/10/a-look-at-pypi-downloads/ -.. _support: http://blog.travis-ci.com/2013-11-18-upcoming-build-environment-updates/ +Versioning +---------- -We also explicitly decided to support Python 3 beginning with version -3.3. Reasons for this include: +This library follows `Semantic Versioning`_. -- Encouraging use of newest versions of Python 3 -- Taking the lead of prominent open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 +.. _Semantic Versioning: http://semver.org/ -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ +It is currently in major version zero (``0.y.z``), which means that anything +may change at any time and the public API should not be considered +stable. License -------