Initial commit

.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+*.pyc
+*.sqlite
+yyy
+zzz_*

CHANGELOG

@@ -0,0 +1,41 @@
+Changelog
+=========
+
+v2.0.0 (2016-09-09)
+-------------------
+
+#. Completely rewritten, works in PY2 and PY3
+#. Support new Kobo db schema
+
+
+v1.0.5 (2016-09-03)
+-------------------
+
+#. Tested new Kobo DB schema
+
+
+v1.0.4 (2016-06-23)
+-------------------
+
+#. Emergency fix for new Kobo DB schema
+
+
+v1.0.3 (2015-01-23)
+-------------------
+
+#. Added options -l and -b (suggested by Pierre-Arnaud Rabier)
+
+
+v1.0.2 (2013-05-11)
+-------------------
+
+#. Better usage text
+
+
+v1.0.1 (2013-04-30)
+-------------------
+
+#. Initial release
+
+
+

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2016 Alberto Pettarin ([email protected])
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,181 @@
+# export-kobo
+
+A Python tool to export annotations and highlights from a Kobo SQLite file.
+
+* Version: 2.0.0
+* Date: 2016-09-08
+* Developer: [Alberto Pettarin](http://www.albertopettarin.it/)
+* License: the MIT License (MIT)
+* Contact: [click here](http://www.albertopettarin.it/contact.html)
+
+## Usage
+
+```bash
+$ # print all annotations and highlights to stdout
+$ python export-kobo.py KoboReader.sqlite
+
+$ # print the help
+$ python export-kobo.py --help
+
+$ # export to file instead of stdout
+$ python export-kobo.py KoboReader.sqlite --output /path/to/out.txt
+
+$ # export as CSV
+$ python export-kobo.py KoboReader.sqlite --csv
+
+$ # export as CSV to file
+$ python export-kobo.py KoboReader.sqlite --csv --output /path/to/out.csv
+
+$ # export annotations only
+$ python export-kobo.py KoboReader.sqlite --annotations-only
+
+$ # export highlights only
+$ python export-kobo.py KoboReader.sqlite --highlights-only
+
+$ # export as CSV to file annotations only
+$ python export-kobo.py KoboReader.sqlite --csv  --annotations-only --output /path/to/out.txt
+
+$ # print the list of books with annotations or highlights to stdout
+$ python export-kobo.py KoboReader.sqlite --list
+
+$ # as above, but export to file
+$ python export-kobo.py KoboReader.sqlite --list --output /path/to/out.txt
+
+$ # as above, but export in CSV format
+$ python export-kobo.py KoboReader.sqlite --list --csv --output /path/to/out.txt
+
+$ # export annotations and highlights for the book "Alice in Wonderland"
+$ python export-kobo.py KoboReader.sqlite --book "Alice in Wonderland"
+
+$ # as above, assuming "Alice in Wonderland" has ID "12" in the list printed by --list
+$ python export-kobo.py KoboReader.sqlite --bookid 12 
+```
+
+
+## Installation
+
+1. Install Python, 3.x (recommended), or 2.7.x, 
+   and make sure you have the ``python`` command available in your shell;
+
+2. Clone this repository:
+    ```bash
+    $ git clone https://github.com/pettarin/export-kobo
+    ```
+   or manually download the ZIP file from the [Releases tab](https://github.com/pettarin/export-kobo/Releases/) and unzip it somewhere;
+
+3. Enter the directory where ``export-kobo.py`` is:
+    ```bash
+    $ cd export-kobo
+    ```
+
+4. Copy in the same directory the ``KoboReader.sqlite`` file
+   from the ``.kobo/`` hidden directory of the USB drive
+   that appears when you plug your Kobo device to the USB port of your PC.
+   You might need to enable the ``View hidden files`` option
+   in your file manager to see the hidden directory;
+
+5. Now you can run the script as explained above, for example:
+    ```bash
+    $ python export-kobo.py KoboReader.sqlite
+    ```
+
+
+## Troubleshooting
+
+### I am on Windows, and I get this error: ``python is not recognized as an internal or external command, operable program or batch file``
+
+Make sure you installed Python for your current user
+(e.g., check the ``Install for all users`` option in the Python installer),
+and that the directory containing the ``python.exe`` executable
+is in your ``PATH`` environment variable
+(e.g., check the ``Add Python to my PATH`` option in the Python installer).
+
+If you have already installed Python, but it is not in your ``PATH``, see
+[this page](https://docs.python.org/3/using/windows.html)
+for directions to solve this issue.
+
+### I got lots of question marks (``?``) in my output
+
+If you are using Python 2.7.x, try switching to Python 3.x,
+which has saner support for Unicode characters.
+
+You might also want to use the ``--output FILE`` switch
+to output to file instead of printing to standard output.
+
+### I ran the script, but I obtained too much data
+
+If you want to output annotations or highlights for a single book,
+you can use the ``--list`` option to list all books with annotations or highlights,
+and then use ``--book`` or ``--bookid`` to export only those you are interested in:
+
+``` bash
+$ python export-kobo.py KoboReader.sqlite --list
+ID  Title
+1   Alice in Wonderland
+2   Moby Dick
+3   Sonnets
+...
+
+$ python export-kobo.py KoboReader.sqlite --book "Alice in Wonderland"
+...
+$ python export-kobo.py KoboReader.sqlite --bookid 1
+...
+```
+
+Alternatively, you can export to a CSV file with ``--csv --output FILE``
+and then open the resulting output file with a spreadsheet application,
+disregarding the annotations/highlights you are not interested in:
+
+```bash
+$ python export-kobo.py KoboReader.sqlite --csv --output notes.csv
+$ libreoffice notes.csv
+```
+
+### I filtered my notes by book title with ``--book``, but I got no results
+
+Check that you wrote the book title exactly as printed by ``--list``
+(e.g., copy-and-paste it), or use ``--bookid`` instead.
+
+
+## Notes
+
+1. Around May 2016 Kobo changed the schema
+   of their ``KoboReader.sqlite`` database with a firmware update.
+   The ``export-kobo.py`` script in the main directory of this repository
+   works for this **new** database schema.
+   If you still have an old firmware on your Kobo,
+   and hence the old database schema,
+   you might want to use one of the scripts in the ``old/`` directory.
+   Note, however, that those scripts are very old, possibly buggy,
+   and they are no longer supported.
+
+2. Since I no longer use a Kobo eReader,
+   this project is maintained in "legacy mode".
+   Changes to the schema of the ``KoboReader.sqlite`` database
+   can be reflected on the code
+   only thanks to users sending me their ``KoboReader.sqlite`` file,
+   for me to study its schema.
+
+3. Bear in mind that no official specifications are published by Kobo,
+   hence the script works as far as
+   my understanding of the database structure of ``KoboReader.sqlite`` is correct,
+   and its schema remains the same.
+
+4. Although the ``KoboReader.sqlite`` file is opened in read-only mode,
+   it is advisable to make a copy of it on your PC
+   and export your notes from this copy,
+   instead of directly accessing the file on your Kobo eReader device.
+
+
+## Acknowledgments
+
+* Pierre-Arnaud Rabier suggested adding an option to extract the annotations and highlights for a single ebook.
+* Nick Kalogirou and Andrea Moro provided me with theirs KoboReader.sqlite file with the new schema.
+
+
+## License
+
+**export-kobo** is released under the MIT License.
+
+
+

VERSION

@@ -0,0 +1 @@
+2.0.0