Merge pull request #2 from codersquid/master

readme, install, and test improvements

Author: codersquid

.gitignore

@@ -1,3 +1,5 @@
 .vagrant
 .DS_Store
 *pyc
+venv
+.cache

dvn_client/src/config.py

@@ -2,3 +2,8 @@
 DEFAULT_PASSWORD = "FIXME"
 DEFAULT_HOST = "dvn-4.hmdc.harvard.edu"
 DEFAULT_CERT = "../resources/dvn-4.hmdc.harvard.edu"
+
+try:
+    from config_local import *
+except ImportError:
+    pass

dvn_client/src/dvn_client.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+
 # DVN client for SWORD API
 # Prereqs: Python, sword2 Module (available using easy_install)
 # Adapted from: https://bitbucket.org/beno/python-sword2/wiki/Quickstart
@@ -31,16 +33,19 @@ def parse_arguments():
 #    parser.add_argument('-u','--username', default=None, help='Description for foo argument')
 #    parser.add_argument('-p','--password', default=None, help='Description for bar argument')
 
-    parser.add_argument('--runTests', action="store", help='Path to a file with test definitions.')
-    parser.add_argument('--config', action="store", help="Path to a file that contains configuration information.")
+    parser.add_argument('--runTests', action="store", default='tests.py',
+            help='Path to a file with test definitions. (default: tests.py)')
+    parser.add_argument('--config', action="store", default='config.py',
+            help="Path to a file that contains configuration information. (default: config.py)")
     return parser.parse_args()
 
 def main():
     # Get the command line arguments.
     args = parse_arguments()
-    
-    if args.runTests and args.config:
+
+    if args.config:
         execfile(args.config, globals())
+    if args.runTests:
         execfile(args.runTests, globals())
 
     dv = None #declare outside so except clause has access
@@ -63,7 +68,7 @@ def main():
         print "RELEASED: ", dv.is_released()
 
         #s = Study.CreateStudyFromDict(PICS_OF_CATS_STUDY)
-        s = Study.CreateStudyFromAtomEntryXmlFile("/home/vagrant/dvn_client/resources/atom-entry-study.xml")
+        s = Study.CreateStudyFromAtomEntryXmlFile(ATOM_STUDY)
         dv.add_study(s)
         #s.add_files([INGEST_FILES])
         print s.get_citation()

dvn_client/src/dvn_test.py

@@ -4,46 +4,44 @@
 __author__="peterbull"
 __date__ ="$Aug 21, 2013 2:56:25 PM$"
 
-from operator import eq
 import os
 import sys
 from time import sleep
 import unittest
+import zipfile
 
 import logging
 logging.basicConfig(level=logging.ERROR)
 
 #local modules
+import config
+import tests as testdata
 from study import Study
 from connection import DvnConnection
-    
+
+
 class TestStudyOperations(unittest.TestCase):
+
     @classmethod
     def setUpClass(self):
-        # LOAD TEST DATA
-        
-        print "Loading test data."
-        testModulePath = os.path.dirname(__file__)
-        execfile(os.path.join(testModulePath, "config.py"), globals())    #CREDS - This file is not committed.
-        execfile(os.path.join(testModulePath, "tests.py"), globals())     #TEST DATA
-        
+
+        print "Verifying test data."
+        assert zipfile.is_zipfile(testdata.INGEST_FILES), 'Invalid tests configuration. %s is not a zipfile' % testdata.INGEST_FILES
+        assert os.path.isfile(testdata.PIC_OF_CAT), 'Invalid tests configuration. %s is not a file' % testdata.PIC_OF_CAT
+        assert os.path.isfile(testdata.ATOM_STUDY), 'Invalid tests configuration. %s is not a file' % testdata.ATOM_STUDY
+
         print "Connecting to DVN."
-        self.dvc = DvnConnection(username=DEFAULT_USERNAME,
-                        password=DEFAULT_PASSWORD, 
-                        host=DEFAULT_HOST, 
-                        cert=DEFAULT_CERT)
-                        
+        self.dvc = DvnConnection(username=config.DEFAULT_USERNAME,
+                        password=config.DEFAULT_PASSWORD, 
+                        host=config.DEFAULT_HOST, 
+                        cert=config.DEFAULT_CERT)
+
         print "Getting Dataverse"
         self.dv = self.dvc.get_dataverses()[0]
-        
-        print "Removing any existing studies."
-        self.dv.delete_all_studies(ignoreExceptions=True)
-        
+
     def setUp(self):
-        #runs before each test method
-        
         #create a study for each test
-        s = Study.CreateStudyFromDict(PICS_OF_CATS_STUDY)
+        s = Study.CreateStudyFromDict(testdata.PICS_OF_CATS_STUDY)
         self.dv.add_study(s)
         id = s.get_id()
         self.s = self.dv.get_study_by_hdl(id)
@@ -57,20 +55,20 @@ def tearDown(self):
             return
 
     def test_create_study_from_xml(self):
-        xmlStudy = Study.CreateStudyFromAtomEntryXmlFile(ATOM_STUDY)
+        xmlStudy = Study.CreateStudyFromAtomEntryXmlFile(testdata.ATOM_STUDY)
         self.dv.add_study(xmlStudy)
         atomStudy = self.dv.get_study_by_string_in_entry("The first study for the New England Journal of Coffee dataverse")
         self.assertTrue(atomStudy)
         self.dv.delete_study(atomStudy)
 
     def test_add_files_to_study(self):
-        expected_files = ["char_r.tab",
-                          "float_new_r.tab",
-                          "int_r.tab",
-                          "min_date_r.tab"]
-        self.s.add_files([INGEST_FILES])
+        zipped_file = zipfile.ZipFile(testdata.INGEST_FILES, 'r')
+        expected_files = [os.path.basename(f) for f in zipped_file.namelist()]
+        self.s.add_files([testdata.INGEST_FILES])
         sleep(3) #wait for ingest
         actual_files = [f.name for f in self.s.get_files()]
+        print 'actual', actual_files
+        print 'expected', expected_files
 
         expected_files.sort()
         actual_files.sort()
@@ -90,21 +88,22 @@ def test_display_study_statement(self):
         self.assertTrue(self.s.get_statement())
 
     def test_delete_a_file(self):
-        self.s.add_file(PIC_OF_CAT)
+        self.s.add_file(testdata.PIC_OF_CAT)
+        test_file = os.path.basename(testdata.PIC_OF_CAT)
 
         #add file and confirm
         files = self.s.get_files()
-        catFile = [f for f in files if f.name == "cat.jpg"]
+        catFile = [f for f in files if f.name == test_file]
         self.assertTrue(len(catFile) == 1)
 
         #delete file and confirm
         self.s.delete_file(catFile[0])
         files = self.s.get_files()
-        catFile = [f for f in files if f.name == "cat.jpg"]
+        catFile = [f for f in files if f.name == test_file]
         self.assertTrue(len(catFile) == 0)
-        
+
     def test_delete_a_study(self):
-        xmlStudy = Study.CreateStudyFromAtomEntryXmlFile(ATOM_STUDY)
+        xmlStudy = Study.CreateStudyFromAtomEntryXmlFile(testdata.ATOM_STUDY)
         self.dv.add_study(xmlStudy)
         atomStudy = self.dv.get_study_by_string_in_entry("The first study for the New England Journal of Coffee dataverse")
         self.assertTrue(atomStudy)
@@ -113,19 +112,19 @@ def test_delete_a_study(self):
         self.assertTrue(startingNumberOfStudies > 0)
         self.dv.delete_study(atomStudy)
         self.assertEqual(len(self.dv.get_studies()), startingNumberOfStudies - 1)
-        
+
     def test_release_study(self):
         self.assertTrue(self.s.get_state() == "DRAFT")
         self.s.release()
         self.assertTrue(self.s.get_state() == "RELEASED")
         self.dv.delete_study(self.s) #this should deaccession
         self.assertTrue(self.s.get_state() == "DEACCESSIONED")
-    
+
     def test_dataverse_released(self):
         self.assertTrue(self.dv.is_released())
-    
+
+
 if __name__ == "__main__":
     __file__ = sys.argv[0]
     suite = unittest.TestLoader().loadTestsFromTestCase(TestStudyOperations)
     unittest.TextTestRunner(verbosity=2).run(suite)
-

dvn_client/src/requirements.txt

@@ -0,0 +1,3 @@
+-e git+https://github.com/pjbull/python-client-sword2.git#egg=sword2
+argparse # for python 2.6
+lxml

readme.md

@@ -1,7 +1,65 @@
-This is a library for writing Python applications that make use of Dataverse Network (DVN) APIs.
+## Dataverse Network (DVN) API Client
 
-The code was originally written as a "proof of concept" at https://github.com/dvn/swordpoc/tree/master/dvn_client but the intention is to eventually publish the code on https://pypi.python.org so users can run `pip install dvn-client` to use the Python library.
+This is a library for writing Python applications that make use of Dataverse
+Network (DVN) APIs.  The code started as a "proof of concept" in the
+[dvn/swordpoc](https://github.com/dvn/swordpoc) repo and the intent is to
+publish the python client on https://pypi.python.org.
 
-For now https://github.com/dvn/swordpoc/blob/master/dvn_client/README.md has some tips but they should be incorporated into this repo.
+The proof of concept
+[README.md](https://github.com/dvn/swordpoc/blob/master/dvn_client/README.md)
+has some tips that have not been incorporated in to this readme yet.
+
+We have been trying to target Python 2.6 because that's the version that ships
+with the latest version (6) of Red Hat Enterprise Linux (RHEL) and CentOS. For
+testing backward compatibility with Python 2.6, this repo includes a Vagrant
+environment. Please note that before you run `vagrant up` you'll need to run
+`git submodule init` and `git submodule update` once after cloning this repo.
+
+## Installation
+
+You will need:
+
+* Python 2.6+
+* [pip](http://www.pip-installer.org/en/latest/)
+* gcc compiler (For OSX you will need xcode + command line tools, or [standalone install](https://github.com/kennethreitz/osx-gcc-installer#readme))
+* Dataverse account
+
+Once you have satisfied the above requirements, try the following commands.
+
+    $ git clone https://github.com/IQSS/dvn-client-python.git
+    $ cd dvn-client-python
+    $ virtualenv venv
+    $ source venv/bin/activate
+    $ pip install -r dvn_client/src/requirements.txt
+
+You may wish to manage virtualenvs using [virtualenvwrapper](http://virtualenvwrapper.readthedocs.org/en/latest/) instead.
+
+## Configuration
+
+Make a `config_local.py` file and fill out the config elements as appropriate. Do not commit this file.
+
+```python
+DEFAULT_USERNAME = ""
+DEFAULT_PASSWORD = ""
+DEFAULT_HOST = "dvn-4.hmdc.harvard.ed"
+DEFAULT_CERT = "../resources/dvn-4.hmdc.harvard.edu" #see below for info on the cert
+```
+
+## Installation Test
+
+* Navigate to `dvn-client-python/dvn-client/src/`
+* Edit test data in `tests.py` as appropriate
+* Run the client `python dvn_client.py`
+* To run all of the tests, run `python dvn_test.py` (for more options see [unittest](http://docs.python.org/2/library/unittest.html#assert-methods))
+
+## PEM Certificate (optional)
+
+If you are using a self-signed certificate, you may see an SSL error when you
+try to hit the server. In that case, follow these instructions.
+
+1. Open private/incognito window (in case you have already added a security exception) in FireFox (instructions will be slightly different for other browsers)
+2. Go to: https://{SERVER}/dvn/api/data-deposit/swordv2/service-document
+3. Add Exception > View > Details > Export
+4. Save the PEM to the “resources” folder of the dvn\_client project
+5. When calling `Dataverse.connect()` or `Dataverse()` constructor, pass a path to this file as `cert=[PATH_TO_CERTIFICATE]`
 
-We have been trying to target Python 2.6 because that's the version that ships with the latest version (6) of Red Hat Enterprise Linux (RHEL) and CentOS. For testing backward compatibility with Python 2.6, this repo includes a Vagrant environment. Please note that before you run `vagrant up` you'll need to run `git submodule init` and `git submodule update` once after cloning this repo.