diff --git a/CONTRIB.rst b/CONTRIB.rst deleted file mode 100644 index a7e3b09844a5..000000000000 --- a/CONTRIB.rst +++ /dev/null @@ -1,25 +0,0 @@ -How to contribute -================= - -Want to help out? -That's awesome. -The library is open source -and `lives on GitHub `_. -Open an issue -or fork the library and submit a pull request. - -Keep in mind that before we can accept any pull requests -we have to jump through a couple of legal hurdles, -primarily a Contributor License Agreement (CLA): - -- **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 - `_. -- **If you work for a company that wants to allow you to contribute your work**, - then you'll need to sign a `corporate CLA - `_. - -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 be able to accept your pull requests. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 53e59ec84d22..1988f04feb2b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,6 +1,11 @@ -Hacking on ``gcloud-python`` +Contributing ============================ +#. **Please sign one of the contributor license agreements below.** +#. Fork the repo, develop and test your code changes, add docs. +#. Make sure that your commit messages clearly describe the changes. +#. Send a pull request. + Here are some guidelines for hacking on gcloud-python. Using a Development Checkout @@ -59,6 +64,22 @@ repo, from which you can submit a pull request. $ cd ~/hack-on-gcloud $ $VENV/bin/python setup.py develop +I'm getting weird errors... Can you help? +----------------------------------------- + +Chances are you have some dependency problems... +If you're on Ubuntu, +try installing the pre-compiled packages:: + + $ sudo apt-get install python-crypto python-openssl libffi-dev + +or try installing the development packages +(that have the header files included) +and then ``pip install`` the dependencies again:: + + $ sudo apt-get install python-dev libssl-dev libffi-dev + $ pip install gcloud + Adding Features --------------- @@ -155,10 +176,12 @@ can build the docs via:: $ tox -e docs -Change Log ----------- +Contributor License Agreements +------------------------------ + +Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA): + +- **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need to sign an `individual CLA `__. +- **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a `corporate CLA `__. -- Feature additions and bugfixes must be added to the ``CHANGES.txt`` - file in the prevailing style. Changelog entries should be long and - descriptive, not cryptic. Other developers should be able to know - what your changelog entry means. +You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests. \ No newline at end of file diff --git a/LICENSE b/LICENSE index e06d2081865a..43562193229a 100644 --- a/LICENSE +++ b/LICENSE @@ -186,7 +186,7 @@ Apache License same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright {yyyy} {name of copyright owner} + Copyright 2014 Google Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.rst b/README.rst index e8f9e16b27af..c09c37a0a643 100644 --- a/README.rst +++ b/README.rst @@ -1,85 +1,101 @@ Google Cloud Python Client ========================== -The goal of this project is to make it really simple and Pythonic -to use Google Cloud Platform services. + Python idiomatic client for Google Cloud Platform services. ------------------- |build| |coverage| ------------------ +- `Homepage `__ + +This client supports the following Google Cloud Platform services: + +- `Google Cloud + Datastore `__ +- `Google Cloud + Storage `__ + +If you need support for other Google APIs, check out the `Google APIs +Python Client +library `__. + Quickstart ---------- -The library is ``pip``-installable:: +:: - $ pip install gcloud - $ python -m gcloud.storage.demo # Runs the storage demo! + $ pip install gcloud -Documentation -------------- +Google Cloud Datastore +---------------------- -- `gcloud docs (browse all services, quick-starts, walk-throughs) `_ -- `gcloud.datastore API docs `_ -- `gcloud.storage API docs `_ -- gcloud.bigquery API docs (*coming soon)* -- gcloud.compute API docs *(coming soon)* -- gcloud.dns API docs *(coming soon)* -- gcloud.sql API docs *(coming soon)* +`Google Cloud Datastore `__ is +a fully managed, schemaless database for storing non-relational data. +Cloud Datastore automatically scales with 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. -I'm getting weird errors... Can you help? ------------------------------------------ +See the `Google Cloud Datastore +docs `__ for more +details on how to activate Cloud Datastore for your project. -Chances are you have some dependency problems... -If you're on Ubuntu, -try installing the pre-compiled packages:: +See `the gcloud-python API +documentation `__ +to learn how to interact with the Cloud Datastore using this Client +Library. - $ sudo apt-get install python-crypto python-openssl libffi-dev +.. code:: python -or try installing the development packages -(that have the header files included) -and then ``pip install`` the dependencies again:: + from gcloud import datastore + dataset = datastore.get_dataset('dataset-id-here', + 'long-email@googleapis.com', + '/path/to/private.key') + # Then do other things... + query = dataset.query().kind('EntityKind') + entity = dataset.entity('EntityKind') - $ sudo apt-get install python-dev libssl-dev libffi-dev - $ pip install gcloud +Google Cloud Storage +-------------------- -How do I build the docs? ------------------------- +`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. -Make sure you have ``sphinx`` installed and:: +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. - $ git clone git://github.com/GoogleCloudPlatform/gcloud-python.git - $ pip install sphinx - $ cd gcloud-python/docs - $ make html +See `the gcloud-python API +documentation `__ +to learn how to connect to the Cloud Storage using this Client Library. -How do I run the tests? ------------------------ +.. code:: python -Make sure you have ``nose`` installed and:: + import gcloud.storage + bucket = gcloud.storage.get_bucket('bucket-id-here', + 'long-email@googleapis.com', + '/path/to/private.key') + # Then do other things... + key = bucket.get_key('/remote/path/to/file.txt') + print key.get_contents_as_string() + key.set_contents_from_string('New contents!') + bucket.upload_file('/remote/path/storage.txt', '/local/path.txt') - $ git clone git://github.com/GoogleCloudPlatform/gcloud-python.git - $ pip install unittest2 nose - $ cd gcloud-python - $ nosetests +Contributing +------------ -How can I contribute? ---------------------- +Contributions to this library are always welcome and highly encouraged. -Before we can accept any pull requests -we have to jump through a couple of legal hurdles, -primarily a Contributor License Agreement (CLA): +See `CONTRIBUTING `__ for more information on how to +get started. -- **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 - `_. -- **If you work for a company that wants to allow you to contribute your work**, - then you'll need to sign a `corporate CLA - `_. +License +------- -You can sign these electronically (just scroll to the bottom). -After that, we'll be able to accept your pull requests. +Apache 2.0 - See `LICENSE `__ for more information. .. |build| image:: https://travis-ci.org/GoogleCloudPlatform/gcloud-python.svg?branch=master :target: https://travis-ci.org/GoogleCloudPlatform/gcloud-python