myql 1.2.7

`mYQL <http://myql.readthedocs.org/en/latest/>`__
=================================================

|Build Status| |Documentation Status| |Code Health| |PyPI| |PyPI| |PyPI|
|PyPI| |PyPI| |Coverage Status| |PyPI|

mYQL is a Python wrapper of the Yahoo Query Language.

Yahoo! Query Language Documentation and Support
===============================================

- Yahoo! Query Language - http://developer.yahoo.com/yql/
- Yahoo! Developer Network: http://developer.yahoo.com
- Yahoo! Application Platform - http://developer.yahoo.com/yap/
- Yahoo! Social APIs - http://developer.yahoo.com/social/
- Yahoo! QUery Language Console
https://developer.yahoo.com/yql/console/

Features
~~~~~~~~

- Simple YQL Query
- Authenticated YQL Query ( OAuth )
- StockScraper
- YQL Open Table (Classes and Metaclasses) Generator
- Response prettyfier

Installation
============

.. code:: shell

$ pip install myql

Quick Start
===========

It's important to know that **response** is a just
**requests.models.Response** object. Yes indeed, ***mYQL*** uses
***requests*** :smile:

By default, you have access to the **community tables**. If for
whatsoever reason you would like to not have access to those tables

.. code:: python

>>> import myql
>>> yql = myql.MYQL(community=False)

Changing response format (xml or json)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The response format is by default ***json***.

.. code:: python

>>> import myql
>>> from myql.utils import pretty_json, pretty_xml
>>> yql = myql.MYQL(format='xml', community=True)
>>> resp = yql.raw_query('select name, woeid from geo.states where place="Congo"')
>>> print(pretty_xml(resp.content))
<?xml version="1.0" encoding="utf-8"?>
<query xmlns:yahoo="http://www.yahooapis.com/v1/base.rng" yahoo:count="11" yahoo:created="2015-06-07T11:56:11Z" yahoo:lang="en-US">
<results>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Cuvette-Ouest Department</name>
<woeid>55998384</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Cuvette Department</name>
<woeid>2344968</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Plateaux District</name>
<woeid>2344973</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Sangha</name>
<woeid>2344974</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Lekoumou</name>
<woeid>2344970</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Pool Department</name>
<woeid>2344975</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Likouala Department</name>
<woeid>2344971</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Niari Department</name>
<woeid>2344972</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Brazzaville</name>
<woeid>2344976</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Bouenza Department</name>
<woeid>2344967</woeid>
</place>
<place xmlns="http://where.yahooapis.com/v1/schema.rng">
<name>Kouilou</name>
<woeid>2344969</woeid>
</place>
</results>
</query>
<!-- total: 33 -->
<!-- pprd1-node1003-lh3.manhattan.bf1.yahoo.com -->

>>> resp = yql.raw_query('select name, woeid from geo.states where place="Congo"', format='json')
>>> print(pretty_json(resp.content))
{
"query": {
"count": 11,
"created": "2015-06-07T11:58:20Z",
"lang": "en-US",
"results": {
"place": [
{
"name": "Cuvette-Ouest Department",
"woeid": "55998384"
},
{
"name": "Cuvette Department",
"woeid": "2344968"
},
{
"name": "Plateaux District",
"woeid": "2344973"
},
{
"name": "Sangha",
"woeid": "2344974"
},
{
"name": "Lekoumou",
"woeid": "2344970"
},
{
"name": "Pool Department",
"woeid": "2344975"
},
{
"name": "Likouala Department",
"woeid": "2344971"
},
{
"name": "Niari Department",
"woeid": "2344972"
},
{
"name": "Brazzaville",
"woeid": "2344976"
},
{
"name": "Bouenza Department",
"woeid": "2344967"
},
{
"name": "Kouilou",
"woeid": "2344969"
}
]
}
}
}

>>>

Methods
-------

use(yql\_table\_url,name=yql\_table\_name)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Maps a table name to the URL of an Open Data Table.

.. code:: python

>>> yql.use('http://www.josuebrunel.org//users.xml', name='myusers')

desc(tablename)
^^^^^^^^^^^^^^^

Returns table description

.. code:: python

>>> response = yql.desc('weather.forecast')
>>> print(pretty_json(response.content))
{
"query": {
"count": 1,
"created": "2015-06-07T12:00:27Z",
"lang": "en-US",
"results": {
"table": {
"hash": "aae78b1462a6a8fbc748aec4cf292767",
"meta": {
"author": "Yahoo! Inc",
"description": "Weather forecast table",
"documentationURL": "http://developer.yahoo.com/weather/",
"sampleQuery": "select * from weather.forecast where woeid=2502265"
},
"name": "weather.forecast",
"request": {
"select": [
{
"key": [
{
"name": "location",
"required": "true",
"type": "xs:string"
},
{
"name": "u",
"type": "xs:string"
}
]
},
{
"key": [
{
"name": "woeid",
"required": "true",
"type": "xs:string"
},
{
"name": "u",
"type": "xs:string"
}
]
}
]
},
"security": "ANY"
}
}
}
}

>>>

raw\_query(query)
^^^^^^^^^^^^^^^^^

Allows you to directly type your query

.. code:: python

>>> response = yql.raw_query("select * from geo.countries where place='North America'")
>>> # deal with the response

select(table, fields, limit).where(filters, ...)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

***NB*** : A simple select doesn't return any data. Use ***GET***
instead.

.. code:: python

>>> response = yql.select('geo.countries', ['name', 'code', 'woeid']).where(['name', '=', 'Canada'])
>>> print(pretty_json(response.content))
{
"query": {
"count": 1,
"created": "2015-06-07T12:10:39Z",
"lang": "en-US",
"results": {
"place": {
"name": "Canada",
"woeid": "23424775"
}
}
}
}

>>> ...
>>> response = yql.select('geo.countries', ['name', 'woeid'], 2).where(['place', 'in', ('Africa', 'Europe')])
>>> from myql.utils import dump
>>> dump(response)
{
"query": {
"count": 2,
"created": "2015-06-07T12:27:04Z",
"lang": "en-US",
"results": {
"place": [
{
"name": "Algeria",
"woeid": "23424740"
},
{
"name": "Angola",
"woeid": "23424745"
}
]
}
}
}

>>>

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 .

.. code:: python

>>> from myql.utils import dump
>>> response = yql.get('geo.countries', ['name', 'woeid'], 1)
>>> dump(response)
{
"query": {
"count": 1,
"created": "2015-06-07T12:29:01Z",
"lang": "en-US",
"results": {
"place": {
"name": "Sao Tome and Principe",
"woeid": "23424966"
}
}
}
}

>>>

insert(table, (field1, field2, ..., fieldN),(value1, value2, ..., valueN))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Insert values into a table. Arguments 2 and 3 may be **tuples** or
**list**.

.. code:: python

>>> from myql.utils import pretty_json
>>> response = yql.insert('yql.storage.admin',('value',),('http://josuebrunel.org',))
>>> print(pretty_json(response.content))
{
"query": {
"count": 1,
"created": "2015-05-14T13:25:56Z",
"lang": "en-US",
"results": {
"inserted": {
"execute": "store://KkkC5xDw4v32IcWWSQ4YRe",
"select": "store://Zc5LHXcmYM7XBfSbo9tzFL",
"update": "store://Rqb5fbQyDvrfHJiClWnZ6q"
}
}
}
}

update(table,[field1, ..., fieldN],[value1, ..., ...valueN]).where(filters, ...)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Update fields values. This method **is always followed by
***where()*****. Arguments 2 and 3 may be **tuples** or **list**.

.. code:: python

>>> from myql.utils import pretty_json
>>> response = yql.update('yql.storage',('value',),('https://josuebrunel.org',)).where(['name','=','store://Rqb5fbQyDvrfHJiClWnZ6q'])
>>> print(pretty_json(response.content))
{
"query": {
"count": 1,
"created": "2015-05-14T13:32:52Z",
"lang": "en-US",
"results": {
"success": "Updated store://KkkC5xDw4v32IcWWSQ4YRe"
}
}
}

delete(table).where(filters, ...)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Delete records

.. code:: python

>>> from myql.utils import pretty_json
>>> response = self.yql.delete('yql.storage').where(['name','=','store://Rqb5fbQyDvrfHJiClWnZ6q'])
>>> print(pretty_json(response.content))
{
"query": {
"count": 1,
"created": "2015-05-14T13:38:28Z",
"lang": "en-US",
"results": {
"success": "store://Rqb5fbQyDvrfHJiClWnZ6q deleted"
}
}
}

Using OAuth
^^^^^^^^^^^

***mYQL*** comes with
***`yahoo\_oauth <http://yahoo-oauth.readthedocs.org/en/master/>`__***,
which is an OAuth library for Yahoo! APIs.

.. code:: python

>>> from yahoo_oauth import OAuth1
>>> oauth = OAuth1(None, None, from_file='credentials.json') # only consumer_key and consumer_secret are required.
>>> from myql import MYQL
>>> yql = MYQL(format='xml', oauth=oauth)
>>> response = yql.get_guid('josue_brunel') # Deal with the response

Stocks Scraper
^^^^^^^^^^^^^^

The full documentation on ***StockScraper*** is
`here <https://myql.readthedocs.org/en/latest/stockscraper/>`__

Release Notes
^^^^^^^^^^^^^

##### 1.2.6
-----------

- Fixed `#148 <https://github.com/josuebrunel/myql/issues/148>`__

##### 1.2.5
-----------

- camelCase dropped for underscore
- Support for substitution variable i.e @myvar
- Support of Remote Filters
- Support of Post Query Filters

##### 1.2.4
-----------

- Weather module added
- StockScraper now under Finance namespace

##### 1.2.3
-----------

- Fixed issue related to date in StockRetriver.get\_historical\_info
`#107 <https://github.com/josuebrunel/myql/issues/107>`__
- Fixed issue with **IN** condition in **where** clause
`#106 <https://github.com/josuebrunel/myql/issues/107>`__
- Fix definition of raw\_input for python3
`#105 <https://github.com/josuebrunel/myql/issues/105>`__
- Yahoo-OAuth included as main oauth library
`#112 <https://github.com/josuebrunel/myql/issues/112>`__

##### 1.2.2
-----------

- **Python3** support OK
`#71 <https://github.com/josuebrunel/myql/issues/71>`__
- **PyPy/PyPy3** support OK
- Fixed issue with **IN** condition in **where** clause
- Fixed issue when passing an empty list/tuple (**[]/()**) in a
**where** clause besides first argument
- Import of
***`StockParser <https://github.com/gurch101/StockScraper>`__*** from
Gurchet Rai OK
`#68 <https://github.com/josuebrunel/myql/issues/68>`__
- Insert, Update, Delete methods added
`#67 <https://github.com/josuebrunel/myql/issues/67>`__
- Dummy *try/except* removed from main module
- Fixed **Invalid OAuth Signature** when using a refreshed token
`#64 <https://github.com/josuebrunel/myql/issues/64>`__
- Fixed misused of ***MYQL.use(...)***
`#76 <https://github.com/josuebrunel/myql/issues/76>`__
- Fixed format issue
`#82 <https://github.com/josuebrunel/myql/issues/82>`__
- Added useful functions in utils
`#81 <https://github.com/josuebrunel/myql/issues/81>`__
- Default access to community tables
- Response prettyfier : *pretty\_json, pretty\_xml*

##### v 1.2.1
-------------

- Multiple requests while using OAuth fixed

##### 1.2.0
-----------

- OpenTable classes
- Access to resources requiring authentication

##### 0.5.6
-----------

- fetch data
- access to community data
- select data format (xml/json)
- change data source
- filter data
- fix handling of default response format on the fly
- fix limit on ***select(...).where(...)*** when no limit value is
passed
- fix limit on ***get(...)***

.. |Build Status| image:: https://travis-ci.org/josuebrunel/myql.svg?branch=master
:target: https://travis-ci.org/josuebrunel/myql
.. |Documentation Status| image:: https://readthedocs.org/projects/myql/badge/?version=latest
:target: https://myql.readthedocs.org
.. |Code Health| image:: https://landscape.io/github/josuebrunel/myql/master/landscape.svg?style=flat
:target: https://landscape.io/github/josuebrunel/myql/master
.. |PyPI| image:: https://img.shields.io/pypi/status/myql.svg?style=flat
:target: https://pypi.python.org/pypi/myql
.. |PyPI| image:: https://img.shields.io/pypi/v/myql.svg?style=flat
:target: https://pypi.python.org/pypi/myql
.. |PyPI| image:: https://img.shields.io/pypi/dm/myql.svg?style=flat
:target: https://pypi.python.org/pypi/myql
.. |PyPI| image:: https://img.shields.io/pypi/pyversions/myql.svg
:target: https://pypi.python.org/pypi/myql
.. |PyPI| image:: https://img.shields.io/pypi/implementation/myql.svg?style=flat
:target: https://pypi.python.org/pypi/myql
.. |Coverage Status| image:: https://coveralls.io/repos/josuebrunel/myql/badge.svg?branch=testing
:target: https://coveralls.io/r/josuebrunel/myql?branch=master
.. |PyPI| image:: https://img.shields.io/pypi/l/myql.svg?style=flat
:target: https://pypi.python.org/pypi/myql