===================================================================================================
pycaching - Geocaching for Python
===================================================================================================
Complete documentation can be found at `Read the Docs <http://pycaching.readthedocs.org/>`_.
.. _features:
Features
===================================================================================================
- **login** to Geocaching.com
- **search** caches
- normal search (unlimited number of caches from any point)
- quick search (all caches inside some area) - currently not working, see below
- **get cache** and its details
- normal loading (can load all details)
- quick loading (can load just basic info but very quickly)
- load logbook for given cache
- **get trackable** details by tracking code
- **post log** for a cache or a trackable
- **geocode** given location
.. _installation:
Installation
===================================================================================================
Stable version - using pip:
.. code-block:: bash
pip install pycaching
Dev version - manually from GIT:
.. code-block:: bash
git clone https://github.com/tomasbedrich/pycaching.git
cd pycaching
pip install .
Pycaching has following requirements:
.. code::
Python>=3.5
requests>=2.8
beautifulsoup4>=4.9
geopy>=1.11
Pycaching tests have the following additional requirements:
.. code::
betamax >=0.8, <0.9
betamax-serializers >=0.2, <0.3
Examples
===================================================================================================
Login
---------------------------------------------------------------------------------------------------
Simply call `pycaching.login()
<https://pycaching.readthedocs.io/en/latest/api.html#pycaching.geocaching.Geocaching.login>`__
method and it will do everything for you.
.. code-block:: python
import pycaching
geocaching = pycaching.login("user", "pass")
If you won't provide an username or password, pycaching will try to load ``.gc_credentials`` file
from current directory or home folder. It will try to parse it as JSON and use the keys ``username``
and ``password`` from that file as login credentials.
.. code-block:: json
{ "username": "myusername", "password": "mypassword" }
You can also provide multiple username and password tuples in a file as login credentials.
The tuple to be used can be chosen by providing its username when calling ``pycaching.login()``,
e.g. ``pycaching.login("myusername2")``. The first username and password tuple specified will be
used as default if ``pycaching.login()`` is called without providing a username.
.. code-block:: json
[ { "username": "myusername1", "password": "mypassword1" },
{ "username": "myusername2", "password": "mypassword2" } ]
.. code-block:: python
import pycaching
geocaching = pycaching.login() # assume the .gc_credentials file is presented
In case you have a password manager in place featuring a command line interface
(e.g. `GNU pass <https://www.passwordstore.org/>`__) you may specify a password retrieval command
using the ``password_cmd`` key instead of ``password``.
.. code-block:: json
{ "username": "myusername", "password_cmd": "pass geocaching.com/myUsername" }
Note that the ``password`` and ``password_cmd`` keys are mutually exclusive.
Load a cache details
---------------------------------------------------------------------------------------------------
.. code-block:: python
cache = geocaching.get_cache("GC1PAR2")
print(cache.name) # cache.load() is automatically called
print(cache.location) # stored in cache, printed immediately
This uses lazy loading, so the `Cache <https://pycaching.readthedocs.io/en/latest/api.html#cache>`__
object is created immediately and the page is loaded when needed (accessing the name).
You can use a different method of loading cache details. It will be much faster, but it will load less
details:
.. code-block:: python
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
You can also load a logbook for cache:
.. code-block:: python
for log in cache.load_logbook(limit=200):
print(log.visited, log.type, log.author, log.text)
Or its trackables:
.. code-block:: python
for trackable in cache.load_trackables(limit=5):
print(trackable.name)
Post a log to cache
---------------------------------------------------------------------------------------------------
.. code-block:: python
geocaching.post_log("GC1PAR2", "Found cache in the rain. Nice place, TFTC!")
It is also possible to call ``post_log`` on `Cache
<https://pycaching.readthedocs.io/en/latest/api.html#cache>`__ object, but you would have to create
`Log <https://pycaching.readthedocs.io/en/latest/api.html#log>`__ object manually and pass it to
this method.
Search for all traditional caches around
---------------------------------------------------------------------------------------------------
.. code-block:: python
from pycaching import Point
from pycaching.cache import Type
point = Point(56.25263, 15.26738)
for cache in geocaching.search(point, limit=50):
if cache.type == Type.traditional:
print(cache.name)
Notice the ``limit`` in the search function. It is because `geocaching.search()
<https://pycaching.readthedocs.io/en/latest/api.html#pycaching.geocaching.Geocaching.search>`__
returns a generator object, which would fetch the caches forever in case of a simple loop.
Geocode address and search around
---------------------------------------------------------------------------------------------------
.. code-block:: python
point = geocaching.geocode("Prague")
for cache in geocaching.search(point, limit=10):
print(cache.name)
Find caches in some area
---------------------------------------------------------------------------------------------------
.. code-block:: python
from pycaching import Point, Rectangle
rect = Rectangle(Point(60.15, 24.95), Point(60.17, 25.00))
for cache in geocaching.search_rect(rect):
print(cache.name)
If you want to search in a larger area, you could use the ``limit`` parameter as described above.
Load trackable details
---------------------------------------------------------------------------------------------------
.. code-block:: python
trackable = geocaching.get_trackable("TB3ZGT2")
print(trackable.name, trackable.goal, trackable.description, trackable.location)
Post a log for trackable
---------------------------------------------------------------------------------------------------
.. code-block:: python
from pycaching.log import Log, Type as LogType
import datetime
log = Log(type=LogType.discovered_it, text="Nice TB!", visited=datetime.date.today())
tracking_code = "ABCDEF"
trackable.post_log(log, tracking_code)
Get geocaches by log type
---------------------------------------------------------------------------------------------------
.. code-block:: python
from pycaching.log import Type as LogType
for find in geocaching.my_finds(limit=5):
print(find.name)
for dnf in geocaching.my_dnfs(limit=2):
print(dnf.name)
for note in geocaching.my_logs(LogType.note, limit=6):
print(note.name)
.. _appendix:
Appendix
===================================================================================================
Legal notice
---------------------------------------------------------------------------------------------------
Be sure to read `Geocaching.com's terms of use <http://www.geocaching.com/about/termsofuse.aspx>`__.
By using this piece of software you break them and your Geocaching account may be suspended or *even
deleted*. To prevent this, I recommend you to load the data you really need, nothing more. This
software is provided "as is" and I am not responsible for any damage possibly caused by it.
Inspiration
---------------------------------------------------------------------------------------------------
Original version was inspired by these packages:
- `Geocache Grabber <http://www.cs.auckland.ac.nz/~fuad/geo.py>`__ (by Fuad Tabba)
- `geocaching-py <https://github.com/abbot/geocaching-py>`__ (by Lev Shamardin)
Although the new version was massively rewritten, I'd like to thank to their authors.
Authors
---------------------------------------------------------------------------------------------------
Authors of this project are `all contributors
<https://github.com/tomasbedrich/pycaching/graphs/contributors>`__. Maintainer is `Tomáš Bedřich
<http://tbedrich.cz>`__.
.. _build_status:
|PyPI monthly downloads|
.. |PyPI monthly downloads| image:: http://img.shields.io/pypi/dm/pycaching.svg
:target: https://pypi.python.org/pypi/pycaching
Raw data
{
"_id": null,
"home_page": null,
"name": "pycaching",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": "geocaching, crawler, geocache, cache, search, geocode, travelbug",
"author": null,
"author_email": "Tomas Bedrich <ja@tbedrich.cz>",
"download_url": "https://files.pythonhosted.org/packages/e1/be/5b8b97acb4c7d9eb5ba97bb750be5b0edfc7f516d02de6a15a8600972b00/pycaching-4.4.2.tar.gz",
"platform": null,
"description": "===================================================================================================\npycaching - Geocaching for Python\n===================================================================================================\n\nComplete documentation can be found at `Read the Docs <http://pycaching.readthedocs.org/>`_.\n\n.. _features:\n\nFeatures\n===================================================================================================\n\n- **login** to Geocaching.com\n- **search** caches\n\n - normal search (unlimited number of caches from any point)\n - quick search (all caches inside some area) - currently not working, see below\n\n- **get cache** and its details\n\n - normal loading (can load all details)\n - quick loading (can load just basic info but very quickly)\n - load logbook for given cache\n\n- **get trackable** details by tracking code\n- **post log** for a cache or a trackable\n- **geocode** given location\n\n.. _installation:\n\nInstallation\n===================================================================================================\n\nStable version - using pip:\n\n.. code-block:: bash\n\n pip install pycaching\n\nDev version - manually from GIT:\n\n.. code-block:: bash\n\n git clone https://github.com/tomasbedrich/pycaching.git\n cd pycaching\n pip install .\n\nPycaching has following requirements:\n\n.. code::\n\n Python>=3.5\n requests>=2.8\n beautifulsoup4>=4.9\n geopy>=1.11\n\nPycaching tests have the following additional requirements:\n\n.. code::\n\n betamax >=0.8, <0.9\n betamax-serializers >=0.2, <0.3\n\nExamples\n===================================================================================================\n\nLogin\n---------------------------------------------------------------------------------------------------\n\nSimply call `pycaching.login()\n<https://pycaching.readthedocs.io/en/latest/api.html#pycaching.geocaching.Geocaching.login>`__\nmethod and it will do everything for you.\n\n.. code-block:: python\n\n import pycaching\n geocaching = pycaching.login(\"user\", \"pass\")\n\nIf you won't provide an username or password, pycaching will try to load ``.gc_credentials`` file\nfrom current directory or home folder. It will try to parse it as JSON and use the keys ``username``\nand ``password`` from that file as login credentials.\n\n.. code-block:: json\n\n { \"username\": \"myusername\", \"password\": \"mypassword\" }\n\n\nYou can also provide multiple username and password tuples in a file as login credentials.\nThe tuple to be used can be chosen by providing its username when calling ``pycaching.login()``,\ne.g. ``pycaching.login(\"myusername2\")``. The first username and password tuple specified will be\nused as default if ``pycaching.login()`` is called without providing a username.\n\n.. code-block:: json\n\n [ { \"username\": \"myusername1\", \"password\": \"mypassword1\" },\n { \"username\": \"myusername2\", \"password\": \"mypassword2\" } ]\n\n\n.. code-block:: python\n\n import pycaching\n geocaching = pycaching.login() # assume the .gc_credentials file is presented\n\nIn case you have a password manager in place featuring a command line interface\n(e.g. `GNU pass <https://www.passwordstore.org/>`__) you may specify a password retrieval command\nusing the ``password_cmd`` key instead of ``password``.\n\n.. code-block:: json\n\n { \"username\": \"myusername\", \"password_cmd\": \"pass geocaching.com/myUsername\" }\n\nNote that the ``password`` and ``password_cmd`` keys are mutually exclusive.\n\n\n\nLoad a cache details\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n cache = geocaching.get_cache(\"GC1PAR2\")\n print(cache.name) # cache.load() is automatically called\n print(cache.location) # stored in cache, printed immediately\n\nThis uses lazy loading, so the `Cache <https://pycaching.readthedocs.io/en/latest/api.html#cache>`__\nobject is created immediately and the page is loaded when needed (accessing the name).\n\nYou can use a different method of loading cache details. It will be much faster, but it will load less\ndetails:\n\n.. code-block:: python\n\n cache = geocaching.get_cache(\"GC1PAR2\")\n cache.load_quick() # takes a small while\n print(cache.name) # stored in cache, printed immediately\n print(cache.location) # NOT stored in cache, will trigger full loading\n\nYou can also load a logbook for cache:\n\n.. code-block:: python\n\n for log in cache.load_logbook(limit=200):\n print(log.visited, log.type, log.author, log.text)\n\nOr its trackables:\n\n.. code-block:: python\n\n for trackable in cache.load_trackables(limit=5):\n print(trackable.name)\n\nPost a log to cache\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n geocaching.post_log(\"GC1PAR2\", \"Found cache in the rain. Nice place, TFTC!\")\n\nIt is also possible to call ``post_log`` on `Cache\n<https://pycaching.readthedocs.io/en/latest/api.html#cache>`__ object, but you would have to create\n`Log <https://pycaching.readthedocs.io/en/latest/api.html#log>`__ object manually and pass it to\nthis method.\n\nSearch for all traditional caches around\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n from pycaching import Point\n from pycaching.cache import Type\n\n point = Point(56.25263, 15.26738)\n\n for cache in geocaching.search(point, limit=50):\n if cache.type == Type.traditional:\n print(cache.name)\n\nNotice the ``limit`` in the search function. It is because `geocaching.search()\n<https://pycaching.readthedocs.io/en/latest/api.html#pycaching.geocaching.Geocaching.search>`__\nreturns a generator object, which would fetch the caches forever in case of a simple loop.\n\nGeocode address and search around\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n point = geocaching.geocode(\"Prague\")\n\n for cache in geocaching.search(point, limit=10):\n print(cache.name)\n\nFind caches in some area\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n from pycaching import Point, Rectangle\n\n rect = Rectangle(Point(60.15, 24.95), Point(60.17, 25.00))\n\n for cache in geocaching.search_rect(rect):\n print(cache.name)\n\nIf you want to search in a larger area, you could use the ``limit`` parameter as described above.\n\nLoad trackable details\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n trackable = geocaching.get_trackable(\"TB3ZGT2\")\n print(trackable.name, trackable.goal, trackable.description, trackable.location)\n\n\nPost a log for trackable\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n from pycaching.log import Log, Type as LogType\n import datetime\n\n log = Log(type=LogType.discovered_it, text=\"Nice TB!\", visited=datetime.date.today())\n tracking_code = \"ABCDEF\"\n trackable.post_log(log, tracking_code)\n\nGet geocaches by log type\n---------------------------------------------------------------------------------------------------\n\n.. code-block:: python\n\n from pycaching.log import Type as LogType\n\n for find in geocaching.my_finds(limit=5):\n print(find.name)\n\n for dnf in geocaching.my_dnfs(limit=2):\n print(dnf.name)\n\n for note in geocaching.my_logs(LogType.note, limit=6):\n print(note.name)\n\n\n.. _appendix:\n\nAppendix\n===================================================================================================\n\nLegal notice\n---------------------------------------------------------------------------------------------------\n\nBe sure to read `Geocaching.com's terms of use <http://www.geocaching.com/about/termsofuse.aspx>`__.\nBy using this piece of software you break them and your Geocaching account may be suspended or *even\ndeleted*. To prevent this, I recommend you to load the data you really need, nothing more. This\nsoftware is provided \"as is\" and I am not responsible for any damage possibly caused by it.\n\nInspiration\n---------------------------------------------------------------------------------------------------\n\nOriginal version was inspired by these packages:\n\n- `Geocache Grabber <http://www.cs.auckland.ac.nz/~fuad/geo.py>`__ (by Fuad Tabba)\n- `geocaching-py <https://github.com/abbot/geocaching-py>`__ (by Lev Shamardin)\n\nAlthough the new version was massively rewritten, I'd like to thank to their authors.\n\nAuthors\n---------------------------------------------------------------------------------------------------\n\nAuthors of this project are `all contributors\n<https://github.com/tomasbedrich/pycaching/graphs/contributors>`__. Maintainer is `Tom\u00e1\u0161 Bed\u0159ich\n<http://tbedrich.cz>`__.\n\n.. _build_status:\n\n|PyPI monthly downloads|\n\n.. |PyPI monthly downloads| image:: http://img.shields.io/pypi/dm/pycaching.svg\n :target: https://pypi.python.org/pypi/pycaching\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Geocaching.com site crawler. Provides tools for searching, fetching caches and geocoding.",
"version": "4.4.2",
"project_urls": {
"Documentation": "https://pycaching.readthedocs.io/",
"Source": "https://github.com/tomasbedrich/pycaching"
},
"split_keywords": [
"geocaching",
" crawler",
" geocache",
" cache",
" search",
" geocode",
" travelbug"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9c7c25b5f1a4996fa235413da509a2113b1fbd80272f65ae0fcc3f52fc11e710",
"md5": "39816561f8dbfe6468e4196d44b123e1",
"sha256": "77e4ede079ffc5cb3a24c3bfa9331c720a1e0c33ac95045eaf330db399d4d0f9"
},
"downloads": -1,
"filename": "pycaching-4.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "39816561f8dbfe6468e4196d44b123e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 39758,
"upload_time": "2024-05-20T08:43:02",
"upload_time_iso_8601": "2024-05-20T08:43:02.722091Z",
"url": "https://files.pythonhosted.org/packages/9c/7c/25b5f1a4996fa235413da509a2113b1fbd80272f65ae0fcc3f52fc11e710/pycaching-4.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e1be5b8b97acb4c7d9eb5ba97bb750be5b0edfc7f516d02de6a15a8600972b00",
"md5": "0213c5eada8d91f13993bf06357eca0b",
"sha256": "f557afc49801e6d45b50d3fef95fb9ed4cf02913fe657d3862cb27aa11fd8d8d"
},
"downloads": -1,
"filename": "pycaching-4.4.2.tar.gz",
"has_sig": false,
"md5_digest": "0213c5eada8d91f13993bf06357eca0b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 1633112,
"upload_time": "2024-05-20T08:43:05",
"upload_time_iso_8601": "2024-05-20T08:43:05.220010Z",
"url": "https://files.pythonhosted.org/packages/e1/be/5b8b97acb4c7d9eb5ba97bb750be5b0edfc7f516d02de6a15a8600972b00/pycaching-4.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-20 08:43:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tomasbedrich",
"github_project": "pycaching",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycaching"
}
JSON
