Updated README, added deprecation warning

Author: tomasbedrich

.gitignore

@@ -1,6 +1,9 @@
 # CUSTOM ===========================================================
 
+# script for upload to PIP
 register.sh
+# tmp file for testing some snippets of code
+test.py
 
 
 
@@ -70,4 +73,4 @@ Desktop.ini
 $RECYCLE.BIN/
 
 # Editor
-*.sublime-*
+*.sublime-*

README.rst

@@ -2,27 +2,24 @@
 pycaching - Geocaching for Python
 =================================
 
-A Python 3 interface for working with Geocaching.com website.
-
 --------
 Features
 --------
 
 -  **login** to Geocaching.com
 -  **search** caches
-   
+
    - normal search (unlimited number of caches from any point)
    - quick search (all caches inside some area)
-   
--  **load cache** and its details by WP or URL
+
+-  **load cache** and its details
 
    -  normal loading (loads all details)
    -  quick loading (loads just basic info very quickly)
    -  lazy loading (create cache object and load info on demand)
    -  load logbook for given cache
 
 -  **post log** to cache logbook
-
 -  **load trackable** details by tracking code
 -  **geocode** given location
 
@@ -42,13 +39,15 @@ Dev version - manually from GIT:
 .. code:: bash
 
     git clone https://github.com/tomasbedrich/pycaching.git
+    pip install ./pycaching
 
-Requirements
-~~~~~~~~~~~~
+Pycaching has following requirements:
+
+.. code::
 
--  Python >= 3.4
--  MechanicalSoup >= 0.3.0
--  geopy >= 1.0.0
+  Python>=3.4
+  MechanicalSoup>=0.3.0
+  geopy>=1.0.0
 
 
 -------------
@@ -63,143 +62,100 @@ Login
     import pycaching
     geocaching = pycaching.login("user", "pass")
 
-The above is just shortcut for:
-
-.. code:: python
-
-    from pycaching import Geocaching
-    geocaching = Geocaching()
-    geocaching.login("user", "pass")
-
 Load a cache details
 ~~~~~~~~~~~~~~~~~~~~
 
 .. code:: python
 
-    import pycaching
+    cache = geocaching.get_cache("GC1PAR2")
+    print(cache.name)  # cache.load() is automatically called
+    print(cache.location)  # stored in cache, printed immediately
 
-    geocaching = pycaching.login("user", "pass")
-    cache = geocaching.load_cache("GC1PAR2")
-    print(cache.name)
+This uses lazy loading, so the ``Cache`` object is created immediately and the
+page is loaded when needed (accessing the name).
 
-Using lazy loading:
+You can use different method of loading cache details. It will be much faster,
+but it will load less details:
 
 .. code:: python
 
-    from pycaching import Geocaching, Cache
+    cache = geocaching.get_cache("GC1PAR2")
+    cache.load_quick()  # takes a small while
+    print(cache.name)  # stored in cache, printed immediately
+    print(cache.location)  # NOT stored in cache, will trigger full loading
 
-    geocaching = Geocaching()
-    geocaching.login("user", "pass")
-    cache = Cache("GC1PAR2", geocaching)
-    print(cache.name)
+You can also load a logbook for cache:
 
-The difference is, that ``Cache`` object is created immediately and the
-page is loaded when needed (accessing the name).
+.. code:: python
 
-Post a new log to a cache
-~~~~~~~~~~~~~~~~~~~~~~~~~
+    for log in cache.load_logbook(limit=200):
+        print(log.visited, log.type, log.author, log.text)
 
-:: code:: python
+Or its trackables:
 
-    from pycaching import Geocaching, Cache, Log, enums
-    from datetime import date
+.. code:: python
 
-    geocaching = Geocaching()
-    geocaching.login("user", "pass")
-    cache = Cache("GC1PAR2", geocaching)
+    for trackable in cache.load_trackables(limit=5):
+        print(trackable.name)
 
-    log = Log()
-    log.text = "Found cache in the rain. Nice Place, TFTC!"
-    log.type = enums.LogType.found_it
-    log.visited = date.today
+Post a log to cache
+~~~~~~~~~~~~~~~~~~~
 
-    cache.post_log(log)
+.. code:: python
 
-Find all traditional caches around
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    geocaching.post_log("GC1PAR2", "Found cache in the rain. Nice Place, TFTC!")
 
-Notice the ``limit`` in search function. It is because ``search()``
-returns a generator object, which would fetch the caches forever in case
-of simple loop.
+It is also possible to call post_log on ``Cache`` object, but you would have
+to create ``Log`` object manually and pass it to this method.
+
+Search for all traditional caches around
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: python
 
-    from pycaching import Geocaching, Point, Type
+    from pycaching import Point
+    from pycaching.cache import Type
 
     point = Point(56.25263, 15.26738)
-    geocaching = Geocaching()
-    geocaching.login("user", "pass")
 
     for cache in geocaching.search(point, limit=50):
         if cache.type == Type.traditional:
             print(cache.name)
 
-Find all caches on some adress
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Notice the ``limit`` in search function. It is because ``search()``
+returns a generator object, which would fetch the caches forever in case
+of simple loop.
 
-.. code:: python
+Geocode adress and search around
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    import pycaching
+.. code:: python
 
-    geocaching = pycaching.login("user", "pass")
-    point = geocaching.geocode("10900 Euclid Ave in Cleveland")
+    point = geocaching.geocode("Prague")
 
     for cache in geocaching.search(point, limit=10):
         print(cache.name)
 
-Find approximate location of caches in area
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Find caches with their approximate locations in some area
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: python
 
-    from pycaching import Geocaching, Point, Rectangle
+    from pycaching import Point, Rectangle
 
-    geocaching = pycaching.Geocaching()
-    geocaching.login("user", "pass")
     rect = Rectangle(Point(60.15, 24.95), Point(60.17, 25.00))
 
     for cache in geocaching.search_quick(rect, strict=True):
         print(cache.name, cache.location.precision)
 
 
-Load trackable details
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: python
-
-    import pycaching
-    geocaching = pycaching.login("user", "pass")
-    trackable = geocaching.load_trackable("TB3ZGT2")
-    print(trackable.name, trackable.goal, trackable.description, trackable.location)
-
-
-Find all nearby caches with trackables in them
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: python
-
-    from pycaching import Geocaching, Point
-
-    point = Point(56.25263, 15.26738)
-    geocaching = Geocaching()
-    geocaching.login("user", "pass")
-
-    for cache in geocaching.search(point, limit=50):
-        if len(cache.trackables) > 0:
-            print(cache.name)
-
-
-Load logbook for a cache
+Load a trackable details
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: python
 
-    import pycaching
-
-    geocaching = pycaching.login("user", "pass")
-    cache = geocaching.load_cache("GC1PAR2")
-    for log in cache.load_logbook(limit=200):
-        print(log.visited, log.type, log.author, log.text)
+    trackable = geocaching.get_trackable("TB3ZGT2")
+    print(trackable.name, trackable.goal, trackable.description, trackable.location)
 
 
 --------
@@ -229,10 +185,12 @@ Although the new version was massively rewritten, I'd like to thank to their aut
 Author
 ~~~~~~
 
-| Tomas Bedrich
+| Tomáš Bedřich
 | `tbedrich.cz <http://tbedrich.cz>`__
 | [email protected]
 
+Thanks to `all contributors <https://github.com/tomasbedrich/pycaching/graphs/contributors>`__!
+
 ------------------------------------------------------------------------------------
 
 |Build Status| |Coverage Status| |PyPI monthly downloads|

pycaching/cache.py

@@ -428,13 +428,13 @@ def load_quick(self):
 
         Loads just basic cache details, but very quickly."""
 
-        res = self.geocaching._request("http://tiles01.geocaching.com/map.details",
-                                       params={"i": self.wp}, expect="json")
+        res = self.geocaching._request("http://tiles01.geocaching.com/map.details", params={
+            "i": self.wp
+        }, expect="json")
 
         if res["status"] == "failed" or len(res["data"]) != 1:
-            error_msg = res[
-                "msg"] if "msg" in res else "Unknown error (probably not existing cache)"
-            raise errors.LoadError("Waypoint '{}' cannot be loaded: {}".format(self.wp, error_msg))
+            msg = res["msg"] if "msg" in res else "Unknown error (probably not existing cache)"
+            raise errors.LoadError("Waypoint '{}' cannot be loaded: {}".format(self.wp, msg))
 
         data = res["data"][0]
 
@@ -508,6 +508,9 @@ def load_trackables(self, limit=float("inf")):
         self.trackables = []
 
         url = self.trackable_page_url  # will trigger lazy_loading if needed
+        if not url:
+            # no link to all trackables = no trackables in cache
+            raise StopIteration()
         res = self.geocaching._request(url)
 
         trackable_table = res.find_all("table")[1]

pycaching/geocaching.py

@@ -11,7 +11,7 @@
 from pycaching.geo import Point
 from pycaching.trackable import Trackable
 from pycaching.errors import Error, NotLoggedInException, LoginFailedException
-from pycaching.util import parse_date
+from pycaching.util import parse_date, deprecated
 
 
 class Geocaching(object):
@@ -210,20 +210,30 @@ def search_quick(self, area, *, strict=False, zoom=None):
                     # can yield more caches (which are not exactly in desired area)
                     yield cache
 
-    # add some shortcuts ensure backwards compatibility
+    # add some shortcuts ------------------------------------------------------
 
     def geocode(self, location):
         return Point.from_location(self, location)
 
-    def load_cache(self, wp):
+    def get_cache(self, wp):
         """Return a cache by its WP."""
         return Cache(self, wp)
 
-    def load_trackable(self, tid):
+    def get_trackable(self, tid):
         """Return a cache by its TID."""
         return Trackable(self, tid)
 
     def post_log(self, wp, text, type=LogType.found_it, date=datetime.date.today()):
         """Post log for cache."""
         l = Log(type=type, text=text, visited=date)
-        self.load_cache(wp).post_log(l)
+        self.get_cache(wp).post_log(l)
+
+    #  ensure backwards compatibility -----------------------------------------
+
+    @deprecated
+    def load_cache(self, wp):
+        return self.get_cache(wp)
+
+    @deprecated
+    def load_trackable(self, tid):
+        return self.get_trackable(tid)

pycaching/util.py

@@ -2,6 +2,9 @@
 
 import logging
 import re
+import warnings
+import inspect
+import functools
 from datetime import datetime
 from pycaching import errors
 
@@ -29,6 +32,25 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
+# copied from:
+# https://wiki.python.org/moin/PythonDecoratorLibrary#Generating_Deprecation_Warnings
+def deprecated(func):
+    """This is a decorator which can be used to mark functions
+    as deprecated. It will result in a warning being emitted
+    when the function is used."""
+
+    @functools.wraps(func)
+    def new_func(*args, **kwargs):
+        warnings.warn_explicit(
+            "Call to deprecated function {}.".format(func.__name__),
+            category=FutureWarning,
+            filename=inspect.getfile(func),
+            lineno=inspect.getsourcelines(func)[1] + 1
+        )
+        return func(*args, **kwargs)
+    return new_func
+
+
 def rot13(text):
     """Returns a text encoded by rot13 cipher."""
     return str.translate(text, _rot13codeTable)