koneko 0.6

Browse pixiv in the terminal

koneko

Browse pixiv in the terminal using kitty's icat to display images (in the terminal!)

Gallery view Image view Artist search (artist profile picture on the left, 3 previews on right) View artists you're following

Requires kitty on Linux. It uses the magical kitty +kitten icat 'kitten' to display images. For more info see the kitty documentation. Actually, lscat.py uses pixcat, which is a Python API for icat.

Why the name Koneko? Koneko (こねこ) means kitten, which is what icat is, a kitty +kitten

Features

See the manual for more details

1. Artist illustrations gallery (ex)
   • Enter the post's coordinates to open it in image view. Coordinates are in the form xy where x is column and y is row.
   • Next and previous pages
2. Image view (ex)
   • View an image in large resolution
   • Browse through different images in a multi-image post.
3. View artists you are following (ex)
4. Search for an artist (ex)
5. View new illustrations from all the artists you are following (ex)

• Both gallery and image views can:
  • Download an image(PixivUtil would be more suitable for batch download) in full resolution
  • Open post in browser

Rationale

• Terminal user interfaces are minimalist, fast, and doesn't load Javascript that slows down your entire browser or track you
  • Image loading is so much faster, especially if you don't delete the cache

I get 32 trackers on Pixiv. Plus, you have to disable ublock if you ever get logged out

The mobile app even directly tells you Google "and our 198 partners" "collect and use data"! See prompt 1, prompt 2 (Github can't render the images correctly for some reason) and this list

• TUIs make you cool
• TUIs with embedded pictures make you even cooler
• TUIs embedded with pictures of cute anime girls make you the coolest
• Keyboard driven
• Familiar, vim-like key sequences
• I use arch btw

Installation

See also: manual installation

0. Install kitty
1. pip install koneko (or if you use conda...):
2. Run koneko

If it crashes (it shouldn't), it might be because pip didn't 'install' the welcome pictures, and the script failed to download them for some reason. Try:

mkdir -p ~/.local/share/koneko/pics
curl -s https://raw.githubusercontent.com/twenty5151/koneko/master/pics/71471144_p0.png -o ~/.local/share/koneko/pics/71471144_p0.png
curl -s https://raw.githubusercontent.com/twenty5151/koneko/master/pics/79494300_p0.png -o ~/.local/share/koneko/pics/79494300_p0.png

Usage

There are five modes of operation:

1. View artist illustrations (ex)
2. View a post (ex)
3. View the artists that you are following (or any other user ID) (ex)
4. Search for artist/user (ex)
5. View newest illustrations from artists you're following (ex)

Enter digits 1-5 to proceed. If prompted, paste in an appropriate pixiv ID or url. See below for url examples.

Alternatively, you can supply a pixiv url as a command line argument, bypassing the first interactive prompt. The pixiv url must be either the url of the artist's page, or a pixiv post. Example:

koneko https://www.pixiv.net/en/users/2232374 # Mode 1
koneko https://www.pixiv.net/en/artworks/78823485 # Mode 2
koneko f https://www.pixiv.net/en/users/2232374 # Mode 3
koneko "raika9" # Mode 4
koneko 5 # Mode 5

For more details refer to the manual.

Roadmap

• Complete unit tests
• Startup time seems to be slow, but the delay is before the first line even executes. Import time is fast. pip install using the wheel seems to be faster.

Terminal reliability

• Be responsive to terminal sizes, calculate number of columns and stuff, rather than hardcoding it. (1/2)
• Option to use pillow or wand to edit numbers on pics
• Support ueberzug

Features

• For multi-image posts in image view, enter a number to jump to the post's page
• Image view should preview the next few images in multi-image posts (currently experimental feature for first image)

Upcoming changelog (in dev branch)

For full changelogs please see releases

Version 0.7

FAQ

• Pixiv keeps emailing me saying I've logged in, every time I use this app!

That's because cookies aren't stored so you log in everytime with a new session. Looking at PixivUtil's cookie implementation, it would be easier to base this app on PixivUtil for downloads, than to write it myself (currently, it's based on the pixivpy api). The problems with this, other than being a huge time and effort investment, is that koneko uses info from the requests, such as number of pages. I'd like to fix this but I'd rather not use mechanize but I don't know how to do it either way.

• What operating systems does it support?

It supports all OSes that kitty supports, which means Linux and macOS. It should work on macOS, but I don't have a test device. If you do, please contribute!

• What versions of kitty does it support?

It has been successfuly tested on version 0.17.2 onwards

• Why use threading and not asyncio? There's a async version of pixivpy.

If only I can understand how to use asyncio. See I don't understand Python's Asyncio. I only need to do two simple things. Start this function in the background, wait for its result somewhere later, in another function. Then keep the result so I can use it later. Asyncio is impossible to use.

• I'm having problems with lscat

First, koneko is intended to work for full screen terminals, so don't tile it around unless your screen is big enough. Moving and resizing it abruptly will not be good for icat, which is really kitty's problem not mine.

You can also use versions less than v0.5.1, which retains legacy support for the original lsix shell script. Note that I've never really tested it, which is why I decided to be honest and depreciated legacy support from v0.6 onwards.

Contributing

• Fork it
• Edit the files on your fork/branch
  • If your git client complains about committing to master, just remove .pre-commit-config.yaml
• Run tests with pytest testing/ -vvvv -l -s --icat
• Try it with python koneko/main.py, or python setup.py install then koneko to simulate a pip install (or pip install .; check out manual installation)
  • If doing the latter, make sure you aren't running the released version on pypi (totally didn't happen to me).
• Submit a pull request
• If you want to, you can create an issue first. Ask any questions by opening a new issue.
• If you're encountering/fixing a bug and you're stuck, try clearing the cache. For example, a bug might have downloaded to the wrong folder, but after fixing the bug, you need to clear the cache, otherwise it would not download anything and display the wrong contents.

Priorities

(As in, what I think I need help on and what you might want to focus on, not what will only be accepted. All PRs will be considered, regardless if it's important or not)

1. Speed: if it's slower than going to pixiv then half of its purpose is gone
   • The bottleneck is network IO and downloading images from pixiv
2. Reliable rendering: There's no point in browsing a media-heavy site if the terminal is text-only and can't render the images well
   • While it's working perfectly for my use case, it should work well for other reasonable cases (different terminal sizes, number+name for the gallery)

Flowchart of modes and their connections:

Simplified UML diagram of the classes:

Actor-ish model of the ui.Gallery class

Actor-ish model of the ui.Image class

Actor-ish model of the ui.User class

Conda environment

conda create -n koneko
conda activate koneko
conda env list                  # make sure you're in the correct environment...
conda install -n koneko pip     # and make sure pip is installed...
which pip                       # and pip is in your conda directory

# Or use manual installation instructions below
# If you're using a separate conda env, you probably want to make some edits
pip install koneko

# Use anywhere (but only in this conda env):
koneko

# To remove the conda env:
conda remove --name koneko --all

Manual installation

Note: if you want to make some edits, you should install it in a conda environment. See above

# Use the latest stable version (recommended for usage)
# Make sure the version number is the latest
git clone -b 'v0.6' --depth 1 https://github.com/twenty5151/koneko.git
# Use the master branch for upcoming features:
git clone -b master https://github.com/twenty5151/koneko.git
# Use the dev branch for latest features, fixes, and instability (recommended for contributers):
git clone -b dev https://github.com/twenty5151/koneko.git

# Run the tests (for those who want to edit)
pytest testing/ -vvvv -l -s --icat

cd koneko
# Manually install without PyPI; for general usage
# Both will correctly copy the required pictures
pip install .
# or
python setup.py install
# or
# Manually install for development, changes will be immediately reflected
python setup.py develop

# On certain shells with implicit cd, typing `koneko` might cd into the dir
# Instead of running the executable
cd ~
# Use anywhere:
koneko

Unit tests

Run pytest testing/ -vvvv -l -s --icat. If icat fails, skip the three offending tests by omitting the --icat argument

Upload to PyPI

When test installing with pip, don't forget to use pip install . or python setup.py install, not pip install koneko (which will grab from latest stable version). (Yes, I made the same mistake again)

Bump version info in __init__.py, setup.py, and README.md

python setup.py sdist bdist_wheel
twine upload dist/*
pip install koneko --upgrade

Manual

Browse pixiv in the terminal using kitty's icat to display images (in the
terminal!)

Usage:
  koneko       [<link> | <searchstr>]
  koneko [1|a] <link_or_id>
  koneko [2|i] <link_or_id>
  koneko (3|f) <link_or_id>
  koneko [4|s] <searchstr>
  koneko [5|n]
  koneko -h

Notes:
*  If you supply a link and want to go to mode 3, you must give the (3|f) argument,
   otherwise your link would default to mode 1.
*  It is assumed you won't need to search for an artist named '5' or 'n' from the
   command line, because it would go to mode 5.

Optional arguments (for specifying a mode):
  1 a  Mode 1 (Artist gallery)
  2 i  Mode 2 (Image view)
  3 f  Mode 3 (Following artists)
  4 s  Mode 4 (Search for artists)
  5 n  Mode 5 (Newest works from following artists ("illust follow"))

Required arguments if a mode is specified:
  <link>        Pixiv url, auto detect mode. Only works for modes 1, 2, and 4
  <link_or_id>  Either pixiv url or artist ID or image ID
  <searchstr>   String to search for artists

Options:
  -h  Show this help

Artist Gallery commands: (No need to press enter)
    Using coordinates, where {digit1} is the row and {digit2} is the column
    {digit1}{digit2}   -- display the image on row digit1 and column digit2
    o{digit1}{digit2}  -- open pixiv image/post in browser
    d{digit1}{digit2}  -- download image in large resolution

Using image number, where {number} is the nth image in order (see examples)
    i{number}          -- display the image
    O{number}          -- open pixiv image/post in browser.
    D{number}          -- download image in large resolution.

    n                  -- view the next page
    p                  -- view the previous page
    r                  -- delete all cached images, re-download and reload view
    b                  -- go back to previous mode (either 3, 4, 5, or main screen)
    h                  -- show this help
    q                  -- quit (with confirmation)

Examples:
    i09   --->  Display the ninth image in image view (must have leading 0)
    i10   --->  Display the tenth image in image view
    O9    --->  Open the ninth image's post in browser
    D9    --->  Download the ninth image, in large resolution

    25    --->  Display the image on column 2, row 5 (index starts at 1)
    d25   --->  Open the image on column 2, row 5 (index starts at 1) in browser
    o25   --->  Download the image on column 2, row 5 (index starts at 1)

Image view commands (No need to press enter):
    b -- go back to the gallery
    n -- view next image in post (only for posts with multiple pages)
    p -- view previous image in post (same as above)
    d -- download this image
    o -- open pixiv post in browser
    f -- show this image in full resolution

    h -- show keybindings
    m -- show this manual
    q -- quit (with confirmation)

User view commands (No need to press enter):
    {digit1}{digit2}   -- display artist illusts on column digit1 and row digit2
    n                  -- view next page
    p                  -- view previous page
    r                  -- delete all cached images, re-download and reload view
    h                  -- show keybindings
    m                  -- show this manual
    q                  -- quit (with confirmation)

Illust Follow Gallery commands: (No need to press enter)
    Using coordinates, where {digit1} is the row and {digit2} is the column
    {digit1}{digit2}   -- display the image on row digit1 and column digit2
    o{digit1}{digit2}  -- open pixiv image/post in browser
    d{digit1}{digit2}  -- download image in large resolution
    a{digit1}{digit2}  -- view illusts by the artist of the selected image

Using image number, where {number} is the nth image in order (see examples)
    i{number}          -- display the image
    O{number}          -- open pixiv image/post in browser.
    D{number}          -- download image in large resolution.
    A{number}          -- view illusts by the artist of the selected image

    n                  -- view the next page
    p                  -- view the previous page
    r                  -- delete all cached images, re-download and reload view
    b                  -- go back to main screen
    h                  -- show this help
    q                  -- quit (with confirmation)

Examples:
    i09   --->  Display the ninth image in image view (must have leading 0)
    i10   --->  Display the tenth image in image view
    O9    --->  Open the ninth image's post in browser
    D9    --->  Download the ninth image, in large resolution

    25    --->  Display the image on column 2, row 5 (index starts at 1)
    d25   --->  Open the image on column 2, row 5 (index starts at 1) in browser
    o25   --->  Download the image on column 2, row 5 (index starts at 1)

Trackers

Nine trackers in the Android app, according to exodus:

• Amazon Advertisement
• AMoAd
• Google Ads
• Google CrashLytics
• Google DoubleClick
• Google Firebase Analytics
• Integral Ad Science
• Moat
• Twitter MoPub

Advertisers from pixiv's privacy policy:

• Looker
• Repro
• Qualaroo
• DDAI（Date Driven Advertising Initiative）
• YourAdChoices
• Rubicon Project
• i-Mobile Co., Ltd.
• Akinasista Corporation
• Axel Mark Inc.
• AppLovin
• Amazon Japan G.K.
• AmoAd Inc.
• AOL Platforms Japan K.K.
• OpenX
• Google Inc.
• CRITEO K.K.
• CyberAgent, Inc.
• Geniee, Inc.
• Supership Inc.
• GMO AD Marketing Inc.
• F@N Communications, Inc.
• Facebook Inc.
• Fluct, Inc.
• Platform One Inc.
• MicroAd Inc.
• MoPub Inc.
• Yahoo! Japan Corporation
• United, Inc.
• 株式会社Zucks
• PubMatic, Inc.
• Liftoff Mobile, Inc.
• Mobfox US LLC
• OneSignal
• Smaato, Inc.
• SMN株式会社
• 株式会社アドインテ