From f96f799fc5ea0cd12173b307dc7bb8d32763df54 Mon Sep 17 00:00:00 2001 From: mcohoon Date: Mon, 18 Apr 2016 10:34:37 -0700 Subject: [PATCH] Updated docs. --- README.md | 17 ++++++++++------- gav4/README.md | 15 +++++++++++++++ gav4/gav4.py | 12 ++++++------ setup.cfg | 3 +++ setup.py | 1 - tests/README.md | 19 +++++++++++++++++++ tests/data.py | 4 ++-- tests/test_gav4.py | 8 ++++---- 8 files changed, 59 insertions(+), 20 deletions(-) create mode 100644 gav4/README.md create mode 100644 tests/README.md diff --git a/README.md b/README.md index 9a91f70..1762443 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Google Analytics Reporting V4 Compatibility Library +# Google Analytics Reporting API V4 Compatibility Library [![Analytics](https://ga-beacon.appspot.com/UA-76561751-1/googleanalytics/gav4-python?pixel)](https://github.com/googleanalytics/gav4-python) -A library for converting Google Analytics Core Reporting API V3 request to Analytics Reporting API V4 requests. +A library for converting Google Analytics [Core Reporting API V3](https://developers.google.com/analytics/devguides/reporting/core/v3/) request to [Analytics Reporting API V4](https://developers.google.com/analytics/devguides/reporting/core/v4/) requests. ## Installation @@ -9,23 +9,23 @@ A library for converting Google Analytics Core Reporting API V3 request to Analy ## Typical usage example -There are two methods of using the gav4 library. You can `apply` the library to an authorized Google Analytics Service object, which exposes a get method that operates much like the current Core Reporting API V3. +There are two methods of using the gav4 library. You can `apply` the library to an authorized `analyticsreporting` Service object, which exposes a get method that operates much like the current Core Reporting API V3. import gav4 - # Apply the gav4 get method to the authorized service object. - gav4.apply_gav4(analytics) + # Apply the gav4 get method to the analyticsreporting service object. + gav4.apply_gav4(analyticsreporting) # Call the gav4_get method with a V3 request and get a V3 response. v3_response = analytics.gav4_get(v3_request).execute() -Alternatively you can convert the requests and responses directly. +Alternatively, you can convert the requests and responses directly. # Convert a V3 request into a V4 request. v4_request = gav4.convert_request(v3_request) # Call the V4 API. - v4_response = analytics.reports().batchGet(body=v4_request).execute() + v4_response = analyticsreporting.reports().batchGet(body=v4_request).execute() # Convert the V4 API response into a V3 response. v3_response = gav4.convert_report(v4_response.get('reports', [])[0]) @@ -61,3 +61,6 @@ You can sign these electronically (just scroll to the bottom). After that, we'll All submissions, including submissions by project members, require review. We use Github pull requests for this purpose. +### Naming + +This library is strictly for the Analytics Reporting API and not to be confused with the [Google Analytics Android SDK V4](https://developers.google.com/analytics/devguides/collection/android/v4/). diff --git a/gav4/README.md b/gav4/README.md new file mode 100644 index 0000000..b3ac8c6 --- /dev/null +++ b/gav4/README.md @@ -0,0 +1,15 @@ +# Google Analytics Reporting API V4 Compatibility Library [![Analytics](https://ga-beacon.appspot.com/UA-76561751-1/googleanalytics/gav4-python/gav4?pixel)](https://github.com/googleanalytics/gav4-python) + +## Contents + +### [`gav4.py`](gav4.py) + +The `gav4.py` contains functions to convert each of the [Core Reporting API V3](https://developers.google.com/analytics/devguides/reporting/core/v3/) parameters to [Analytics Reporting API V4](https://developers.google.com/analytics/devguides/reporting/core/v4/) request fields. + +The file also contains the `apply_gav4` function which can be called with an authorized `analyticsreporting` service object; once applied, you can call: + + `analyticsreporting.gav4_get(...)` + +which takes the same parameters and returns the same response as when you call the Core reporting API V3 method: + + `analytics.data().ga().get(...)` diff --git a/gav4/gav4.py b/gav4/gav4.py index ef87b2d..cab6cdc 100644 --- a/gav4/gav4.py +++ b/gav4/gav4.py @@ -15,25 +15,25 @@ """Library for converting V3 API request to V4 API requests. -This library contains helper functions to convert a Core Reporting API V3 +This library contains helper functions which convert a Core Reporting API V3 request into a Analytics Reporting API V4 request. It is designed to work in concert to the Google API Python client library. import gav4 - # Apply the gav4 get method to the authorized service object. - gav4.apply_gav4(analytics) + # Apply the gav4 get method to the analyticsreporting service object. + gav4.apply_gav4(analyticsreporting) # Call the gav4_get method with a V3 request and get a V3 response. v3_response = analytics.gav4_get(v3_request).execute() -Alternatively you can convert the requests and responses directly. +Alternatively, you can convert the requests and responses directly. # Convert a V3 request into a V4 request. v4_request = gav4.convert_request(v3_request) # Call the V4 API. - v4_response = analytics.reports().batchGet(body=v4_request).execute() + v4_response = analyticsreporting.reports().batchGet(body=v4_request).execute() # Convert the V4 API response into a V3 response. v3_response = gav4.convert_report(v4_response.get('reports', [])[0]) @@ -171,7 +171,7 @@ def convert_request(**kwargs): def gav4_get(self, **kwargs): - """A service object method this method converts and calls the requests. + """A service object method which converts and calls the requests. This method gets attached to an authorized analytics V4 service object. It operates like a V3 data().ga().get() method. diff --git a/setup.cfg b/setup.cfg index 2a9acf1..1eee7db 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,2 +1,5 @@ [bdist_wheel] universal = 1 + +[metadata] +description-file = README.md diff --git a/setup.py b/setup.py index 4e33856..a160eb0 100644 --- a/setup.py +++ b/setup.py @@ -38,7 +38,6 @@ description='Google Analytics V4 API Compatibility Library', author='Google Analytics Platform', author_email='mcohoon+gav4-python@google.com', - long_description=README, scripts=[], url='https://github.com/googleanalytics/gav4-python', packages=find_packages(), diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..73c6414 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,19 @@ +# GAV4 Tests [![Analytics](https://ga-beacon.appspot.com/UA-76561751-1/googleanalytics/gav4-python/tests?pixel)](https://github.com/googleanalytics/gav4-python) + +## Testing + +Run the tests with the following command: + + python setup.py tests + +This may require you to install the nose library -- `pip install nose`. + +## Contents + +### [data.py](data.py) + +The `data.py` file contain requests requests, converted requests, responses, converted responses, and mocks of the service objects and its member objects. + +### [test_gav4.py](test_gav4.py) + +The `test_gav4.py` file contains tests for the gav4 library. It includes unit tests for the individual conversion methods as well as an end-to-end integration test. diff --git a/tests/data.py b/tests/data.py index 2edc226..bf9a9b1 100644 --- a/tests/data.py +++ b/tests/data.py @@ -494,8 +494,8 @@ def batchGet(self, body): # pylint: disable=invalid-name return BatchGet(body) -class Analytics(object): - """Mock Google Analytics service object.""" +class AnalyticsReporting(object): + """Mock AnalyticsReporting service object.""" def reports(self): """Returns a mock Reports object.""" diff --git a/tests/test_gav4.py b/tests/test_gav4.py index 175e7b4..ad0f7fa 100644 --- a/tests/test_gav4.py +++ b/tests/test_gav4.py @@ -73,13 +73,13 @@ def testGav4Get(self): """ # Get the MOCK authenticated service object. - analytics = data.Analytics() + analyticsreporting = data.AnalyticsReporting() # Apply the gav4 library. - gav4.apply_gav4(analytics) + gav4.apply_gav4(analyticsreporting) - # Call the veeneer_get() method. - request = analytics.gav4_get(**data.V3_REQUEST) + # Call the gav4_get() method. + request = analyticsreporting.gav4_get(**data.V3_REQUEST) # Call the wrapped execute method. response = request.execute()