Thanks to visit codestin.com
Credit goes to github.com

Skip to content
This repository was archived by the owner on Dec 25, 2023. It is now read-only.

Updated README and test instructions #251

Merged
merged 2 commits into from
Nov 5, 2015
Merged

Updated README and test instructions #251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cdb728e
Combine lint and test-lint into a single command.
pcostell Nov 5, 2015
6c80288
Update contributing and readme instructions.
pcostell Nov 5, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ script:
env:
- TOXENV=py27
- TOXENV=lint
- TOXENV=lint-test

after_success:
- tox -e coveralls
129 changes: 44 additions & 85 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 [email protected]: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
93 changes: 24 additions & 69 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <[email protected]>
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/
9 changes: 2 additions & 7 deletions run_pylint.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
9 changes: 1 addition & 8 deletions tox.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}