Merge pull request #339 from bear/docs/v3.1_release

v3.1 Release Documentation

Author: jeremylow

doc/changelog.rst

@@ -0,0 +1,43 @@
+Changelog
+---------
+
+Version 3.1
+==========
+
+What's New
+____________
+
+* :py:func:`twitter.api.Api.PostMediaMetadata()` Method allows the posting of alt text (hover text) to a photo on Twitter. Note that it appears that you have to call this method prior to attaching the photo to a status.
+
+* A couple new methods have been added related to showing the connections between two users:
+
+  * :py:func:`twitter.api.Api.ShowFriendship()` shows the connection between two users (i.e., are they following each other?)
+  * :py:func:`twitter.api.Api.IncomingFriendship()` shows all of the authenticated user's pending follower requests (if the user has set their account to private).
+  * :py:func:`twitter.api.Api.OutgoingFriendship()` shows the authenticated user's request to follow other users (i.e. the user has attempted to follow a private account).
+
+* Several methods were added related to muting users:
+
+  * :py:func:`twitter.api.Api.GetMutes()` returns **all** users the currently authenticated user is muting (as ``twitter.models.User`` objects).
+  * :py:func:`twitter.api.Api.GetMutesPaged()` returns a page of ``twitter.models.User`` objects.
+  * :py:func:`twitter.api.Api.GetMutesIDs()` returns **all** of the users the currently authenticated user is muting as integers.
+  * :py:func:`twitter.api.Api.GetMutesIDsPaged()` returns a single page of the users the currently authenticated user is muting as integers.
+
+
+What's Changed
+______________
+
+* :py:func:`twitter.api.Api.GetStatus()` Now accepts the keyword argument ``include_ext_alt_text`` which will request alt text to be included with the Status object being returned (if available). Defaults to ``True``.
+
+* ``[model].__repr__()`` functions have been revised for better Unicode compatibility. If you notice any weirdness, please let us know.
+
+* :py:func:`twitter.api.Api()` no longer accepts the ``shortner`` parameter; however, see ``examples/shorten_url.py`` for an example of how to use a URL shortener with the API.
+
+* :py:func:`twitter.api.Api._Encode()` and :py:func:`twitter.api.Api._EncodePostData()` have both been refactored out of the API.
+
+* :py:class:`twitter.models.Media` now has an attribute ``ext_alt_text`` for alt (hover) text for images posted to Twitter.
+
+* :py:class:`twitter.models.Status` no longer has the properties ``relative_created_at``, ``now``, or ``Now``. If you require a relative time, we suggest using a third-party library.
+
+* Updated examples, specifically ``examples/twitter-to-xhtml.py``, ``examples/view_friends.py``, ``examples/shorten_url.py``
+
+* Updated ``get_access_token.py`` script to be python3 compatible.

doc/conf.py

@@ -57,9 +57,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.0rc1'
+version = '3.1'
 # The full version, including alpha/beta/rc tags.
-release = '3.0rc1'
+release = '3.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/index.rst

@@ -16,6 +16,7 @@ Contents:
    getting_started.rst
    contributing.rst
    migration_v30.rst
+   changelog.rst
    rate_limits.rst
    models.rst
    searching.rst

doc/models.rst

@@ -3,14 +3,13 @@ Models
 
 Python-twitter provides the following models of the objects returned by the Twitter API:
 
-* :py:mod:`twitter.category.Category`
-* :py:mod:`twitter.direct_message.DirectMessage`
-* :py:mod:`twitter.hashtag.Hashtag`
-* :py:mod:`twitter.list.List`
-* :py:mod:`twitter.media.Media`
-* :py:mod:`twitter.status.Status`
-* :py:mod:`twitter.trend.Trend`
-* :py:mod:`twitter.url.Url`
-* :py:mod:`twitter.user.User`
-* :py:mod:`twitter.user.UserStatus`
-
+* :py:class:`twitter.models.Category`
+* :py:class:`twitter.models.DirectMessage`
+* :py:class:`twitter.models.Hashtag`
+* :py:class:`twitter.models.List`
+* :py:class:`twitter.models.Media`
+* :py:class:`twitter.models.Status`
+* :py:class:`twitter.models.Trend`
+* :py:class:`twitter.models.Url`
+* :py:class:`twitter.models.User`
+* :py:class:`twitter.models.UserStatus`

doc/searching.rst

@@ -9,10 +9,11 @@ Searching
 Raw Queries
 ===========
 
-To the Api.GetSearch() method, you can pass the parameter ``raw_query``, which should be the query string you wish to use for the search **omitting the leading "?"**. This will override every other parameter. Twitter's search parameters are quite complex, so if you have a need for a very particular search, you can find Twitter's documentation at https://dev.twitter.com/rest/public/search.
+To the ``Api.GetSearch()`` method, you can pass the parameter ``raw_query``, which should be the query string you wish to use for the search **omitting the leading "?"**. This will override every other parameter. Twitter's search parameters are quite complex, so if you have a need for a very particular search, you can find Twitter's documentation at https://dev.twitter.com/rest/public/search.
 
 For example, if you want to search for only tweets containing the word "twitter", then you could do the following: ::
 
-    results = api.GetSearch(raw_query="q=twitter%20&result_type=recent&since=2014-07-19&count=100")
+    results = api.GetSearch(
+        raw_query="q=twitter%20&result_type=recent&since=2014-07-19&count=100")
 
-If you want to build a search query and you're not quite sure how it should look all put together, you can use Twitter's Advanced Search tool: https://twitter.com/search-advanced, and then use the part of search URL after the "?" to use for the Api, removing the ``&src=typd`` portion.
+If you want to build a search query and you're not quite sure how it should look all put together, you can use Twitter's Advanced Search tool: https://twitter.com/search-advanced, and then use the part of search URL after the "?" to use for the Api, removing the ``&src=typd`` portion.

doc/twitter.rst

@@ -13,27 +13,7 @@ API
 Models
 ---------------------
 
-.. automodule:: twitter.category
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: twitter.direct_message
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: twitter.hashtag
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: twitter.list
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: twitter.media
+.. automodule:: twitter.models
     :members:
     :undoc-members:
     :show-inheritance:
@@ -43,26 +23,6 @@ Models
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: twitter.status
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: twitter.trend
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: twitter.url
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. automodule:: twitter.user
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 
 Utilities
 ---------------------

requirements.docs.txt

@@ -2,3 +2,4 @@ future>=0.15.2
 requests>=2.9.1
 requests-oauthlib>=0.6.1
 sphinx>=1.3.6
+sphinx_rtd_theme

twitter/__init__.py

@@ -23,7 +23,7 @@
 __email__        = '[email protected]'
 __copyright__    = 'Copyright (c) 2007-2016 The Python-Twitter Developers'
 __license__      = 'Apache License 2.0'
-__version__      = '3.0rc1'
+__version__      = '3.1'
 __url__          = 'https://github.com/bear/python-twitter'
 __download_url__ = 'https://pypi.python.org/pypi/python-twitter'
 __description__  = 'A Python wrapper around the Twitter API'