go-over 0.4.3

Converts Goodreads CSV files to custom desing JSON for jekyll blog consumption.

What is "go over"?

Go over is a python package designed to help manage data for a blog hosted with Jekyll. The package is a CLI suite of tools, which means that it will contain several independent tools. At the moment, though, it has only one (goodreads). Once installed, you can get detailed help by invoking the tool with no parameters.

go-over

Installation

The package is provided as a Pypy installable package. Use pip3 to install it:

pip3 install go-over

As always, it is recommended to use a virtual environment.

go-over tool: goodreads

The first tool provided by go-over is a manager for data exported from Goodreads.com. Goodreads provides a feature to export your library as a CSV. The tool can process that CVS file and generate JSON files to easily consume on using liquid from your jekyll blog.

You will need to pass the CVS file to the tool:

go-over goodreads -g goodreads_library_export.csv

This will generate the files in a folder with name ./results. But call also tell where to generate the resulting files with the -r option:

go-over goodreads -g goodreads_library_export.csv -r _data

Unfortunately, the data coming from Goodreads.com is incomplete or does not contain all the information to customize your blog. Still, no worries, you can easily complement that with your data. To do so, you can provide a complementary JSON file with the -c parameter. If that file is not there, go-over will generate it for you from the data on the original CVS file. Also, you can force the generation of this file at any time with the flag --force_complementary_rewrite or -f. Note that forcing the generation will only override the existing data, but no data will be lost from the complementary file.

The complementary JSON file will have the form:

{
    "books": [
        {
            "id": "17255186",
            "title": "The Phoenix Project: A Novel About IT, DevOps, and Helping Your Business Win",
            "language": "EN",
            "tags": "fiction, devops",
            "format": "audiobook",
            "my_review_url": "/gene-kim-the-phoenix-project/",
            "read_dates": [
                "2021/12/11"
            ],
            "is_favourite": true
        },
    ]
}

Where:

• language: Here, you can specify the language you use to read/listen to the book/audiobook.
• title: Book title. Sometimes the titles coming from the CSV are very long, and here you can shorten them.
• tags: You can add a list of tags to apply to the book.
• format: audiobook/softcover/hardcover
• my_review_url: a partial like to you review of the book in Jekyll.
• read_dates: you might have read multiple times the book, here you can add a list of the dates with the format YYYY/MM/dd. If you set this value to null, the date on the original file will be used, which is the last read's date. Use this field if you have read it multiple times.
• is_favourite: you can mark books as favourites. When favourites exist, a JSON file for the favourites will be generated. Any data provided in the complementary file will override the original CVS file.

You can explore the CLI help of this tool with:

go-over goodreads --help

Setting up the dev environment

I'm using a python virtual environment, and I have exported the configuration to a file called venv_requirements.txt. To start working, follow these steps:

1. On the root folder, create the environment if you do not have it already with: python3 -m venv .venv
2. Start the environment: source .venv/bin/activate
3. Install the requirements: pip install -r requirements.txt
4. Install the local package to edit: pip install -e ./

You should be ready to go!

With that done, you can run the test with pytest. To run the test allowing for prints (not capturing) and inspecting fixtures run: pytest -v -s --setup-show

When you finish, stop the virtual environment with: deactivate

Run with demo data

In the demo/source folder, you will find data to do a demo run and see how it works. To do so, without affecting your environment, follow these steps:

1. (If not done already) Set up the environment python3 -m venv .venv
2. Activate the environment: source .venv/bin/activate
3. (If not done already) Install the requirements: pip install -r requirements.txt
4. Install the local package to edit: pip install -e ./

go-over -v goodreads -g ./demo/source/goodreads_library_export.csv -c ./demo/source/goodreads_complement.json -r ./demo/results

After doing this, in the results folder you will have all the generated files:

> ls -la demo/results/
books_by_tags.json
books_favourites.json
books_read_2011.json
books_read_2018.json
books_read_2019.json
books_read_2020.json
books_read_2021.json
books_read_2022.json
books_read_no_date.json
books_reading.json
books_stats.json
books_to_read.json

Developer note

NOTE: I'm new to python, so any advice on doing this better is highly welcome.