From 2d270ff30bc502dc5d00e9678db18f2c9e7dbdae Mon Sep 17 00:00:00 2001 From: josuebrunel Date: Sat, 25 Apr 2015 11:14:10 +0200 Subject: [PATCH] #1 : Doc updated --- .gitignore | 1 + README.md | 27 +++----- docs/docs/contrib.md | 2 + docs/docs/index.md | 146 +++++++++++++++++++++++++++++++++++++++---- docs/docs/table.md | 1 + docs/mkdocs.yml | 7 ++- 6 files changed, 153 insertions(+), 31 deletions(-) create mode 100644 docs/docs/contrib.md create mode 100644 docs/docs/table.md diff --git a/.gitignore b/.gitignore index 27b3734..a2063ee 100755 --- a/.gitignore +++ b/.gitignore @@ -58,3 +58,4 @@ docs/_build/ myconfig.py *.xml +site diff --git a/README.md b/README.md index aabceac..50bf978 100755 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ MYQL MYQL is a Python wrapper of the Yahoo Query Language. -Yahoo! Query Langauge Documentation and Support +Yahoo! Query Language Documentation and Support =============================================== * Yahoo! Query Language - http://developer.yahoo.com/yql/ @@ -50,8 +50,7 @@ how to use >>> yql.diagnostics = True # To turn diagnostics on ``` -access to community tables --------------------------- +####access to community tables ```python >>> yql = myql.MYQL() @@ -73,8 +72,7 @@ access to community tables >>> # do your magic ``` -changing response format (xml or json) --------------------------------------- +####changing response format (xml or json) The response format is by default ***json***. @@ -94,18 +92,15 @@ u'\n>> +``` +or + +```python +>>> import myql +>>> yql = myql.MYQL(community=True) +>>> # do your magic +``` + +####Changing response format (xml or json) + +The response format is by default ***json***. + +```python +>>> import myql +>>> yql = myql.MYQL(format='xml', community=True) +>>> rep = yql.rawQuery('select name, woeid from geo.states where place="Congo"') +>>> rep.text +u'\nCuvette-Ouest Department55998384Cuvette Department2344968Plateaux District2344973Sangha2344974Lekoumou2344970Pool Department2344975Likouala Department2344971Niari Department2344972Brazzaville2344976Bouenza Department2344967Kouilou2344969\n\n' +>>> rep = yql.rawQuery('select name, woeid from geo.states where place="Congo"', format='json') +>>> rep.json() +{u'query': {u'count': 11, u'lang': u'en-US', u'results': {u'place': [{u'woeid': u'55998384', u'name': u'Cuvette-Ouest Department'}, {u'woeid': u'2344968', u'name': u'Cuvette Department'}, {u'woeid': u'2344973', u'name': u'Plateaux District'}, {u'woeid': u'2344974', u'name': u'Sangha'}, {u'woeid': u'2344970', u'name': u'Lekoumou'}, {u'woeid': u'2344975', u'name': u'Pool Department'}, {u'woeid': u'2344971', u'name': u'Likouala Department'}, {u'woeid': u'2344972', u'name': u'Niari Department'}, {u'woeid': u'2344976', u'name': u'Brazzaville'}, {u'woeid': u'2344967', u'name': u'Bouenza Department'}, {u'woeid': u'2344969', u'name': u'Kouilou'}]}, u'created': u'2014-08-27T04:52:38Z'}} +>>> +``` + + +Methods +------- + +####use(data_provider_url) +Changes the data provider + +```python +>>> yql.use('http://myserver.com/mytables.xml') +``` + +####desc(tablename) +Returns table description + +```python +>>> response = yql.desc('weather.forecast') +>>> response.json() +{u'query': {u'count': 1, u'lang': u'en-US', u'results': {u'table': {u'request': {u'select': [{u'key': [{u'required': u'true', u'type': u'xs:string', u'name': u'location'}, {u'type': u'xs:string', u'name': u'u'}]}, {u'key': [{u'required': u'true', u'type': u'xs:string', u'name': u'woeid'}, {u'type': u'xs:string', u'name': u'u'}]}]}, u'security': u'ANY', u'meta': {u'documentationURL': u'http://developer.yahoo.com/weather/', u'sampleQuery': u'select * from weather.forecast where woeid=2502265', u'description': u'Weather forecast table', u'author': u'Yahoo! Inc'}, u'hash': u'aae78b1462a6a8fbc748aec4cf292767', u'name': u'weather.forecast'}}, u'created': u'2014-08-16T19:31:51Z'}} +>>> +``` + +####rawQuery(query) + +Allows you to directly type your query + +```python +>>> response = yql.rawQuery("select * from geo.countries where place='North America'") +>>> # deal with the response +``` + +####select(table, fields, limit).where(filters, ...) + +Select a table i.e *weather.forecast*. +If *table* not provided, it will use the default table. If there's no such thing as a default table, it will raise a *NoTableSelectedError* + +***NB*** : A simple select doesn't return any data. Use ***GET*** instead. + +```python +>>> response = yql.select('geo.countries', [name, code, woeid]).where(['name', '=', 'Canada']) +>>> response.json() +{u'query': {u'count': 1, u'lang': u'en-US', u'results': {u'place': {u'woeid': u'23424775', u'name': u'Canada'}}, u'created': u'2014-08-16T19:04:08Z'}} +>>> ... +>>> rep = yql.select('geo.countries', ['name', 'woeid'], 2).where(['place', '=', 'Africa']) +>>> rep.json() +{u'query': {u'count': 2, u'lang': u'en-US', u'results': {u'place': [{u'woeid': u'23424740', u'name': u'Algeria'}, {u'woeid': u'23424745', u'name': u'Angola'}]}, u'created': u'2014-08-17T10:52:49Z'}} +>>> +>>> rep = yql.select('geo.countries', ['name', 'woeid'], 2).where(['place', 'in', ('Africa', 'Europe')]) +>>> rep.json() +{u'query': {u'count': 2, u'lang': u'en-US', u'results': {u'place': [{u'woeid': u'23424740', u'name': u'Algeria'}, {u'woeid': u'23424745', u'name': u'Angola'}]}, u'created': u'2014-08-17T11:22:49Z'}} +>>> +``` + +####get(table, fields, limit) +Same as ***SELECT***, but instead returns data. + +**REMINDER** : Some tables require a **where clause**, therefore ***GET*** won't work on those tables, use *select(...).where(...)* instead . + +```python +>>> yql.get('geo.countries', ['name', 'woeid'], 1) +>>> rep.json() +{u'query': {u'count': 1, u'lang': u'en-US', u'results': {u'place': {u'woeid': u'23424966', u'name': u'Sao Tome and Principe'}}, u'created': u'2014-08-17T10:32:25Z'}} +>>> +``` - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. diff --git a/docs/docs/table.md b/docs/docs/table.md new file mode 100644 index 0000000..ae8381b --- /dev/null +++ b/docs/docs/table.md @@ -0,0 +1 @@ +##OpenTable diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c97182f..3bd74ac 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1 +1,6 @@ -site_name: My Docs +site_name: myql +pages: +- [index.md, Home] +- [table.md, OpenTable] +- [contrib.md, Contribute] +theme: readthedocs