README.md 3.67 KB
Newer Older
abuddenberg's avatar
abuddenberg committed
1
gcis-py-client
abuddenberg's avatar
abuddenberg committed
2
==============
abuddenberg's avatar
abuddenberg committed
3
4
5
6

gcis-py-client provides a python-based abstraction of the Global Change
Information System Structured Data Server [API](http://data.globalchange.gov).

abuddenberg's avatar
abuddenberg committed
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Installation
------------

### Requirements

These should be available through the package manager of your choice
(Macports, apt, yum, etc.):

* Python 2.7.x (though it might work with previous versions)
* Setuptools 2.0.x
* pip is highly recommended


To install from git with pip:

Brian Duggan's avatar
Brian Duggan committed
22
    pip install git+http://github.com/USGCRP/gcis-py-client
abuddenberg's avatar
abuddenberg committed
23
24
25

To install from tarball:

26
27
    tar -xzvf GcisPyClient-x.y.tar.gz
    cd GcisPyClient-x.y
abuddenberg's avatar
abuddenberg committed
28
29
30
31

    python setup.py test (to run the test suite)
    python setup.py install (to install)

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
Setup
-----

### User Credentials

GcisClient will use the first credentials it finds while searching the following places:

1. Strings passed directly to the GcisClient constructor.
2. Environment variables "GCIS_USER" and "GCIS_KEY" (both are required)
3. Config file at $HOME/etc/Gcis.conf (A sample of this file is included below)
4. Config file at $HOME/.gcis-py-client/Gcis.conf
5. Interactively, with a username and key prompt

Sample Gcis.conf file:

    - url      : http://data-stage.globalchange.gov
      userinfo : me@example.com:298015f752D99E789056EF826A7D97afc38a8bbd6e3e23b3
      key      : M2FiLtG2n2qTyJHIztvHm5zweTYjNkM5ZWEtYjNkMS00LTgS00LTg2N2QtYZDFhzQyNGUxCg==

    - url      : http://data.globalchange.gov
      userinfo : username:pass
      key      : key

abuddenberg's avatar
abuddenberg committed
55
56
57
Usage
-----

abuddenberg's avatar
abuddenberg committed
58
59
60
61
62
63
64
65
66
67
68
    from gcis_clients import GcisClient

    base_url = 'http://data.gcis-dev-front.joss.ucar.edu'
    gcis = GcisClient(base_url, 'andrew.buddenberg@noaa.gov', 'your api key here')

Make sure our credentials work:

    status_code, resp_text = gcis.test_login()
    print status_code, resp_text
    assert 'auth_required' not in resp_text

69
Let's pull a list of all figures in Chapter 2 of the nca3:
abuddenberg's avatar
abuddenberg committed
70

71
72
    for partial_figure in gcis.get_figure_listing('nca3', chapter_id='our-changing-climate'):
        full_figure = gcis.get_figure('nca3', partial_figure.identifier, chapter_id='our-changing-climate')
abuddenberg's avatar
abuddenberg committed
73
74
75
76
77
        print full_figure


Let's work with the infamous temperature figure:

78
    fig2_7 = gcis.get_figure('nca3', 'observed-us-temperature-change')
abuddenberg's avatar
abuddenberg committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

Warning: Images and Chapters are specifically excluded from JSON output.  This is what gets sent to GCIS. So...

    print fig2_7.as_json(indent=4)

...you might want to view the original input:

    print fig2_7.original

Let's see about the images:

    for image in fig2_7.images:
        print image

How about the whole Image?:

    print gcis.get_image('69da6d93-4426-4061-a2a1-7b3d01f2dc1c').as_json(indent=4)
abuddenberg's avatar
abuddenberg committed
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

Want to find the lineage of a publication?

    fig2_1 = gcis.get_figure('nca3', 'ten-indicators-of-a-warming-world')
    print fig2_1.parents

Add a parent to a figure directly...

    cmip3 = gcis.get_dataset('nca3-cmip3-r201205')
    gcis.associate_figure_with_parent('nca3', 'ten-indicators-of-a-warming-world', Parent.from_obj(cmip3))

...or as part of an update

    fig2_1.add_parent(Parent.from_obj(cmip3))
    gcis.update_figure('nca3', 'our-changing-climate', fig2_1)
    
**NOTE:** GcisClient will disassociate and then reassociate Parents as part of an update. Adding a new Parent during an 
update will cause "Parent dissociation failed" messages to appear--these can be safely ignored.
 
**ALSO:** Updates do NOT, presently, remove parents you have not included on the Figure object.

Remove a parent from a figure

    gcis.delete_figure_parent_assoc('nca3', 'ten-indicators-of-a-warming-world', Parent.from_obj(cmip3))
abuddenberg's avatar
abuddenberg committed
120
121
122
123
124
125
126
127
128

Building a source distribution
------------------------------

    $ python setup.py sdist
    
This builds a .tar.gz file of this package.