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

Skip to content

Commit 76fa19d

Browse files
pcostellpcostell
committed
Merge pull request GoogleCloudPlatform#251 from pcostell/readme
Updated README and test instructions, Combine lint and test-lint.
2 parents 8b76450 + 6c80288 commit 76fa19d

File tree

5 files changed

+71
-170
lines changed

5 files changed

+71
-170
lines changed

‎.travis.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ script:
1717
env:
1818
- TOXENV=py27
1919
- TOXENV=lint
20-
- TOXENV=lint-test
2120

2221
after_success:
2322
- tox -e coveralls

‎CONTRIBUTING.md‎

Lines changed: 44 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,79 @@
1-
Contributing
2-
============================
1+
# Contributing
32

43
- **Please sign one of the contributor license agreements below.**
54
- Fork the repo, develop and test your code changes, add docs.
65
- Make sure that your commit messages clearly describe the changes.
76
- Send a pull request.
87

9-
Here are some guidelines for hacking on `ndb`.
8+
## Getting Started
109

11-
Using a Development Checkout
12-
----------------------------
10+
You need to separately download and install the App Engine SDK.
1311

14-
You'll have to create a development environment to hack on `ndb`,
15-
using a Git checkout:
12+
Note: There is no guarantee older versions of the App Engine SDK will
13+
work with the current version of ndb.
1614

17-
- While logged into your GitHub account, navigate to the `ndb` repo on
18-
GitHub.
15+
You can setup your environment by running:
1916

20-
```
21-
https://github.com/pcostell/appengine-ndb-experiment
22-
```
17+
gcloud components update app-engine-python
18+
export GAE=$GCLOUD_PATH/platform/google_appengine
2319

24-
- Fork and clone the `ndb` repository to your GitHub account by
25-
clicking the "Fork" button.
20+
If you haven't downloaded `gcloud` yet, you can find it and instructions
21+
about using it on the [Cloud SDK page][1].
2622

27-
- Clone your fork of `ndb` from your GitHub account to your local
28-
computer, substituting your account username and specifying the destination
29-
as `hack-on-ndb`. For example:
23+
## Code Structure
3024

31-
```
32-
$ cd ~
33-
$ git clone [email protected]:USERNAME/appengine-ndb-experiment.git hack-on-ndb
34-
$ cd hack-on-ndb
35-
# Configure remotes such that you can pull changes from the ndb-git
36-
# repository into your local repository.
37-
$ git remote add upstream https://github.com:pcostell/appengine-ndb-experiment
38-
# fetch and merge changes from upstream into master
39-
$ git fetch upstream
40-
$ git merge upstream/master
41-
```
25+
The code is structured into four subdirectories:
4226

43-
Now your local repo is set up such that you will push changes to your GitHub
44-
repo, from which you can submit a pull request.
27+
- ndb: This is the main code base. Notable submodules are
28+
key.py, model.py, query.py, eventloop.py, tasklets.py, and context.py.
29+
For each module foo.py there's a corresponding foo_test.py which
30+
contains unit tests for that module.
31+
- demo: This is where demo programs live. Check out guestbook.py and
32+
main.py.
33+
- samples: This is where sample code lives.
34+
- tests: This is where additional ndb tests live.
4535

46-
- Create a virtualenv in which to install `ndb`:
36+
The main directory contains some scripts and auxiliary files.
4737

48-
```
49-
$ cd ~/hack-on-ndb
50-
$ virtualenv -ppython2.7 env
51-
```
38+
## Working on ndb
5239

53-
Note that very old versions of `virtualenv` (versions below, say,
54-
1.10 or thereabouts) require you to pass a `--no-site-packages` flag to
55-
get a completely isolated environment.
40+
We accept contributions, so if you see something wrong file an issue or
41+
send us a pull request!
5642

57-
You can choose which Python version you want to use by passing a `-p`
58-
flag to `virtualenv`. For example, `virtualenv -ppython2.7`
59-
chooses the Python 2.7 interpreter to be installed.
43+
Note: Because this library is included in the App Engine python runtime,
44+
we currently cannot accept any changes that break our existing API
45+
(for now). Additionally, there are restrictions on adding any extra
46+
third party dependencies.
6047

61-
From here on in within these instructions, the `~/hack-on-ndb/env`
62-
virtual environment you created above will be referred to as `${VENV}`.
63-
To use the instructions in the steps that follow literally, use the
48+
### Running Tests
6449

65-
```
66-
$ export VENV=~/hack-on-ndb/env
67-
```
50+
Tests can be run using tox.
6851

69-
command.
52+
tox -e py27
7053

71-
- Install `ndb` from the checkout into the virtualenv using
72-
`setup.py develop`. Running `setup.py develop` **must** be done while
73-
the current working directory is the `ndb-git` checkout directory:
54+
Lint can also be run using tox. This will fire off two pylint commands, one
55+
for the main ndb library and one for the tests which have slightly relaxed
56+
requirements.
7457

75-
```
76-
$ cd ~/hack-on-ndb
77-
$ ${VENV}/bin/python setup.py develop
78-
```
58+
tox -e lint
7959

80-
Running Tests
81-
--------------
60+
to run coverage tests, run
8261

83-
- To run all tests for `ndb`, run
84-
85-
```
86-
$ make runtests
87-
```
88-
89-
- In order to install the App Engine SDK for Python, you can either
90-
[download][1] the source as a zip file.
91-
92-
If you already have the [Google Cloud SDK][2] (`gcloud` CLI tool)
93-
installed, then you can install via:
94-
95-
```
96-
$ gcloud components update gae-python
97-
```
98-
99-
If the Google Cloud SDK installed in `${GOOGLE_CLOUD_SDK}`,
100-
then the App Engine SDK can be found in
101-
`${GOOGLE_CLOUD_SDK}/platform/google_appengine` (as of January 2014).
102-
103-
Contributor License Agreements
104-
------------------------------
62+
tox -e cover
10563

64+
## Contributor License Agreements
65+
10666
Before we can accept your pull requests you'll need to sign a Contributor
10767
License Agreement (CLA):
10868

10969
- **If you are an individual writing original source code** and **you own the
110-
intellectual property**, then you'll need to sign an [individual CLA][3].
70+
intellectual property**, then you'll need to sign an [individual CLA][2].
11171
- **If you work for a company that wants to allow you to contribute your work**,
112-
then you'll need to sign a [corporate CLA][4].
72+
then you'll need to sign a [corporate CLA][3].
11373

11474
You can sign these electronically (just scroll to the bottom). After that,
11575
we'll be able to accept your pull requests.
11676

117-
[1]: https://cloud.google.com/appengine/downloads
118-
[2]: https://cloud.google.com/sdk/
119-
[3]: https://developers.google.com/open-source/cla/individual
120-
[4]: https://developers.google.com/open-source/cla/corporate
77+
[1]: https://cloud.google.com/sdk/
78+
[2]: https://developers.google.com/open-source/cla/individual
79+
[3]: https://developers.google.com/open-source/cla/corporate

‎README.md‎

Lines changed: 24 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,36 @@
1-
Introduction
2-
------------
1+
# Google Datastore ndb Client Library
32

4-
(UPDATE: As of SDK 1.6.4, NDB has reached status General Availability.
5-
Mentions of its experimental status in this file should be ignored.)
3+
[![Build Status](https://travis-ci.org/GoogleCloudPlatform/datastore-ndb-python.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/datastore-ndb-python)
4+
[![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)
65

7-
In this project I am developing a new, experimental datastore
8-
API for the Google App Engine Python runtime. I am doing this as a
9-
Google employee but using an open source development style as I
10-
believe this project will benefit from early user feedback.
6+
## Introduction
117

12-
Eventually, when the project is sufficiently mature, the code will
13-
(hopefully) become a standard component of the App Engine Python SDK
14-
and the Python runtime. Until then, however, the way to use this code
15-
is to check it out from the repository and copy it into your
16-
application.
8+
---
9+
**Note:** As of Google App Engine SDK 1.6.4, ndb has reached status General Availability.
10+
11+
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.
1712

18-
Until the code is integrated into the SDK and runtime, I am not going
19-
to worry about backwards compatibility between versions of this
20-
experimental code. You are not required to check out the trunk,
21-
however I do not plan to fix bugs in older branches.
13+
---
2214

23-
See the file LICENSE for the open source licensing conditions (which
24-
are the same as for the App Engine SDK).
15+
ndb is a client library for use with [Google Cloud Datastore][0].
16+
It was designed specifically to be used from within the
17+
[Google App Engine][1] Python runtime.
2518

26-
--Guido van Rossum <[email protected]>
19+
ndb is included in the Python runtime and is available through a
20+
standard Python import.
2721

22+
from google.appengine.ext import ndb
2823

29-
Overview
30-
--------
24+
It is also possible to include ndb directly from this GitHub project.
25+
This will allow application developers to manage their own dependencies. Note
26+
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.
3127

32-
The code is structured into four subdirectories:
28+
## Overview
3329

34-
- ndb: This is the main code base. Notable submodules are
35-
key.py, model.py, query.py, eventloop.py, tasklets.py, and context.py.
36-
For each module foo.py there's a corresponding foo_test.py which
37-
contains unit tests for that module.
30+
Learn how to use the ndb library by visiting the Google Cloud Platform
31+
[documentation][2].
3832

39-
- demo: This is where demo programs live. Check out guestbook.py and
40-
main.py.
4133

42-
- samples: This is where sample code lives.
43-
44-
- tests: This is where additional ndb tests live.
45-
46-
The main directory contains some scripts and auxiliary files.
47-
48-
How To
49-
------
50-
51-
You need to separately download and install the latest version of the
52-
App Engine Python SDK. NOTE: older versions don't work!!!!!!!!!
53-
(If you don't know where to find that you are not ready to play with
54-
this code. :-) Assuming the SDK lives at /usr/local/google_appengine,
55-
you need to add that directory to your $PYTHONPATH environment
56-
variable. You should then be able to run something like this:
57-
58-
>>> import ndb
59-
60-
If this works your setup is correct.
61-
62-
To run the tests, use
63-
64-
make
65-
66-
To run the tests with coverage, install the coverag.py package from
67-
http://nedbatchelder.com/code/coverage/ and then use
68-
69-
make coverage
70-
71-
To run the demo app on localhost:8080, use
72-
73-
make serve
74-
75-
To run an interactive shell with ndb already imported and some sample
76-
classes defined, use
77-
78-
make python
79-
80-
See the Makefile for more details. For Windows users, the "make.cmd"
81-
script has similar functionality.
34+
[0]:https://cloud.google.com/datastore
35+
[1]:https://cloud.google.com/appengine
36+
[2]:https://cloud.google.com/appengine/docs/python/ndb/

‎run_pylint.sh‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,5 @@ TESTS=blobstore_test.py,context_test.py,eventloop_test.py,google_test_imports.py
66

77
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
88

9-
if [[ $* == *--test* ]]; then
10-
echo "Ignoring non-test files: ${NON_TESTS}"
11-
pylint --ignore=${NON_TESTS} --disable=invalid-name,W,I ndb
12-
else
13-
echo "Ignoring test files: ${TESTS}"
14-
pylint --ignore=${TESTS} --disable=W,I ndb
15-
fi
9+
pylint --ignore=${NON_TESTS} --disable=invalid-name,W,I ndb
10+
pylint --ignore=${TESTS} --disable=W,I ndb

‎tox.ini‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,4 @@ commands =
3636
deps =
3737
-ehg+https://bitbucket.org/logilab/pylint@33e334be064c#egg=pylint
3838
logilab-common<=0.63.0 # Hack for pylint upstream
39-
40-
[testenv:lint-test]
41-
basepython =
42-
python2.7
43-
commands =
44-
{[testenv:lint]commands} --test
45-
deps =
46-
{[testenv:lint]deps}
39+

0 commit comments

Comments
 (0)