RCB-527 topics (#71)

* RCB-527 Topics

- Added topics to Api.py
- Created topics example
- Code cleanup on all examples
- Passed against jugmaster

* Updated README

- cleaned up obsolete instructions
- added list of available endpoints
- added release notes reference

* Updated examples README

* Added topics to unit tests

Author: cp2boston

README.md

@@ -1,10 +1,9 @@
 [![Build Status](https://travis-ci.org/rosette-api/python.svg?branch=master)](https://travis-ci.org/rosette-api/python)
 
-# This is the Python client binding for Rosette API.
-See the wiki for more information.
+## This is the Python client binding for Rosette API.
+Please check out the [wiki](https://github.com/rosette-api/python/wiki) for additional information
 
-Installation
-------------
+### Installation
 
 The Python binding requires Python 2.6 or greater and is available through pip:
 
@@ -19,79 +18,30 @@ To check your installed version:
 
 `pip show rosette_api`
 
-Basic Usage
------------
-
-```python
-# 1. Set utf-8 encoding.
-# -*- coding: utf-8 -*-
-
-# 2. Imports from rosette.api.
-from rosette.api import API, DocumentParameters, MorphologyOutput
-
-# 3. Create API object.
-api = API("[your_api-key]")
-
-# 4. Create parameters object
-params = DocumentParameters()
-
-# 5. Set parameters.
-params["content"] = "The quick brown fox jumped over the lazy dog. Yes he did."
-
-# 6. Make a call.
-result = api.morphology(params)
-
-# result is a Python dictionary that contains
-
-{u'tokens': [u'The', u'quick', u'brown', u'fox', u'jumped', u'over', u'the', u'lazy', u'dog', u'.', u'Yes', u'he', u'did', u'.'], u'posTags': [u'DET', u'ADJ', u'ADJ', u'NOUN', u'VERB', u'ADP', u'DET', u'ADJ', u'NOUN', u'PUNCT', u'VERB', u'PRON', u'VERB', u'PUNCT'], u'compoundComponents': [None, None, None, None, None, None, None, None, None, None, None, None, None, None], u'lemmas': [u'the', u'quick', u'brown', u'fox', u'jump', u'over', u'the', u'lazy', u'dog', u'.', u'yes', u'he', u'do', u'.'], u'hanReadings': [None, None, None, None, None, None, None, None, None, None, None, None, None, None]}
-```
-
-The samples use the following procedure:
-
-1. If the application reads text in, set encoding to utf-8 in the first line of the script.
-
-2. Import the `rosette.api` packages that your application needs. The `rosette.api` packages include
-    * `API`
-    * `DocumentParameters`
-    * `NameSimilarityParameters`
-    * `NameTranslationParameters`
-    * `MorphologyOutput`
-    * `DataFormat`
-
-3. Create an `API` object with the `user_key` parameter.
-
-4. Create a parameters object for your request input:
-
-   | Parameter | Endpoint |
-   | ----|----|
-   | `NameSimilarityParameters` | for `/name-similarity` |
-   | `NameTranslationParameters` | for `/translated-name` |
-   | `DocumentParameters` | for all other endpoints |
-
-
-5. Set the parameters required for your operation: "`content`" or "`contentUri`" for `DocumentParameters`;
-"`name`" and "`targetLanguage`" for `NameTranslationParameters`; "`name1.text`" and "`name2.text`" for
- `NameSimilarityParameters`; Other parameters are optional.
-
-6. Invoke the `API` method for the endpoint you are calling. The methods are
-    * `entities()` 
-    * `categories()`
-    * `sentiment()`
-    * `language()`
-    * `morphology(tag)` where tag is a member of `MorphologyOutput`: `LEMMAS`, `PARTS_OF_SPEECH`, `COMPOUND_COMPONENTS`, `HAN_READINGS`, or `COMPLETE`. An empty tag is equivalent to `COMPLETE`.
-    * `sentences()`
-    * `tokens()`
-    * `relationships()`
-    * `name_translation()`
-    * `name_similarity()`
-    * `matched_name()` *deprecated
-    * `translated_name()` *deprecated
-
-7. The API will return a dictionary with the results.
-
-See [examples](examples) for more request samples.
-
-## Docker ##
+### Basic Usage
+
+For help in how to call the various endpoints, please refer to the [examples](https://github.com/rosette-api/python/tree/develop/examples).
+
+### Supported Endpoints
+- categories
+- entities
+- info
+- language
+- morphology (complete, compound components, han readings, lemmas, parts of speech)
+- name deduplication
+- name similarity
+- name translation
+- ping
+- relationships
+- sentences
+- sentiment
+- syntax dependencies
+- text embedding
+- tokens
+- topics
+- transliteration
+
+### Docker
 A Docker image for running the examples against the compiled source library is available on Docker Hub.
 
 Command: `docker run -e API_KEY=api-key -v "<binding root directory>:/source" rosetteapi/docker-python`
@@ -100,12 +50,11 @@ Additional environment settings:
 `-e ALT_URL=<alternative URL>`
 `-e FILENAME=<single filename>`
 
-API Documentation
------------------
-
+### API Documentation
 See [documentation](http://rosette-api.github.io/python)
 
-Additional Information
-----------------------
+### Release Notes
+See [wiki](https://github.com/rosette-api/python/wiki/Release-Notes)
 
+### Additional Information
 Visit [Rosette API site](https://developer.rosette.com)

examples/README.md

@@ -38,6 +38,7 @@ Each example, when run, prints its output to the console.
 | sentences.py                     | Gets the sentences from a piece of text               |
 | sentiment.py                     | Gets the sentiment of a local file                    |
 | tokens.py                        | Gets the tokens (words) from a piece of text          |
+| topics.py | Returns key phrases and concepts from provided content |
 | translated-name.py               | Translates a name from one language to another        |
 | transliteration.py               | Transliterates the given text |
 

examples/categories.py

@@ -3,34 +3,40 @@
 """
 Example code to call Rosette API to get the category of a document (at a given URL).
 """
+from __future__ import print_function
 
 import argparse
 import json
 import os
 
+
 from rosette.api import API, DocumentParameters, RosetteException
 
 
-def run(key, altUrl='https://api.rosette.com/rest/v1/'):
+def run(key, alt_url='https://api.rosette.com/rest/v1/'):
+    """ Run the example """
     categories_url_data = "http://www.onlocationvacations.com/2015/03/05/the-new-ghostbusters-movie-begins-filming-in-boston-in-june/"
     url = categories_url_data
     # Create an API instance
-    api = API(user_key=key, service_url=altUrl)
+    api = API(user_key=key, service_url=alt_url)
     params = DocumentParameters()
 
     # Use a URL to input data instead of a string
     params["contentUri"] = url
     try:
         return api.categories(params)
-    except RosetteException as e:
-        print(e)
+    except RosetteException as exception:
+        print(exception)
 
 
-parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter, description='Calls the ' + os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
-parser.add_argument('-k', '--key', help='Rosette API Key', required=True)
-parser.add_argument('-u', '--url', help="Alternative API URL", default='https://api.rosette.com/rest/v1/')
+PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                 description='Calls the ' +
+                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
+PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
+PARSER.add_argument('-u', '--url', help="Alternative API URL",
+                    default='https://api.rosette.com/rest/v1/')
 
 if __name__ == '__main__':
-    args = parser.parse_args()
-    result = run(args.key, args.url)
-    print(json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))
+    ARGS = PARSER.parse_args()
+    RESULT = run(ARGS.key, ARGS.url)
+    print(json.dumps(RESULT, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))

examples/entities.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
-
 """
 Example code to call Rosette API to get entities from a piece of text.
 """
+from __future__ import print_function
 
 import argparse
 import json
@@ -11,23 +11,27 @@
 from rosette.api import API, DocumentParameters, RosetteException
 
 
-def run(key, altUrl='https://api.rosette.com/rest/v1/'):
+def run(key, alt_url='https://api.rosette.com/rest/v1/'):
+    """ Run the example """
     # Create an API instance
-    api = API(user_key=key, service_url=altUrl)
+    api = API(user_key=key, service_url=alt_url)
     entities_text_data = "Bill Murray will appear in new Ghostbusters film: Dr. Peter Venkman was spotted filming a cameo in Boston this… http://dlvr.it/BnsFfS"
     params = DocumentParameters()
     params["content"] = entities_text_data
     params["genre"] = "social-media"
     try:
         return api.entities(params)
-    except RosetteException as e:
-        print(e)
+    except RosetteException as exception:
+        print(exception)
 
-parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter, description='Calls the ' + os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
-parser.add_argument('-k', '--key', help='Rosette API Key', required=True)
-parser.add_argument('-u', '--url', help="Alternative API URL", default='https://api.rosette.com/rest/v1/')
+PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                 description='Calls the ' +
+                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
+PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
+PARSER.add_argument('-u', '--url', help="Alternative API URL",
+                    default='https://api.rosette.com/rest/v1/')
 
 if __name__ == '__main__':
-    args = parser.parse_args()
-    result = run(args.key, args.url)
-    print(json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))
+    ARGS = PARSER.parse_args()
+    RESULT = run(ARGS.key, ARGS.url)
+    print(json.dumps(RESULT, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))

examples/info.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
-
 """
 Example code to call Rosette API to get information such as version and build
 """
+from __future__ import print_function
 
 import argparse
 import json
@@ -11,21 +11,25 @@
 from rosette.api import API, RosetteException
 
 
-def run(key, altUrl='https://api.rosette.com/rest/v1/'):
+def run(key, alt_url='https://api.rosette.com/rest/v1/'):
+    """ Run the example """
     # Create an API instance
-    api = API(user_key=key, service_url=altUrl)
+    api = API(user_key=key, service_url=alt_url)
 
     try:
         return api.info()
-    except RosetteException as e:
-        print(e)
+    except RosetteException as exception:
+        print(exception)
 
 
-parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter, description='Calls the ' + os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
-parser.add_argument('-k', '--key', help='Rosette API Key', required=True)
-parser.add_argument('-u', '--url', help="Alternative API URL", default='https://api.rosette.com/rest/v1/')
+PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                 description='Calls the ' +
+                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
+PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
+PARSER.add_argument('-u', '--url', help="Alternative API URL",
+                    default='https://api.rosette.com/rest/v1/')
 
 if __name__ == '__main__':
-    args = parser.parse_args()
-    result = run(args.key, args.url)
-    print(json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))
+    ARGS = PARSER.parse_args()
+    RESULT = run(ARGS.key, ARGS.url)
+    print(json.dumps(RESULT, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))

examples/language.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
-
 """
 Example code to call Rosette API to determine the language of a piece of text.
 """
+from __future__ import print_function
 
 import argparse
 import json
@@ -11,25 +11,29 @@
 from rosette.api import API, DocumentParameters, RosetteException
 
 
-def run(key, altUrl='https://api.rosette.com/rest/v1/'):
+def run(key, alt_url='https://api.rosette.com/rest/v1/'):
+    """ Run the example """
     # Create an API instance
-    api = API(user_key=key, service_url=altUrl)
+    api = API(user_key=key, service_url=alt_url)
 
     language_data = "Por favor Señorita, says the man."
     params = DocumentParameters()
     params["content"] = language_data
     api.set_custom_headers("X-RosetteAPI-App", "python-app")
     try:
         return api.language(params)
-    except RosetteException as e:
-        print(e)
+    except RosetteException as exception:
+        print(exception)
 
 
-parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter, description='Calls the ' + os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
-parser.add_argument('-k', '--key', help='Rosette API Key', required=True)
-parser.add_argument('-u', '--url', help="Alternative API URL", default='https://api.rosette.com/rest/v1/')
+PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                 description='Calls the ' +
+                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
+PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
+PARSER.add_argument('-u', '--url', help="Alternative API URL",
+                    default='https://api.rosette.com/rest/v1/')
 
 if __name__ == '__main__':
-    args = parser.parse_args()
-    result = run(args.key, args.url)
-    print(json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))
+    ARGS = PARSER.parse_args()
+    RESULT = run(ARGS.key, ARGS.url)
+    print(json.dumps(RESULT, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))

examples/morphology_complete.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
-
 """
 Example code to call Rosette API to get the complete morphological analysis of a piece of text.
 """
+from __future__ import print_function
 
 import argparse
 import json
@@ -11,24 +11,28 @@
 from rosette.api import API, DocumentParameters, RosetteException
 
 
-def run(key, altUrl='https://api.rosette.com/rest/v1/'):
+def run(key, alt_url='https://api.rosette.com/rest/v1/'):
+    """ Run the example """
     # Create an API instance
-    api = API(user_key=key, service_url=altUrl)
+    api = API(user_key=key, service_url=alt_url)
 
     morphology_complete_data = "The quick brown fox jumped over the lazy dog. Yes he did."
     params = DocumentParameters()
     params["content"] = morphology_complete_data
     try:
         return api.morphology(params)
-    except RosetteException as e:
-        print(e)
+    except RosetteException as exception:
+        print(exception)
 
 
-parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter, description='Calls the ' + os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
-parser.add_argument('-k', '--key', help='Rosette API Key', required=True)
-parser.add_argument('-u', '--url', help="Alternative API URL", default='https://api.rosette.com/rest/v1/')
+PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                 description='Calls the ' +
+                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
+PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
+PARSER.add_argument('-u', '--url', help="Alternative API URL",
+                    default='https://api.rosette.com/rest/v1/')
 
 if __name__ == '__main__':
-    args = parser.parse_args()
-    result = run(args.key, args.url)
-    print(json.dumps(result, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))
+    ARGS = PARSER.parse_args()
+    RESULT = run(ARGS.key, ARGS.url)
+    print(json.dumps(RESULT, indent=2, ensure_ascii=False, sort_keys=True).encode("utf8"))