diff --git a/.travis.yml b/.travis.yml index 0f460959..cc3a3899 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,7 +17,6 @@ script: env: - TOXENV=py27 - TOXENV=lint - - TOXENV=lint-test after_success: - tox -e coveralls diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83593fd5..95d099be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,120 +1,79 @@ -Contributing -============================ +# 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 `ndb`. +## Getting Started -Using a Development Checkout ----------------------------- +You need to separately download and install the App Engine SDK. -You'll have to create a development environment to hack on `ndb`, -using a Git checkout: +Note: There is no guarantee older versions of the App Engine SDK will +work with the current version of ndb. -- While logged into your GitHub account, navigate to the `ndb` repo on -GitHub. +You can setup your environment by running: -``` -https://github.com/pcostell/appengine-ndb-experiment -``` + gcloud components update app-engine-python + export GAE=$GCLOUD_PATH/platform/google_appengine -- Fork and clone the `ndb` repository to your GitHub account by -clicking the "Fork" button. +If you haven't downloaded `gcloud` yet, you can find it and instructions +about using it on the [Cloud SDK page][1]. -- Clone your fork of `ndb` from your GitHub account to your local -computer, substituting your account username and specifying the destination -as `hack-on-ndb`. For example: +## Code Structure -``` -$ cd ~ -$ git clone git@github.com:USERNAME/appengine-ndb-experiment.git hack-on-ndb -$ cd hack-on-ndb -# Configure remotes such that you can pull changes from the ndb-git -# repository into your local repository. -$ git remote add upstream https://github.com:pcostell/appengine-ndb-experiment -# fetch and merge changes from upstream into master -$ git fetch upstream -$ git merge upstream/master -``` +The code is structured into four subdirectories: -Now your local repo is set up such that you will push changes to your GitHub -repo, from which you can submit a pull request. +- ndb: This is the main code base. Notable submodules are + key.py, model.py, query.py, eventloop.py, tasklets.py, and context.py. + For each module foo.py there's a corresponding foo_test.py which + contains unit tests for that module. +- demo: This is where demo programs live. Check out guestbook.py and + main.py. +- samples: This is where sample code lives. +- tests: This is where additional ndb tests live. -- Create a virtualenv in which to install `ndb`: +The main directory contains some scripts and auxiliary files. -``` -$ cd ~/hack-on-ndb -$ virtualenv -ppython2.7 env -``` +## Working on ndb -Note that very old versions of `virtualenv` (versions below, say, - 1.10 or thereabouts) require you to pass a `--no-site-packages` flag to - get a completely isolated environment. +We accept contributions, so if you see something wrong file an issue or +send us a pull request! - You can choose which Python version you want to use by passing a `-p` - flag to `virtualenv`. For example, `virtualenv -ppython2.7` - chooses the Python 2.7 interpreter to be installed. +Note: Because this library is included in the App Engine python runtime, +we currently cannot accept any changes that break our existing API +(for now). Additionally, there are restrictions on adding any extra +third party dependencies. - From here on in within these instructions, the `~/hack-on-ndb/env` - virtual environment you created above will be referred to as `${VENV}`. - To use the instructions in the steps that follow literally, use the +### Running Tests - ``` - $ export VENV=~/hack-on-ndb/env - ``` +Tests can be run using tox. - command. + tox -e py27 - - Install `ndb` from the checkout into the virtualenv using - `setup.py develop`. Running `setup.py develop` **must** be done while - the current working directory is the `ndb-git` checkout directory: +Lint can also be run using tox. This will fire off two pylint commands, one +for the main ndb library and one for the tests which have slightly relaxed +requirements. - ``` - $ cd ~/hack-on-ndb - $ ${VENV}/bin/python setup.py develop - ``` + tox -e lint - Running Tests - -------------- +to run coverage tests, run - - To run all tests for `ndb`, run - - ``` - $ make runtests - ``` - - - In order to install the App Engine SDK for Python, you can either - [download][1] the source as a zip file. - - If you already have the [Google Cloud SDK][2] (`gcloud` CLI tool) - installed, then you can install via: - - ``` - $ gcloud components update gae-python - ``` - - If the Google Cloud SDK installed in `${GOOGLE_CLOUD_SDK}`, - then the App Engine SDK can be found in - `${GOOGLE_CLOUD_SDK}/platform/google_appengine` (as of January 2014). - - Contributor License Agreements - ------------------------------ + tox -e cover +## 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][3]. + intellectual property**, then you'll need to sign an [individual CLA][2]. - **If you work for a company that wants to allow you to contribute your work**, - then you'll need to sign a [corporate CLA][4]. + then you'll need to sign a [corporate CLA][3]. You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests. - [1]: https://cloud.google.com/appengine/downloads - [2]: https://cloud.google.com/sdk/ - [3]: https://developers.google.com/open-source/cla/individual - [4]: https://developers.google.com/open-source/cla/corporate + [1]: https://cloud.google.com/sdk/ + [2]: https://developers.google.com/open-source/cla/individual + [3]: https://developers.google.com/open-source/cla/corporate diff --git a/README.md b/README.md index 5055503b..b93cc92a 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,36 @@ -Introduction ------------- +# Google Datastore ndb Client Library -(UPDATE: As of SDK 1.6.4, NDB has reached status General Availability. -Mentions of its experimental status in this file should be ignored.) +[![Build Status](https://travis-ci.org/GoogleCloudPlatform/datastore-ndb-python.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/datastore-ndb-python) +[![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/datastore-ndb-python/badge.svg?branch=master&service=github)](https://coveralls.io/github/GoogleCloudPlatform/datastore-ndb-python?branch=master) -In this project I am developing a new, experimental datastore -API for the Google App Engine Python runtime. I am doing this as a -Google employee but using an open source development style as I -believe this project will benefit from early user feedback. +## Introduction -Eventually, when the project is sufficiently mature, the code will -(hopefully) become a standard component of the App Engine Python SDK -and the Python runtime. Until then, however, the way to use this code -is to check it out from the repository and copy it into your -application. +--- +**Note:** As of Google App Engine SDK 1.6.4, ndb has reached status General Availability. + +Using ndb from outside of Google App Engine (without the use of Remote API) is currently a work in progress and has not been released. -Until the code is integrated into the SDK and runtime, I am not going -to worry about backwards compatibility between versions of this -experimental code. You are not required to check out the trunk, -however I do not plan to fix bugs in older branches. +--- -See the file LICENSE for the open source licensing conditions (which -are the same as for the App Engine SDK). +ndb is a client library for use with [Google Cloud Datastore][0]. +It was designed specifically to be used from within the +[Google App Engine][1] Python runtime. ---Guido van Rossum +ndb is included in the Python runtime and is available through a +standard Python import. + from google.appengine.ext import ndb -Overview --------- +It is also possible to include ndb directly from this GitHub project. +This will allow application developers to manage their own dependencies. Note +however that ndb depends on the non-public Google Datastore App Engine RPC API. This means that there is no explicit support for older versions of ndb in the App Engine Python runtime. -The code is structured into four subdirectories: +## Overview -- ndb: This is the main code base. Notable submodules are - key.py, model.py, query.py, eventloop.py, tasklets.py, and context.py. - For each module foo.py there's a corresponding foo_test.py which - contains unit tests for that module. +Learn how to use the ndb library by visiting the Google Cloud Platform +[documentation][2]. -- demo: This is where demo programs live. Check out guestbook.py and - main.py. -- samples: This is where sample code lives. - -- tests: This is where additional ndb tests live. - -The main directory contains some scripts and auxiliary files. - -How To ------- - -You need to separately download and install the latest version of the -App Engine Python SDK. NOTE: older versions don't work!!!!!!!!! -(If you don't know where to find that you are not ready to play with -this code. :-) Assuming the SDK lives at /usr/local/google_appengine, -you need to add that directory to your $PYTHONPATH environment -variable. You should then be able to run something like this: - - >>> import ndb - -If this works your setup is correct. - -To run the tests, use - - make - -To run the tests with coverage, install the coverag.py package from -http://nedbatchelder.com/code/coverage/ and then use - - make coverage - -To run the demo app on localhost:8080, use - - make serve - -To run an interactive shell with ndb already imported and some sample -classes defined, use - - make python - -See the Makefile for more details. For Windows users, the "make.cmd" -script has similar functionality. +[0]:https://cloud.google.com/datastore +[1]:https://cloud.google.com/appengine +[2]:https://cloud.google.com/appengine/docs/python/ndb/ diff --git a/run_pylint.sh b/run_pylint.sh index 092c35df..aab85591 100755 --- a/run_pylint.sh +++ b/run_pylint.sh @@ -6,10 +6,5 @@ TESTS=blobstore_test.py,context_test.py,eventloop_test.py,google_test_imports.py NON_TESTS=blobstore.py,context.py,django_middleware.py,eventloop.py,google_imports.py,__init__.py,key.py,metadata.py,model.py,msgprop.py,polymodel.py,prospective_search.py,query.py,stats.py,tasklets.py -if [[ $* == *--test* ]]; then - echo "Ignoring non-test files: ${NON_TESTS}" - pylint --ignore=${NON_TESTS} --disable=invalid-name,W,I ndb -else - echo "Ignoring test files: ${TESTS}" - pylint --ignore=${TESTS} --disable=W,I ndb -fi +pylint --ignore=${NON_TESTS} --disable=invalid-name,W,I ndb +pylint --ignore=${TESTS} --disable=W,I ndb diff --git a/tox.ini b/tox.ini index b22ba12c..5f3c9d56 100644 --- a/tox.ini +++ b/tox.ini @@ -36,11 +36,4 @@ commands = deps = -ehg+https://bitbucket.org/logilab/pylint@33e334be064c#egg=pylint logilab-common<=0.63.0 # Hack for pylint upstream - -[testenv:lint-test] -basepython = - python2.7 -commands = - {[testenv:lint]commands} --test -deps = - {[testenv:lint]deps} + \ No newline at end of file