Python: module yahoo.search.web

Python: module yahoo.search.web

 
 yahoo.search.web (version 1.10, Sun Feb 25 21:47:52 MST 2007)index/home/leif/hack/pysearch.git/yahoo/search/web.py
yahoo.search.web - Web Search services module
 
This module implements the Web Search web services, searching web content.
The supported classes of web searches are:
    
    WebSearch           - Web Search
    ContextSearch       - Web Search with a context added
    RelatedSuggestion   - Web Search Related Suggestion
    SpellingSuggestion  - Web Search Spelling Suggestion
 
An application ID (appid) is always required when instantiating a search
object. In addition, each search class takes different set of parameters,
as defined by this table
 
                 Web   Context  Related  Spelling
                -----  -------  -------  --------
    query        [X]     [X]      [X]       [X]
    region       [X]      .        .         .
    context       .      [X]       .         .
    type         [X]     [X]       .         .
    results      [X]     [X]      [X]        .
    start        [X]     [X]       .         .
 
    format       [X]     [X]       .         .
    adult_ok     [X]     [X]       .         .
    similar_ok   [X]     [X]       .         .
    language     [X]     [X]       .         .
    country      [X]     [X]       .         .
    site         [X]      .        .         .
    subscription [X]      .        .         .
 
    output       [X]     [X]      [X]       [X]
    callback     [X]     [X]      [X]       [X]
 
 
Each of these parameter is implemented as an attribute of each
respective class. For example, you can set parameters like:
 
    from yahoo.search.web import WebSearch
 
    srch = WebSearch(app_id="YahooDemo")
    srch.query = "Leif Hedstrom"
    srch.results = 40
 
    for res in srch.parse_results():
       print res.Url

 
Modules

       
types
yahoo

 
Classes

       

yahoo.search._CommonSearch(yahoo.search._Search)
ContextSearch
WebSearch
yahoo.search._Search(yahoo.search.debug.Debuggable, __builtin__.object)
RelatedSuggestion
SpellingSuggestion

 
class ContextSearch(yahoo.search._CommonSearch)

   
ContextSearch - perform a Yahoo Web Search with a context
 
This class implements the Contextual Web Search service APIs, which is
very similar to a regular web search. Allowed parameters are:
 
    query        - The query to search for (UTF-8 encoded).
    context      - The context to extract meaning from (UTF-8 encoded).
    type         - The kind of search to submit (all, any or phrase).
                      * all returns results with all query terms.
                      * any resturns results with one or more of the
                        query terms.
                      * phrase returnes results containing the query
                        terms as a phrase.
    results      - The number of results to return (1-100).
    start        - The starting result position to return (1-based).
                   The finishing position (start + results - 1) cannot
                   exceed 1000.
    format       - Specifies the kind of web file to search for.
    adult_ok     - The service filters out adult content by default.
                   Enter a 1 to allow adult content.
    similar_ok   - Specifies whether to allow multiple results with
                   similar content. Enter a 1 to allow similar content.
    language     - The language the results are written in.
    country      - The country code for the country the website is
                   located in.
    license      - The Creative Commons license that the contents are
                   licensed under. You may submit multiple values (e.g.
                   license=cc_commercial&license=cc_modifiable).
    output       - The format for the output result. If json or php is
                   requested, the result is not XML parseable, so we
                   will simply return the "raw" string.
    callback     - The name of the callback function to wrap around
                   the JSON data.
    
 
Supported formats are
 
    html      - Regular HTML / XHTML
    msword    - Microsoft Word
    pdf       - Adobe PDF
    ppt       - Microsoft PowerPoint
    rss       - RSS feed
    txt       - Text file
    xls       - Microsft Excel
 
 
Full documentation for this service is available at:
 
    http://developer.yahoo.net/web/V1/contextSearch.html 
 

Method resolution order:
ContextSearch
yahoo.search._CommonSearch
yahoo.search._Search
yahoo.search.debug.Debuggable
__builtin__.object

Data and other attributes defined here:

METHOD = 'POST'
NAME = 'contextSearch'
SERVICE = 'WebSearchService'

Methods inherited from yahoo.search._Search:

__getattr__(self, name)
__init__(self, app_id, opener=None, xml_parser=None, result_factory=None, debug_level=0, **args)
The app_id is a required argument, the Yahoo search services will
not accept requests without a proper app_id. A valid app_id is a
combination of 8 - 40 characters, matching the regexp
 
    "^[a-zA-Z0-9 _()\[\]*+\-=,.:\\@]{8,40}$"
 
Please visit http://developer.yahoo.net/search/ to request an App ID
for your own software or application.
    
Four optional arguments can also be passed to the constructor:
 
    opener         - Opener for urllib2
    xml_parser     - Function to parse XML (default: minidom)
    result_factory - Result factory class (default: none)
    debug_devel    - Debug level (if any)
 
All other "named" arguments are passed into as a dictionary to the
set_params() method.
 
The result factory is specific to the particular web service used,
e.g. the different Yahoo Search services will each implement their
own factory class.
 
Both of these settings can be controlled via their respective
install method (see below).
__setattr__(self, name, value)
# Implement the attribute handlers, to avoid confusion
encode_params(self)
URL encode the list of parameter values.
get_param(self, param)
Get the value of a query parameter, or the default value if unset
get_results(self, stream=None, xml_parser=None, close=True)
Read the stream (if provided) and either return the raw XML, or
send the data to the provided XML parser for further processing.
If no stream is provided, it will call the open() method using the
default opener. The stream will be closed upon return from this
method, unless the close=False is passed as an argument.
get_url(self, with_params=True)
Return the URL for this request object
get_valid_params(self)
Return a list of all valid parameters for this search
install_opener(self, opener)
Install a URL opener (for use with urllib2), overriding the
default opener. This is rarely required.
install_result_factory(self, result_factory)
Install a python class (not an instance!) that should be used as a
factory for creating result(s) objects.
install_xml_parser(self, xml_parser)
Install an XML parser that will be used for all results for this
object. The parser is expected to "read" the data from the supplied
stream argument. To uninstall the parser (e.g. to make sure we
return raw XML data) simply call this method with an argument of
None.
missing_params(self)
Validate that the search object is propertly setup with all
required parameters etc. This is called automatically before a
search is actually performed, but you can also call it manually
if desired. It will return a list of zero or more paramters that
are missing.
open(self, opener=None, retries=2)
Open a connection to the webservice server, and request the URL.
The return value is a "stream", which can be read calling the
read(), readline() or readlines() methods. If you override this
method, please make sure to call the missing_params() method before
you try to send a request to the Web server.
parse_results(self, xml=None)
Get the result from the request, and instantiate the appropriate
result class. This class will be populated with all the data from
the XML object.
reset(self)
Reset all the parameter values for the object instance.
set_param(self, param, value)
Set the value of a query parameter
set_params(self, args)
Set one or several query parameters from a dictionary

Data descriptors inherited from yahoo.search._Search:

app_id
Application ID (issued by Yahoo), same ass appid
appid
Application ID (issued by Yahoo)
cc_licenses
List of all supported Creative Commons licenses
countries
List of all supported county codes
debug_level
Set and modify the debug level
languages
List of all supported languages
regions
List of all supported region codes
subscriptions
List of all supported premium subscriptions
svc_name
Descriptive name of the service
svc_protocol
Service protocol (e.g. HTTP)
svc_server
Service server name or IP
svc_service
Service path
svc_version
Service version string

Data and other attributes inherited from yahoo.search._Search:

PROTOCOL = 'http'
SERVER = 'search.yahooapis.com'
VERSION = 'V1'

Data descriptors inherited from yahoo.search.debug.Debuggable:

__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class RelatedSuggestion(yahoo.search._Search)

   
RelatedSuggestion - perform a Yahoo Web Related Suggestions search
 
This class implements the Web Search Related Suggestion web service
APIs. The only allowed parameters are:
 
    query        - The query to get related searches from
    results      - The number of results to return (1-50)
    output       - The format for the output result. If json or php is
                   requested, the result is not XML parseable, so we
                   will simply return the "raw" string.
    callback     - The name of the callback function to wrap around
                   the JSON data.
 
 
Full documentation for this service is available at:
 
    http://developer.yahoo.net/web/V1/relatedSuggestion.html 
 

Method resolution order:
RelatedSuggestion
yahoo.search._Search
yahoo.search.debug.Debuggable
__builtin__.object

Data and other attributes defined here:

NAME = 'relatedSuggestion'
SERVICE = 'WebSearchService'

Methods inherited from yahoo.search._Search:

__getattr__(self, name)
__init__(self, app_id, opener=None, xml_parser=None, result_factory=None, debug_level=0, **args)
The app_id is a required argument, the Yahoo search services will
not accept requests without a proper app_id. A valid app_id is a
combination of 8 - 40 characters, matching the regexp
 
    "^[a-zA-Z0-9 _()\[\]*+\-=,.:\\@]{8,40}$"
 
Please visit http://developer.yahoo.net/search/ to request an App ID
for your own software or application.
    
Four optional arguments can also be passed to the constructor:
 
    opener         - Opener for urllib2
    xml_parser     - Function to parse XML (default: minidom)
    result_factory - Result factory class (default: none)
    debug_devel    - Debug level (if any)
 
All other "named" arguments are passed into as a dictionary to the
set_params() method.
 
The result factory is specific to the particular web service used,
e.g. the different Yahoo Search services will each implement their
own factory class.
 
Both of these settings can be controlled via their respective
install method (see below).
__setattr__(self, name, value)
# Implement the attribute handlers, to avoid confusion
encode_params(self)
URL encode the list of parameter values.
get_param(self, param)
Get the value of a query parameter, or the default value if unset
get_results(self, stream=None, xml_parser=None, close=True)
Read the stream (if provided) and either return the raw XML, or
send the data to the provided XML parser for further processing.
If no stream is provided, it will call the open() method using the
default opener. The stream will be closed upon return from this
method, unless the close=False is passed as an argument.
get_url(self, with_params=True)
Return the URL for this request object
get_valid_params(self)
Return a list of all valid parameters for this search
install_opener(self, opener)
Install a URL opener (for use with urllib2), overriding the
default opener. This is rarely required.
install_result_factory(self, result_factory)
Install a python class (not an instance!) that should be used as a
factory for creating result(s) objects.
install_xml_parser(self, xml_parser)
Install an XML parser that will be used for all results for this
object. The parser is expected to "read" the data from the supplied
stream argument. To uninstall the parser (e.g. to make sure we
return raw XML data) simply call this method with an argument of
None.
missing_params(self)
Validate that the search object is propertly setup with all
required parameters etc. This is called automatically before a
search is actually performed, but you can also call it manually
if desired. It will return a list of zero or more paramters that
are missing.
open(self, opener=None, retries=2)
Open a connection to the webservice server, and request the URL.
The return value is a "stream", which can be read calling the
read(), readline() or readlines() methods. If you override this
method, please make sure to call the missing_params() method before
you try to send a request to the Web server.
parse_results(self, xml=None)
Get the result from the request, and instantiate the appropriate
result class. This class will be populated with all the data from
the XML object.
reset(self)
Reset all the parameter values for the object instance.
set_param(self, param, value)
Set the value of a query parameter
set_params(self, args)
Set one or several query parameters from a dictionary

Data descriptors inherited from yahoo.search._Search:

app_id
Application ID (issued by Yahoo), same ass appid
appid
Application ID (issued by Yahoo)
cc_licenses
List of all supported Creative Commons licenses
countries
List of all supported county codes
debug_level
Set and modify the debug level
languages
List of all supported languages
regions
List of all supported region codes
subscriptions
List of all supported premium subscriptions
svc_name
Descriptive name of the service
svc_protocol
Service protocol (e.g. HTTP)
svc_server
Service server name or IP
svc_service
Service path
svc_version
Service version string

Data and other attributes inherited from yahoo.search._Search:

METHOD = 'GET'
PROTOCOL = 'http'
SERVER = 'search.yahooapis.com'
VERSION = 'V1'

Data descriptors inherited from yahoo.search.debug.Debuggable:

__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class SpellingSuggestion(yahoo.search._Search)

   
SpellingSuggestion - perform a Yahoo Web Spelling Suggestion search
 
This class implements the Web Search Spelling Suggestion web service
APIs. The only allowed parameter is:
 
    query        - The query to get spelling suggestions for
    output       - The format for the output result. If json or php is
                   requested, the result is not XML parseable, so we
                   will simply return the "raw" string.
    callback     - The name of the callback function to wrap around
                   the JSON data.
 
 
Full documentation for this service is available at:
 
    http://developer.yahoo.net/web/V1/spellingSuggestion.html 
 

Method resolution order:
SpellingSuggestion
yahoo.search._Search
yahoo.search.debug.Debuggable
__builtin__.object

Data and other attributes defined here:

NAME = 'spellingSuggestion'
SERVICE = 'WebSearchService'

Methods inherited from yahoo.search._Search:

__getattr__(self, name)
__init__(self, app_id, opener=None, xml_parser=None, result_factory=None, debug_level=0, **args)
The app_id is a required argument, the Yahoo search services will
not accept requests without a proper app_id. A valid app_id is a
combination of 8 - 40 characters, matching the regexp
 
    "^[a-zA-Z0-9 _()\[\]*+\-=,.:\\@]{8,40}$"
 
Please visit http://developer.yahoo.net/search/ to request an App ID
for your own software or application.
    
Four optional arguments can also be passed to the constructor:
 
    opener         - Opener for urllib2
    xml_parser     - Function to parse XML (default: minidom)
    result_factory - Result factory class (default: none)
    debug_devel    - Debug level (if any)
 
All other "named" arguments are passed into as a dictionary to the
set_params() method.
 
The result factory is specific to the particular web service used,
e.g. the different Yahoo Search services will each implement their
own factory class.
 
Both of these settings can be controlled via their respective
install method (see below).
__setattr__(self, name, value)
# Implement the attribute handlers, to avoid confusion
encode_params(self)
URL encode the list of parameter values.
get_param(self, param)
Get the value of a query parameter, or the default value if unset
get_results(self, stream=None, xml_parser=None, close=True)
Read the stream (if provided) and either return the raw XML, or
send the data to the provided XML parser for further processing.
If no stream is provided, it will call the open() method using the
default opener. The stream will be closed upon return from this
method, unless the close=False is passed as an argument.
get_url(self, with_params=True)
Return the URL for this request object
get_valid_params(self)
Return a list of all valid parameters for this search
install_opener(self, opener)
Install a URL opener (for use with urllib2), overriding the
default opener. This is rarely required.
install_result_factory(self, result_factory)
Install a python class (not an instance!) that should be used as a
factory for creating result(s) objects.
install_xml_parser(self, xml_parser)
Install an XML parser that will be used for all results for this
object. The parser is expected to "read" the data from the supplied
stream argument. To uninstall the parser (e.g. to make sure we
return raw XML data) simply call this method with an argument of
None.
missing_params(self)
Validate that the search object is propertly setup with all
required parameters etc. This is called automatically before a
search is actually performed, but you can also call it manually
if desired. It will return a list of zero or more paramters that
are missing.
open(self, opener=None, retries=2)
Open a connection to the webservice server, and request the URL.
The return value is a "stream", which can be read calling the
read(), readline() or readlines() methods. If you override this
method, please make sure to call the missing_params() method before
you try to send a request to the Web server.
parse_results(self, xml=None)
Get the result from the request, and instantiate the appropriate
result class. This class will be populated with all the data from
the XML object.
reset(self)
Reset all the parameter values for the object instance.
set_param(self, param, value)
Set the value of a query parameter
set_params(self, args)
Set one or several query parameters from a dictionary

Data descriptors inherited from yahoo.search._Search:

app_id
Application ID (issued by Yahoo), same ass appid
appid
Application ID (issued by Yahoo)
cc_licenses
List of all supported Creative Commons licenses
countries
List of all supported county codes
debug_level
Set and modify the debug level
languages
List of all supported languages
regions
List of all supported region codes
subscriptions
List of all supported premium subscriptions
svc_name
Descriptive name of the service
svc_protocol
Service protocol (e.g. HTTP)
svc_server
Service server name or IP
svc_service
Service path
svc_version
Service version string

Data and other attributes inherited from yahoo.search._Search:

METHOD = 'GET'
PROTOCOL = 'http'
SERVER = 'search.yahooapis.com'
VERSION = 'V1'

Data descriptors inherited from yahoo.search.debug.Debuggable:

__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class WebSearch(yahoo.search._CommonSearch)

   
WebSearch - perform a Yahoo Web Search
 
This class implements the Web Search web service APIs. Allowed
parameters are:
 
    query        - The query to search for (UTF-8 encoded).
    region       - The regional search engine on which the service
                   performs the search. For example, region=uk will give
                   you the search engine at uk.search.yahoo.com.
    type         - The kind of search to submit (all, any or phrase)
                      * all returns results with all query terms.
                      * any resturns results with one or more of the
                        query terms.
                      * phrase returns results containing the query
                        terms as a phrase.
    results      - The number of results to return (1-100).
    start        - The starting result position to return (1-based).
                   The finishing position (start + results - 1) cannot
                   exceed 1000.
    format       - Specifies the kind of web file to search for.
    adult_ok     - The service filters out adult content by default.
                   Enter a 1 to allow adult content.
    similar_ok   - Specifies whether to allow multiple results with
                   similar content. Enter a 1 to allow similar content
    language     - The language the results are written in.
    country      - The country code for the country the website is
                   located in.
    site         - A domain to restrict your searches to (e.g.
                   www.yahoo.com). You may submit up to 30 values
                   (e.g. ["www.yahoo.com", "www.cnn.com"]).
    subscription - Any subscriptions to premium content that should
                   also be searched. You may submit multiple values.
    license      - The Creative Commons license that the contents are
                   licensed under. You may submit multiple values (e.g.
                   [cc_commercial, cc_modifiable] ).
    output       - The format for the output result. If json or php is
                   requested, the result is not XML parseable, so we
                   will simply return the "raw" string.
    callback     - The name of the callback function to wrap around
                   the JSON data.
 
Supported values for 'format' are
 
    html      - Regular HTML / XHTML
    msword    - Microsoft Word
    pdf       - Adobe PDF
    ppt       - Microsoft PowerPoint
    rss       - RSS feed
    txt       - Text file
    xls       - Microsft Excel
 
 
Full documentation for this service is available at:
 
    http://developer.yahoo.net/web/V1/webSearch.html 
 

Method resolution order:
WebSearch
yahoo.search._CommonSearch
yahoo.search._Search
yahoo.search.debug.Debuggable
__builtin__.object

Data and other attributes defined here:

NAME = 'webSearch'
SERVICE = 'WebSearchService'

Methods inherited from yahoo.search._Search:

__getattr__(self, name)
__init__(self, app_id, opener=None, xml_parser=None, result_factory=None, debug_level=0, **args)
The app_id is a required argument, the Yahoo search services will
not accept requests without a proper app_id. A valid app_id is a
combination of 8 - 40 characters, matching the regexp
 
    "^[a-zA-Z0-9 _()\[\]*+\-=,.:\\@]{8,40}$"
 
Please visit http://developer.yahoo.net/search/ to request an App ID
for your own software or application.
    
Four optional arguments can also be passed to the constructor:
 
    opener         - Opener for urllib2
    xml_parser     - Function to parse XML (default: minidom)
    result_factory - Result factory class (default: none)
    debug_devel    - Debug level (if any)
 
All other "named" arguments are passed into as a dictionary to the
set_params() method.
 
The result factory is specific to the particular web service used,
e.g. the different Yahoo Search services will each implement their
own factory class.
 
Both of these settings can be controlled via their respective
install method (see below).
__setattr__(self, name, value)
# Implement the attribute handlers, to avoid confusion
encode_params(self)
URL encode the list of parameter values.
get_param(self, param)
Get the value of a query parameter, or the default value if unset
get_results(self, stream=None, xml_parser=None, close=True)
Read the stream (if provided) and either return the raw XML, or
send the data to the provided XML parser for further processing.
If no stream is provided, it will call the open() method using the
default opener. The stream will be closed upon return from this
method, unless the close=False is passed as an argument.
get_url(self, with_params=True)
Return the URL for this request object
get_valid_params(self)
Return a list of all valid parameters for this search
install_opener(self, opener)
Install a URL opener (for use with urllib2), overriding the
default opener. This is rarely required.
install_result_factory(self, result_factory)
Install a python class (not an instance!) that should be used as a
factory for creating result(s) objects.
install_xml_parser(self, xml_parser)
Install an XML parser that will be used for all results for this
object. The parser is expected to "read" the data from the supplied
stream argument. To uninstall the parser (e.g. to make sure we
return raw XML data) simply call this method with an argument of
None.
missing_params(self)
Validate that the search object is propertly setup with all
required parameters etc. This is called automatically before a
search is actually performed, but you can also call it manually
if desired. It will return a list of zero or more paramters that
are missing.
open(self, opener=None, retries=2)
Open a connection to the webservice server, and request the URL.
The return value is a "stream", which can be read calling the
read(), readline() or readlines() methods. If you override this
method, please make sure to call the missing_params() method before
you try to send a request to the Web server.
parse_results(self, xml=None)
Get the result from the request, and instantiate the appropriate
result class. This class will be populated with all the data from
the XML object.
reset(self)
Reset all the parameter values for the object instance.
set_param(self, param, value)
Set the value of a query parameter
set_params(self, args)
Set one or several query parameters from a dictionary

Data descriptors inherited from yahoo.search._Search:

app_id
Application ID (issued by Yahoo), same ass appid
appid
Application ID (issued by Yahoo)
cc_licenses
List of all supported Creative Commons licenses
countries
List of all supported county codes
debug_level
Set and modify the debug level
languages
List of all supported languages
regions
List of all supported region codes
subscriptions
List of all supported premium subscriptions
svc_name
Descriptive name of the service
svc_protocol
Service protocol (e.g. HTTP)
svc_server
Service server name or IP
svc_service
Service path
svc_version
Service version string

Data and other attributes inherited from yahoo.search._Search:

METHOD = 'GET'
PROTOCOL = 'http'
SERVER = 'search.yahooapis.com'
VERSION = 'V1'

Data descriptors inherited from yahoo.search.debug.Debuggable:

__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Data

       
__author__ = 'Leif Hedstrom <leif@ogre.com>'
__date__ = 'Sun Feb 25 21:47:52 MST 2007'
__revision__ = '$Id: web.py,v 1.10 2007-02-28 05:20:11 zwoop Exp $'
__version__ = '$Revision: 1.10 $'

 
Author

       
Leif Hedstrom <leif@ogre.com>

retrieved