PqDL

Diese Seite wird nur unregelmäßig aktualisiert, für die allerneuesten Informationen bitte auf blog.leoluk.de nachschauen. Die derzeit aktuelle Version von PqDL ist 0.3.3, der GC.com-Update-Bug ist behoben.
This is the German project site. Click here for an English translation.

Disclaimer und GC.com ToU

Die Nutzungsbedingungen auf geocaching.com lassen sich so interpretieren, dass der Einsatz dieses Tools nicht zulässig ist.

Das Tool verursacht allerdings keinen zusätzlichen Traffic, wartet zwischen den Downloads und tritt ausschließlich auf Wunsch des Benutzers in Aktion.

Man könnte das Starten dieses Programms auch damit vergleichen, auf die Website zu gehen und die Daten manuell herunterzuladen - denn das Programm macht nichts anderes. Abgesehen davon ist es auch kein Spider, der Cachedaten abgreift, und bietet keinen nicht-PMs Zusatzfunktionen. Deshalb sehe ich nicht ein, warum der Einsatz dieses Tools verboten sein könnte.

Seht es so - anstatt eben mit Firefox auf die Seite zu gehen und beispielsweise GTA zu verwenden, verwendet man eben PqDL als Browser. Und abgesehen davon ist man zahlender "Kunde".

Benutzung natürlich auf eigene Gefahr, es ist allerdings kein einziger Fall bekannt, bei dem jemand Ärger bekommen hätte.


Hier klicken um zur Projektseite auf Sourceforge.net zu kommen


Momentane Probleme

Eines der letzten GC.com-Updates hat den Parser von PqDL lahmgelegt.

Ich habe das Problem inzwischen behoben. Bitte unbedingt auf die neueste Version umsteigen! (0.3.3)


PqDL ist ein Open Source-Tool, das es ermöglicht, semi-automatisch Pocket Queries von geocaching.com herunterzuladen, um sie in GSAK weiterzuvearbeiten.

Nach dem neuesten Update auf geocaching.com können Pocket Queries mit mehr als 500 (maximal 1000 Caches) erzeugt werden, aber wenn die 500 überschritten wird, werden sie nicht mehr per Mail versendet. Das Herunterladen der Caches per Hand ist allerdings ein wenig umständlich. Hier findet ihr ein schönes Tutorial, wie man PqDL mit GSAK verwendet (danke!). Danke auch für diesen Artikel.

Deshalb habe ich dieses Tool geschrieben - es verbindet sich zu geocaching.com und lädt die gewünschten Pocket Queries herunter.

Bei Fragen helfe ich gerne:





Screenshot



Dokumentation

Das Programm ist ein Kommandozeilentool, welches sich deshalb perfekt zusammen mit GSAK verwenden lässt (beispielsweise könnte pqdl die PQs in den Temp-Ordner von "pqloader" kopieren, von wo aus sie dann in die GSAK-Datenbank eingelesen werden).

Wenn man -j verwendet, werden schon heruntergeladene PQs nicht erneut geladen, selbst wenn die heruntergeladenen Dateien später gelöscht werden.

Kommandozeilenoptionen

-> PQdl v0.3.1-stable by leoluk. Updates and help on www.leoluk.de/paperless-caching/pqdl

Usage: pqdl.py [-h] -u USERNAME -p PASSWORD [-o OUTPUTDIR] [options] [pq_1 pq_2 ...]

PQdl is a tool that can download Pocket Queries from geocaching.com.  Pocket
Queries that contain more than 500 caches won't be sent per mail, so you  need
to do it by hand or with this script. This script is written by leoluk. Please
look at www.leoluk.de/paperless-caching/pqdl for updates.

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -u USERNAME, --username=USERNAME
                        Username on GC.com (use parentheses if it contains
                        spaces)
  -p PASSWORD, --password=PASSWORD
                        Password on GC.com (use parentheses if it contains
                        spaces), you will be asked if you don't specify it
                        (you can omit this!)
  -o OUTPUTDIR, --outputdir=OUTPUTDIR
                        Output directory for downloaded files (will be created
                        if it doesn't exists yet), will be set as default for
                        other file parameters, sets the working dir [default:
                        D:\Eigene Dateien\Python\pqdl]
  -r, --remove          Remove downloaded files from GC.com. WARNING: This
                        deletes the files ONLINE! WARNING: This is broken from
                        time to time, thanks go to Groundspeak!
  -n, --nospecial       Ignore special Pocket Queries that can't be removed
                        like My Finds.
  -s, --singlefile      Overwrite existing files. When using this option,
                        there won't be any timestamps added! (so just one file
                        for every PQ in your DL folder), applies to unzip too
  -e, --delay           Random delays between the requests
  -l, --list            Do not download anything, just list the files. Best to
                        be used with -d.
  --myfinds             Trigger a My Finds Pocket Query if possible (you'll
                        most likely need to run this program again if the PQ
                        is not generated fast enough, so consider using
                        --myfinds with -l)

  Arguments:
    Pass the names of the Pocket Queries you want to download as
    parameters (pq_1 pq_2 ...). (case sensitive!) If none given, it will
    try to download all of them. You can exlude PQs by adding # on the
    beginning of the name. You need to specify the 'friendly name', the
    name, the date, the cache count or the ID of a PQ. You can use UNIX-
    style wildcards (*, ?, [x], [!x]). Please run with -d -l to get the
    friendly name or other parameters.

  ZIP options:
    PqDL supports unzipping the Pocket Queries. They will be renamed
    automatically after unzipping by this pattern: Name-of-
    PQ_1234567_06-12-2010[_waypoints].gpx (-s will be used). Note: if you
    want to your PQs with GSAK or pqloader, there's no need to unzip them!

    -z, --unzip         Unzips and removes the downloaded ZIP files.
    --keepzip           Do not remove unzipped files. (to be used with -z)

  Debug options:
    They are lots of debug options. You should always use -d if the
    program doesn not exactly does what it's supposed to do, they are lots
    of interesting debug outputs. The other debug options are only needed
    for debugging special problems with the parser. PLEASE ALWAYS USE -d
    IF YOU SEND ME A BUG REPORT!

    -d, --debug         Debug output (RECOMMENDED)
    -t, --httpdebug     HTTP header debug output, used for debugging fake
                        requests
    --httpremovedebug   HTTP 'remove PQ' debug output, used when -r doesn't
                        works
    --ignoreerrors      Ignore version errors
    --httpmaindebug     HTTP 'getPQ' debug output, used for debugging the main
                        parser that gets the PQ site table
    --ctl=CTL           Remove-CTL value, used for debugging very special
                        problems with -r (default: search)

  Journal and map options:
    These are special options that will allow PqDL to remember which PQs
    have already been downloaded. This is based on the PQ latest
    generation date, if the PQ gets generated again, it will be
    downloaded. The journal file is an .ini file (by default
    filestate.txt) that can be used for the mappings too. The section for
    this feature is [Log].

    -j, --journal       Create a download journal file. Files downloaded while
                        using -j there won't be downloaded again (requires -j
                        or --usejournal)
    --usejournal        Like -j, but in read-only mode, it won't add new PQs
                        or pqloader mappings to the journal (-j or this one!)
    --resetjournal      Reset the log section of the journal
    --journalfile=JOURNALFILE
                        Filename of journal file [default: filestate.txt]

  GSAK/pqloader file mappings options:
    This is a feature made for those who use PqDL in conjunction with
    pqloader. pqloader will take the first word in a PQs file name to
    decide in which database the PQs will be saved. This feature allows
    you to add this prefix automatically after downloading the PQs, so you
    don't longer need to rename your PQs online! This feature will use an
    .ini file like -j (this can be the same one, the default is
    filestate.txt too). In order to use this, you need to add a new
    section [Map] to the .ini file and mappings like My-PQ-Name=PQ-Prefix
    (one per line). You can use the name, friendlyname, date or ID, but no
    wildcards yet.

    -m, --mappings      Assign a GSAK Database for pqloader to every PQ,
                        requires journal
    --mapfile           File that contains the mapping section, default is the
                        journal file. [default: filestate.txt, or the custom
                        journal file if set]. For usage examples look at the
                        project site.
    --sep               Seperator for pqloader [default: ' ']

This tool probably violates the Terms of Service by Groundspeak.  Please don't
abuse it. If any argument (username, password, PQ names, ...) contains spaces,
put it into parantheses.

Beispiele

Die Bedienung des Programms sollte selbsterklärend sein.

Wer sehen möchte, was das Programm macht, sollte unbedingt -d verwenden!

Ein Beispielaufruf könnte so aussehen:
pqdl.exe -u leoluk -p mein_passwort
Dieser Aufruf wird alle zur Verfügung stehenden PQs herunterladen und nach einem festen Schema, nämlich name_datum.zip benennen.

pqdl.exe -u "leo luk" -p mein_passwort
Dieser Aufruf wird alle zur Verfügung stehenden PQs herunterladen und nach einem festen Schema, nämlich name_datum.zip benennen. Besonderheit in diesem Fall sind die Anführungszeichen, die Leerzeichen im Namen ermöglichen.

pqdl.exe -u leoluk -p mein_passwort PQ1 PQ2
Dieser Aufruf wird nur die PQs namens "PQ1" und "PQ2" herunterladen und nach einem festen Schema, nämlich name_datum.zip benennen.

pqdl.exe -s -u leoluk -p mein_passwort PQ1 PQ2
Dieser Aufruf wird nur die PQs namens "PQ1" und "PQ2" herunterladen, bei der Benennung allerdings das Datum weglassen.

pqdl.exe -s -d -u leoluk -p mein_passwort Freiburg
Dieser Aufruf wird die PQ "Freiburg" herunterladen und ohne Datum benennen, allerdings noch Debugdaten ausgeben.

pqdl.exe -s -l -d -u leoluk -p mein_passwort Freiburg
Dieser Aufruf wird die PQ "Freiburg" herunterladen und benennen und Debugdaten ausgeben, allerdings dann den Download selber überspringen. (Simulation!)

pqdl.exe -u leoluk -p mein_passwort #PQ1 #PQ2
Dieser Aufruf wird alle PQs außer PQ1 und PQ2 herunterladen.

pqdl.exe -u leoluk -p mein_passwort -n
Dieser Aufruf wird alle normalen PQs herunterladen, aber z.B. die My Finds-PQ weglassen.


pqdl.exe -d -u leoluk -p mein_passwort -n -j

Dieser Aufruf wird alle normalen PQs herunterladen, aber z.B. die My Finds-PQ weglassen. Weiterhin werden Debugausgaben erzeugt und eine Dateichronik angelegt, die verhindert, dass Dateien mehrfach heruntegeladen werden.


pqdl.exe -d -u leoluk -p mein_passwort -n -j -z

Dieser Aufruf wird alle normalen PQs herunterladen, aber z.B. die My Finds-PQ weglassen. Weiterhin werden Debugausgaben erzeugt und eine Dateichronik angelegt, die verhindert, dass Dateien mehrfach heruntegeladen werden. Die heruntergeladenen Dateien werden entzippt und dann gelöscht.

Download

Die aktuellste Version des Tools kann von der Sourceforge-Projektseite heruntergeladen werden.

Bitte nicht anderswo hochladen! (Begründung: das Programm verändert sich sehr oft, und das Letzte was ich brauchen kann sind lauter veraltete Versionen überall verstreut).

Alle gefundenen Fehler bitte melden (siehe unten)!

Changelog

04.06.2010 - Version 0.1.0

  • erstes Release

06.06.2010 - Version 0.2.0

  • kleine Korrekturen bei der Ausgabeformatierung
  • Farben in der Ausgabe entfernt, hat Probleme unter Linux gemacht
  • Probleme mit Sonderzeichen im PQ-Namen behoben
  • Versionsausgabe verbessert
  • Nachricht zu Leerzeichem im Benutzername (in Anführungszeichen setzen!)
  • Erkennung der My Finds-Pocket Query
  • Ausschluss der My Finds-Pocket Query mit dem Parameter -n
  • Möglichkeit, bereits heruntergeladene Dateien auf GC.com zu löschen, damit sie nicht erneut heruntegeladen werden mit der Option -r
  • Möglichkeit, Pocket Queries vom Download auszuschließen, indem man sie als Argument übergibt, aber mit einem # vor dem Namen (nützlich, wenn man alle bis auf einige PQs herunterladen möchte)
  • Erweitertes Debuggen des Löschens von PQs mit der Option --httpremovedebug (die anderen Debugschalter sind -d für Standarddebugging und -t zum HTTP-Header-Debuggen)

06.06.2010 - Version 0.2.1

  • Löschen von Pocket Queries funktioniert jetzt zuverlässiger (bzw. auf anderen Accounts als meinem) dank zusätzlichem Parser, der das Javascript auf der GC.com-Seite simuliert (zum Debuggen dieser Funktion wurde die Option --ctl hinzugefügt)

12.06.2010 - Version 0.2.2

  • Dateichronik hinzugefügt, die verhindert, dass eine PQ erneut heruntergeladen wird; kann über den Schalter -j aktiviert werden, der Datenbank-Dateiname (relativ zu -o) kann mit --journalfile bestimmt und die Datei mit --resetjournal gelöscht und neu erzeugt werden; für nur lesenden Zugriff --usejournal verwenden; die PQs werden anhand ihrer ID identifiziert
  • diverse korrigierte Hilfetexte und (Debug-)Ausgaben
  • Code aufgeräumt
  • Probleme mit alten mechanize-Versionen behoben (danke an Jan!)
  • Debugausgaben für Versionen der Module und Python für -d
  • My Finds-Pocket Query wird intern besser verarbeitet
  • Pausen zwischen einzelnen Anfragen mit -e (zum "Verstecken")
  • Erweitertes Debuggen des Parsens der PQ-Tabelle mit der Option --httpmaindebug

12.06.2010 - Version 0.2.3

  • korrigierte Debug- und Hilfetexte
  • Bugs in der Dateichronik beseitigt
  • automatisches Entzippen der PQs mit -z (die ZIPs werden automatisch gelöscht nach dem Entpacken, um das zu verhindern --keepzip verwenden)
    die Dateien in den ZIPs werden automatisch erkannt und neu benannt (z.B. Name-der-PQ_1234567_06-12-2010_waypoints.gpx)

12.06.2010 - Version 0.2.4

  • verbesserte Sicherheit - das Password muss nicht mehr per Kommandozeile übergeben werden; wenn -p weggelassen wird, wird nach dem Passwort gefragt

18.06.2010 - Version 0.3.0

  • man kann jetzt zusätzlich zum friendlyname auch noch den Namen (in Anführungszeichen falls Leerzeichen!), das Datum der Erzeugung, die Anzahl der Caches oder die ID des Caches als Argumente angeben bzw. mit # ausschließen. Beispiel: Mit 1000 kann man alle PQs herunterladen, die genau 1000 Caches enthalten.
  • für die Argumente können jetzt Wildcards verwendet werden, nach dem UNIX-Standard (* für irgendein Zeichen, ? für ein Zeichen, [...] für Zeichen in der Klammer oder [!...] um das Zeichen auszuschließen
    durch diese Änderungen können jetzt mehrere Argumente als Filter kombiniert werden, mit W* #*x* kann man z.B. alle PQs herunterladen, die mit W beginnen, aber keine, die x enthalten. 
  • erweiterte Unterstützung für pqloader, mit der Option -m kann aus einer Mappings-Datei jeder PQ einen Prefix zuweisen, also die Datenbank wählen; der Name wird dann dem Dateinamen vorangestellt (Trennzeichen kann mit --sep geändert werden)
  • der nur in manchen Fällen auftretende IndexError-Fehler wurde behoben (das Problem waren übrigens noch nicht erzeugte PQs, deshalb verschwindet das Problem nach einer Weile)
  • mit der Option --myfinds kann eine My Finds-PQ angefordert werden, falls verfügbar (um diese herunterzuladen, ist warscheinlich ein erneuter Aufruf von PqDL  erforderlich, falls die PQ nicht schnell genug erzeugt wird)
  • das Passwort kann in der Kommandozeile weggelassen werden, wenn dies passiert, wird danach gefragt (versteckte Eingabe!)
  • besseres Zurücksetzen der Logdatei
  • bessere Verarbeitung der Logdateien
01.08.2010 - Version 0.3.1
  • Bugfix: Update von GC.com hatte den Parser lahmgelegt

Quellcode (Linux/Mac/etc.)plarge

Das Programm ist in Python geschrieben, und der Quellcode ist unter der GPL verfügbar (siehe Projektseite).

Für Windows steht eine Executable zur Verfügung, für den ganzen Rest muss der Quellcode verwendet werden.

Zum Ausführen werden Python 2.6 und die Python-Pakete mechanize, beautifulsoup, termcolor und colorama benötigt.

Am besten direkt die aktuellste Version aus dem SVN verwenden:

svn co https://pqdl.svn.sourceforge.net/svnroot/pqdl/tags/pqdl-v0.1 pqdl-v0.1

Für die aktuellste Entwicklerversion diesen Befehl verwenden: (Achtung! keine Garantie auf Funktionstüchtigkeit!)

svn co https://pqdl.svn.sourceforge.net/svnroot/pqdl/trunk pqdl-trunk

Um den Trunk upzudaten, svn up im Verzeichnis mit dem Quellcode verwenden. Um ein stabiles Release upzudaten, einfach erneut mit svn co https://... auschecken.

Die letzten Änderungen in den stabilen Releases werden im Changelog hier und in den Release Notes auf der Projektseite veröffentlicht. Die letzten Änderungen im Trunk können im SVN-Protokoll abgerufen werden.

Betaversionen

Von Zeit zu Zeit kann es sein, dass ein Feature im Trunk schon ausgereift ist, aber noch nicht wirklich stabil läuft. Dann werde ich eine Betaversion veröffentlichen, die technisch einem stabilen Release gleicht und auch kompiliert zur Verfügung stehen wird, sowie hier im Beta-Changelog erscheinen wird (und natürlich mit Release Notes auf SF.net).

Bugs und Featurevorschläge

Für Fehlerberichte, Vorschläge und anderes einfach das Kontaktformular verwenden (per Mail bevorzugt, Mailadresse steht über dem Formular!) Ich beantworte jede Anfrage :-)

Gerne auch per Chat:



Bugs bitte unbedingt melden und eine Debugausgabe mitschicken! (Option -d, in Härtefällen auch -t, --httpremovedebug oder --httpmaindebug, falls verlangt; ab Version 0.3.2 stattdessen -d und in Härtefällen --loglevel HTTPDEBUG verwenden)
Untergeordnete Seiten (1): PqDL (EN)
Comments