added intro and usage to docs

CHANGES.txt

@@ -0,0 +1,7 @@
+Change Log
+==========
+
+v0.1 (2013-01-05)
+-----------------
+
+* Initial release.

README.rst

@@ -5,3 +5,76 @@ About
 -----
 
 yweather is a Python module that provides an interface to the `Yahoo! Weather RSS feed <http://developer.yahoo.com/weather/>`_.
+
+International Support
+---------------------
+
+::
+
+    >>> client.fetch_woeid("Paris, France")
+    '615702'
+    >>> client.fetch_woeid("Seattle, Washington")
+    '2490383'
+
+Location and weather data is not limited to a single country. Fetch data for any location that is available on Yahoo! Weather.
+
+Different countries use different measurement systems (unfortunately). Fetch data according to United States customary units or the metric system.::
+
+    >>> paris_weather = client.fetch_weather("615702", metric=True)
+    >>> seattle_weather = client.fetch_weather("2490383", metric=False)
+
+Data is Returned as a Dict
+--------------------------
+
+::
+
+    >>> norfolk_weather = client.fetch_weather("2460389")
+    >>> norfolk_weather["astronomy"]["sunrise"]
+    '7:18 am'
+    >>> norfolk_weather["condition"]["text"]
+    'Partly Cloudy'
+
+Weather data is returned as a Python ``dict``, not as an object of a confusing class.
+
+No API Keys or Signup Needed
+----------------------------
+
+Unlike many weather APIs, Yahoo! Weather's RSS feed doesn't require sign ups, API keys, or special authorization to fetch and use their data. All you have to do is follow their `Terms of Use <http://developer.yahoo.com/weather/#terms>`_.
+
+No Manual ID Lookups
+--------------------
+
+::
+
+    >>> client.fetch_woeid("Raleigh, North Carolina")
+    '2478307'
+    >>> client.fetch_lid("2379574")
+    'USIL0228'
+
+yweather doesn't assume you know location identifiers off the top of your head. You can call the ``fetch_woeid`` or ``fetch_lid`` methods to lookup a location's WOEID or LID. WOEID is Yahoo! Weather's location identifier. LID is The Weather Channel's location identifier.
+
+5-day Forecast Support
+----------------------
+
+::
+
+    >>> london_weather = client.fetch_weather("UKXX0085")
+    >>> len(london_weather["forecast"])
+    5
+
+By using a The Weather Channel Location ID (LID), you can fetch a location's 5-day weather forecast. A little warning though -- it's using an undocumented API. If you aren't up for it, you can still get the 2-day forecast using a WOEID.
+
+Documentation
+-------------
+
+yweather includes complete and easy-to-read `documentation <https://yweather.readthedocs.org/>`_. Check it out for a gentle introduction or the full API details.
+
+Bug/Issues Tracker
+------------------
+
+yweather uses its `GitHub Issues page <https://github.com/tsroten/yweather/issues>`_ to track bugs, feature requests, and support questions.
+
+License
+-------
+
+yweather is released under the OSI-approved `MIT License <http://opensource.org/licenses/MIT>`_. See the file LICENSE.txt for more information.

YAHOO_TERMS.txt

@@ -0,0 +1,9 @@
+Yahoo! Weather Terms of Use
+
+The feeds are provided free of charge for use by individuals and non-profit organizations for personal, non-commercial uses. We ask that you provide attribution to Yahoo! Weather in connection with your use of the feeds.
+
+If you provide this attribution in text, please use: "Yahoo! Weather." If you provide this attribution with a graphic, please use the Yahoo! Weather logo that we have included in the feed itself.
+
+We reserve all rights in and to the Yahoo! Weather logo, and your right to use the Yahoo! Weather logo is limited to providing attribution in connection with these RSS feeds.
+
+Yahoo! also reserves the right to require you to cease distributing these feeds at any time for any reason.

docs/_build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 3fd54a863af1193efdfc3582a2fb3a89
+config: f01ae198554471cb0b2fd1c048840a2e
 tags: fbb0d17656682115ca4d033fb2f83ba1

docs/_build/html/_modules/yweather.html

@@ -181,7 +181,14 @@ <h1>Source code for yweather</h1><div class="highlight"><pre>
             <span class="n">link</span> <span class="o">=</span> <span class="n">rss</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;channel/link&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">text</span>
         <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
             <span class="k">return</span> <span class="bp">None</span>
-        <span class="n">lid</span> <span class="o">=</span> <span class="n">link</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&quot;/forecast/&quot;</span><span class="p">)[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&quot;_&quot;</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
+
+        <span class="c"># use regex or string.split</span>
+        <span class="c"># regex assumes the format XXXXNNNN for the LID.</span>
+        <span class="c"># string.split works more general of the context.</span>
+
+        <span class="n">lid</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">&quot;[A-Za-z]{4}[0-9]{4}&quot;</span><span class="p">,</span> <span class="n">link</span><span class="p">)</span><span class="o">.</span><span class="n">group</span><span class="p">()</span>
+        <span class="c"># lid = link.split(&quot;/forecast/&quot;)[1].split(&quot;_&quot;)[0]</span>
+
         <span class="k">return</span> <span class="n">lid</span>
 </div>
 <div class="viewcode-block" id="Client.fetch_weather"><a class="viewcode-back" href="../api.html#yweather.Client.fetch_weather">[docs]</a>    <span class="k">def</span> <span class="nf">fetch_weather</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">,</span> <span class="n">metric</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
@@ -221,6 +228,9 @@ <h1>Source code for yweather</h1><div class="highlight"><pre>
 
         <span class="n">rss</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_fetch_xml</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
 
+        <span class="k">if</span> <span class="n">rss</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">&quot;channel/item/title&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">text</span> <span class="o">==</span> <span class="s">&quot;City not found&quot;</span><span class="p">:</span>
+            <span class="k">return</span> <span class="bp">None</span>
+
         <span class="c"># xml_items details which tags should be read and what their</span>
         <span class="c"># destination dict key should be. These tags don&#39;t appear</span>
         <span class="c"># multiple times.</span>
@@ -264,7 +274,7 @@ <h1>Source code for yweather</h1><div class="highlight"><pre>
                     <span class="n">weather</span><span class="p">[</span><span class="n">meta</span><span class="p">[</span><span class="mi">1</span><span class="p">]]</span> <span class="o">=</span> <span class="bp">None</span>
             <span class="k">else</span><span class="p">:</span>
                 <span class="n">weather</span><span class="p">[</span><span class="n">meta</span><span class="p">[</span><span class="mi">1</span><span class="p">]]</span> <span class="o">=</span> <span class="bp">None</span>
-        
+
         <span class="k">try</span><span class="p">:</span>
             <span class="n">image_url</span> <span class="o">=</span> <span class="n">CONDITION_IMAGE_URL</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">weather</span><span class="p">[</span><span class="s">&quot;condition&quot;</span><span class="p">][</span><span class="s">&quot;code&quot;</span><span class="p">])</span>
             <span class="n">weather</span><span class="p">[</span><span class="s">&quot;condition&quot;</span><span class="p">][</span><span class="s">&quot;image&quot;</span><span class="p">]</span> <span class="o">=</span>  <span class="n">image_url</span>

docs/_build/html/_sources/changes.txt

@@ -0,0 +1 @@
+.. include:: ../CHANGES.txt

docs/_build/html/_sources/glossary.txt

@@ -6,5 +6,11 @@ Glossary
     LID
         Location ID. The Weather Channel uses these to identify locations around the world. Because Yahoo! Weather gets their weather data from The Weather Channel, the Location ID can be used on Yahoo's RSS Feed to gain access to a 5-day weather forecast. Note: this usage is undocumented.
 
+    metric system
+        The metric system is a system of measurement that is used around the world (in all but three countries). It is often considered to be synonymous with the `International System of Units <http://en.wikipedia.org/wiki/International_System_of_Units>`_. Some example units include grams and meters. See `Wikipedia's article <http://en.wikipedia.org/wiki/Metric_system>`_ for more information.
+
+    United States customary units
+        A system of measurements commonly used across the United States. Some example units include miles, pounds, and inches. See `Wikipedia's article <http://en.wikipedia.org/wiki/United_States_customary_units>`_ for more information.
+
     WOEID
         Where On Earth IDentifier. Yahoo! GeoPlanet uses these 32-bit identifiers to reference spatial entities around the world. See `Yahoo! GeoPlanet's Key Concepts <http://developer.yahoo.com/geo/geoplanet/guide/concepts.html#woeids>`_ for more information.

docs/_build/html/_sources/index.txt

@@ -3,11 +3,18 @@ Welcome to yweather's documentation!
 
 :mod:`yweather` is a Python module that provides an interface to the `Yahoo! Weather RSS feed <http://developer.yahoo.com/weather/>`_.
 
-Contents:
+:mod:`yweather` Documentation
+-----------------------------
 
 .. toctree::
    :maxdepth: 2
 
+   intro
+   usage
+   api
+   changes
+   glossary
+
 
 
 Indices and tables

docs/_build/html/_sources/intro.txt

@@ -0,0 +1,67 @@
+Introduction
+============
+
+This is the documentation for :mod:`yweather`. :mod:`yweather` is a Python module that provides an interface to the `Yahoo! Weather RSS feed <http://developer.yahoo.com/weather/>`_
+
+Prerequisites
+-------------
+
+:mod:`yweather` requires Python 2.6, 2.7, or 3 to run.
+
+Installation
+------------
+
+There are multiple ways to install :mod:`yweather`. If you are unsure about which method to use, try ``pip``.
+
+pip (recommended)
+~~~~~~~~~~~~~~~~~
+
+`pip <http://www.pip-installer.org/>`_ is a tool for installing and managing Python packages. To install :mod:`yweather`, run:
+
+.. code-block:: bash
+
+    $ pip install yweather
+
+This will download :mod:`yweather` from `the Python Package Index <http://pypi.python.org/>`_ and install it in your Python's ``site-packages`` directory.
+
+Tarball Release
+~~~~~~~~~~~~~~~
+
+1. Download the most recent release from `yweather's PyPi page <http://pypi.python.org/pypi/yweather/>`_.
+2. Unpack the tarball.
+3. From inside the ``yweather-0.X`` directory, run ``python setup.py install``
+
+This will install :mod:`yweather` in your Python's ``site-packages`` directory.
+
+Install the Development Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`yweather's code <https://github.com/tsroten/yweather>`_ is hosted at GitHub. To install the development version, do the following:
+
+1. Make sure `Git <http://git-scm.org/>`_ is installed. Test if it's installed by running ``git --version``
+2. ``git clone git://github.com/tsroten/yweather.git``
+3. ``pip install -e yweather``
+
+This will link the ``yweather`` directory into your ``site-packages`` directory. You can find out where your ``site-packages`` directory is by running:
+
+.. code-block:: bash
+
+    python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
+
+Basic Usage
+-----------
+
+.. code-block:: python
+
+    >>> import yweather
+    >>> client = yweather.Client()
+    >>> client.fetch_woeid("Oslo, Norway")
+    '862592'
+    >>> oslo_weather = client.fetch_weather("862592")
+    >>> oslo_weather["atmosphere"]["pressure"]
+    '30.24'
+    >>> oslo_weather["condition"]["text"]
+    'Mostly Cloudy'
+
+This code creates a :class:`yweather.Client` instance that allows you to fetch a location's :term:`WOEID` and weather. The weather data is returned as a :class:`dict <python3:dict>`.
+

docs/_build/html/_sources/usage.txt

@@ -0,0 +1,74 @@
+Usage
+=====
+
+Let's learn how to use :mod:`yweather`.
+
+Create a :class:`~yweather.Client` Object
+-----------------------------------------
+
+:mod:`yweather` consists of a single class, :class:`~yweather.Client`.
+
+.. code-block:: python
+
+    >>> import yweather
+    >>> client = yweather.Client()
+
+By creating an instance of :class:`~yweather.Client`, you've created an object that you can use to fetch location identifiers and weather data from Yahoo! Weather.
+
+Fetch a Location's :term:`WOEID`
+--------------------------------
+
+Yahoo! Weather gives every location a unique :term:`WOEID`. In order to fetch weather data from Yahoo!, you must first know the location's :term:`WOEID`.
+
+.. code-block:: python
+
+    >>> client.fetch_woeid("Beijing, China")
+    '2151330'
+    >>> client.fetch_woeid("96734")
+    '12798281'
+    >>> client.fetch_woeid("10 South Main Street, Harrisonburg, VA")
+    '12767058'
+
+You can retrieve a :term:`WOEID` by passing a general or specific address. The above example used city and country, ZIP code, and complete address.
+
+Fetch a Location's Weather
+--------------------------
+
+Once you have a location's :term:`WOEID`, you can use it to fetch the location's weather. Weather data is returned as a :class:`dict <python3:dict>`. Its structure is detailed in :meth:`~yweather.Client.fetch_weather`'s API documentation.
+
+.. code-block:: python
+
+    >>> beijing_weather = client.fetch_weather("2151330")
+    >>> beijing_weather["guid"]
+    'CHXX0008_2013_01_06_7_00_CST'
+    >>> beijing_weather["description"]
+    'Yahoo! Weather for Beijing, CN'
+    >>> beijing_weather["condition"]["temp"]
+    '28'
+
+The returned :class:`dict <python3:dict>` contains metadata along with the weather data itself. By default, :term:`United States customary units` are used, but by changing the *metric* argument, you can receive data according to the :term:`metric system`.
+
+.. code-block:: python
+
+    >>> kailua_weather = client.fetch_weather("12798281", metric=True)
+    >>> kailua_weather["forecast"][0]["high"]
+    '25'
+    >>> kailua_weather["units"]["forecast"]["high"]
+    '°C'
+
+The units used for each data value are accessible with the *units* key.
+
+Using a Location's :term:`LID`
+------------------------------
+
+Because Yahoo! Weather's data comes from `The Weather Channel <http://www.weather.com>`_, weather data is also accessible via a The Weather Channel :term:`LID`. This provides access to a 5-day forecast versus the 2-day forecast available with a location's :term:`WOEID`.
+
+.. code-block:: python
+
+    >>> client.fetch_lid("2151330")
+    'CHXX0008'
+    >>> beijing_weather = client.fetch_weather("CHXX0008")
+    >>> len(beijing_weather["forecast"])
+    5
+
+The :meth:`~yweather.Client.fetch_lid` method takes a :term:`WOEID` and returns a :term:`LID`. You can pass the :term:`LID` to the :meth:`~yweather.Client.fetch_weather` method.

docs/_build/html/_static/searchtools.js

@@ -301,7 +301,7 @@ var Search = {
   },
 
   query : function(query) {
-    var stopwords = ["are","is","in","on","if","of","a","by","that","they","there","with","such","this","it","then","will","or","the","but","be","not","into","and","for","their","no","at","these","as","was","to","near"];
+    var stopwords = ["with","into","such","was","at","as","these","their","and","are","to","not","by","the","then","no","it","be","they","there","will","but","if","near","a","of","for","that","on","or","is","this","in"];
 
     // Stem the searchterms and add them to the correct list
     var stemmer = new Stemmer();

docs/_build/html/api.html

@@ -25,7 +25,9 @@
     <script type="text/javascript" src="_static/jquery.js"></script>
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
-    <link rel="top" title="yweather 0.1 documentation" href="index.html" /> 
+    <link rel="top" title="yweather 0.1 documentation" href="index.html" />
+    <link rel="next" title="Change Log" href="changes.html" />
+    <link rel="prev" title="Usage" href="usage.html" /> 
   </head>
   <body>
     <div class="related">
@@ -37,6 +39,12 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
+        <li class="right" >
+          <a href="changes.html" title="Change Log"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="usage.html" title="Usage"
+             accesskey="P">previous</a> |</li>
         <li><a href="index.html">yweather 0.1 documentation</a> &raquo;</li> 
       </ul>
     </div>  
@@ -456,6 +464,12 @@ <h3>Navigation</h3>
       </div>
       <div class="sphinxsidebar">
         <div class="sphinxsidebarwrapper">
+  <h4>Previous topic</h4>
+  <p class="topless"><a href="usage.html"
+                        title="previous chapter">Usage</a></p>
+  <h4>Next topic</h4>
+  <p class="topless"><a href="changes.html"
+                        title="next chapter">Change Log</a></p>
   <h3>This Page</h3>
   <ul class="this-page-menu">
     <li><a href="_sources/api.txt"
@@ -487,6 +501,12 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
+        <li class="right" >
+          <a href="changes.html" title="Change Log"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="usage.html" title="Usage"
+             >previous</a> |</li>
         <li><a href="index.html">yweather 0.1 documentation</a> &raquo;</li> 
       </ul>
     </div>