SHIS¶

Simple HTTP Image Server (or SHIS for short) is a drop in replacement for python -m http.server, albeit for images. It lets you quickly and conveniently browse through image directories directly in your browser.

Features¶

SHIS is built with speed in mind. Here are some features which help.

Friendly syntax
Instant serving
Multiprocessing support
Efficient resumes
Create thumbnails and previews
Minimal dependencies
Pagination support
Preserve EXIF orientation
Determine Public IP

Friendly syntax ¶

SHIS is meant to be a drop in replacement for http.server, so it’s easier for your brain (and your hands) to remember it’s usage. SHIS follows the same invocation as http.server.

Instant serving ¶

SHIS starts serving webpages even before the thumbnails can be created. This means that you can start browsing the website for images while SHIS is busy creating thumbnails. This is incredibly useful for large directories where processing thumbnails can take a long time.

Multiprocessing support ¶

SHIS uses multiprocessing to take advantage of all cores available on the system. This means that multiple thumbnails can be generated paralelly, which significantly speeds up the entire process.

Efficient resumes ¶

When SHIS is run for the first time, it creates thumbnails for every image in the directory. However, when the next time SHIS is run, it only creates thumbnails for files which have changed. In case SHIS was interrupted in between, it will only create thumbnails for images which haven’t been processed. This means subsequent runs will be significantly faster.

Create thumbnails and previews ¶

SHIS can create both, small size thumbnails and large size previews. This means one can quickly skim through large size previews instead of waiting for the original full size image to load in the browser. To enable large size previews, run SHIS with the --previews flag. SHIS also lets you customize the size of the generated thumbnails and previews using the --thumb-size and --preview-size flags.

Minimal dependencies ¶

SHIS does not depend on a lot of third party modules. It uses Pillow (PIL) to create thumbnails, Jinja2 as the templating language to create HTML pages, and tqdm to display clean progress bars. It uses the built in HTTP Server included with python to serve webpages.

Pagination support ¶

SHIS was designed keeping in mind hundreds (or even thousands) of images per directory. With such quantity, it becomes necessary to split images across multiple pages. SHIS automatically does that for you. By default, SHIS only displays up to 200 items per page. You can customize This using the --pagination flag.

Preserve EXIF orientation ¶

More often than not, the correct orientation of an image is stored in its EXIF data. SHIS will honor the EXIF orientation (if present) in an image and rotate it accordingly. This means you no longer have to worry about rotating images anymore.

Determine Public IP ¶

In a scenario where you’re running SHIS on a remove VM such as EC2, it’s helpful to know the public IP of the server. SHIS tries to determine the public IP of your machine, and displays that address whenever possible. This means you no longer have to remember the public IP of your server.

Usage¶

SHIS provides a number of options that can help you with customizatiion.

usage: shis.server [-h] [--image-dir DIR] [--thumb-dir DIR] [--port PORT]
                   [--pagination ITEMS] [--order ORDER] [--ncpus CPUS] [--clean]
                   [--previews] [--thumb-size SIZE] [--preview-size SIZE]

Named Arguments¶

--image-dir, -d

directory to scan for images (default: current dir)

SHIS will recursively scan this directory and all its subdirectories for image files.

Note

SHIS categorizes a file as an image if the file ends in one of the following extensions:

jpeg, jpg, png, or tiff.

--thumb-dir, -s

directory to store generated content (default: “shis”)

SHIS will store all processed files in this directory, the structure of which is as follows:

shis
├── small
│   ├── image.jpg
│   ..
├── large
│   ..
├── full
│   ├── image.jpg -> ../../image.jpg
│   ..
├── static
│   ├── dir-subdir.html
│   ..
├── html
│   ├── dir-subdir.html
│   ..
└── index.html

Once processing is complete, small shall store small size thumbnails (default: 320px) of every image. If --previews is set, large shall store large size previews (default: 1024px) of every image. If not, then it shall store symlinks to the original image in image_dir. full shall always store symlinks to the original image in image_dir.

The static folder stores Javascript and CSS files required for the website. index.html is the first HTML page of the website. All other HTML pages are stored in html.

--port, -p

port to host the server on (default: 7447)

This is the port on which the generated website shall be served. By default, this is set to 7447 (the T9 keys for shis). If you ever encounter OSError: [Errno 98] Address already in use while running SHIS, this is the option that you should change.

--pagination, -n

number of items to display per page (default: 200)

This is the maximum number of thumbnails displayed in a single page on the website. The rest of the images are distributed across multiple pages.

--order, -o

Possible choices: original, random, name

image listing order: name (default), random, original

This is the order in which images shall be displayed. You can either choose to sort images by their filename, shuffle them in random order, or choose to leave the order untouched.

--ncpus, -j

number of workers to spawn (default: available CPUs)

This is the number of processes that will be spawned simultaneously. One of these processes will be used to run an HTTP Server and the others will be used parallely for the purpose of processing images. By default, SHIS is configured to use all available CPU cores for maximum performance.

--clean, -c

remove existing –thumb-dir (if any) before processing

If thumb_dir already exists, SHIS does not attempt to remove any existing thumbnails from the small, large, or full directories. In fact, SHIS uses this information to only create thumbnails if they haven’t already been created. However, if this option is set, SHIS will clear all contents from thumb_dir and start afresh.

--previews, -f

also generate fullscreen previews (takes more time)

When a user clicks on a thumbnail in the generated website, a full screen preview opens up. By default, this is the original full size image being served. If this option is set, SHIS will explicitly create thumbnails for full screen previews (which will typically be much smaller in size compared to the original full size image) and serve them instead of the original full size image.

--thumb-size

size of generated thumbnails in pixels (default: 256)

This is the size of the thumbnails generated by SHIS. Note that this option also controls the size of the thumbnails displayed on the website.

--preview-size

size of generated previews in pixels (default: 1024)

This is the size of the full screen preview generated by SHIS. Note that the website always displays fullscreen previews.

API Reference¶

shis.server¶

create_templates(args, num_pages)¶

Generate HTML files and corresponding directories for the website.

This function creates static and html directories inside args.thumb_dir. If the directories already exist, they will be cleared before continuing. All static content (JS/CSS) is stored in args.thumb_dir /static and all HTML files (except index.html) are stored in args.thumb_dir /html. The data required to populate Jinja2 templates is obtained from generate_albums().

Parameters

args (argparse.Namespace) – preprocessed command line arguments.
num_pages (int) – number of HTML files (pages) to create.

Return type

None

generate_albums(args)¶

Generate data required to populate Jinja2 templates.

This function generates the correct names and URLs for all thumbnails, albums, breadcrumbs and previews required for populating each HTML page of the website.

Parameters: args (argparse.Namespace) – preprocessed command line arguments.
Returns: a generator which yields data required to populate each page.
Return type: Tuple[Dict, int]

generate_thumbnail(paths, args)¶

Takes paths from process_paths() and generates thumbnail(s).

By default, only one thumbnail of size args.thumb_size is created, while previews are symlinked to the original image. If args.previews is set, previews of args.preview_size will also be created. Download links are always symlinked to the original image.

Parameters

paths (Tuple[str, str, str, str]) – A tuple of paths to process.
args (argparse.Namespace) – preprocessed command line arguments.

main(args)¶

The main script for coordinating shis.

Parameters: args (argparse.Namespace) – command line arguments parsed by argparse.
Return type: None

make_parser()¶

Creates a parser with the specified options.

Returns: a parser with the specified options.
Return type: argparse.ArgumentParser

preprocess_args(args)¶

Preprocess arguments parsed by argparse.

Specifically, this function disambiguates the relative paths supplied for args.image_dir and args.thumb_dir and converts them into absolute paths.

Parameters: args (argparse.Namespace) – command line arguments parsed by argparse.
Returns: preprocessed command line arguments.
Return type: argparse.Namespace

process_paths(args)¶

Generate paths to be processed by generate_thumbnail()

If args.clean is set, all image files within args.image_dir will be included. Else, thumbnails which already exist and are newer than the original image will be fileterd out.

Parameters: args (argparse.Namespace) – preprocessed command line arguments.
Returns: a 4-tuple containing (1) the absolute path of the original image, and the absolute path of the (2) small, (3) large and (4) full size thumbnails to be generated by generate_thumbnail().
Return type: Tuple[Tuple[str, str, str, str], int]

shis.utils¶

chunks(iterable, chunk_size)¶

Yield successive chunk_size sized chunks from iterable.

Parameters

iterable (List[str]) – an iterable to split into chunks.
chunk_size (int) – number of chunks to split iterable into.

Returns

a generator comtaining chunks of iterable.

Return type

Generator[List[str], None, None]

filter_image(name)¶

Checks if a given file name is an image.

Parameters: name (str) – the file name to check.
Returns: True if the file name is an image, False otherwise.
Return type: bool

fixed_width_formatter(width=80)¶

Patch argparse.HelpFormatter to use a fixed width.

Parameters: width (int) – the maximum width of the help and usage text generated.
Returns: a patched instance of the formatter class.
Return type: argparse.HelpFormatter

get_public_ip(host, port)¶

Try to determine the public IP of the server.

Parameters

host (str) – the fallback host to return in case of an error
port (int) – the port to check for public availability

Return type

Tuple[str, int]

rreplace(string, find, replace)¶

Starting from the right, replace the first occurence of find in string with replace.

Parameters

string (str) – the string to search find in.
find (str) – the substring to find in string.
replace (str) – the substring to replace find with.

Returns

the replaced string.

Return type

str

slugify(path)¶

Create a slug given a path.

Essentially, this replaces slashes with dashes.

Parameters: path (str) – the path to slugify.
Returns: the slugified path.
Return type: str

start_httpd(server, address, handler, args)¶

Try to start an HTTPServer, choosing the next available port.

Parameters

server (http.server.HTTPServer) – the server class to execute
address (Tuple[str, int]) – the address to start the server on
handler (http.server.SimpleHTTPRequestHandler) – the request handler to use with the server
args (argparse.Namespace) – preprocessed command line arguments

Return type

http.server.HTTPServer

start_server(args)¶

Start a Simple HTTP Server as a separate thread.

Parameters: args (argparse.Namespace) – preprocessed command line arguments.
Return type: http.server.HTTPServer

urlify(slug, page=1)¶

Create a URL given a slug and a page index.

Parameters

slug (str) – a slug from slugify().
page – an optional page number to include in the url.

Returns

the path of the HTML page described by slug.

Return type

str

Quickstart¶

First, make sure you have shis installed.

$ pip install shis

Next, navigate to a directory containing images.

$ cd directory/containing/images

Finally, run shis.server the same way you’d run http.server

$ python -m shis.server
# Serving HTTP on 0.0.0.0:7447. Press CTRL-C to quit.
# Processing images from : directory/containing/images
# Creating thumbnails in : directory/containing/images/shis
# Generating Website     : 100%|████████████████████|     4/    4 [00:00<00:00,  49.82it/s]
# Generating Thumbnails  : 100%|████████████████████|   300/  300 [00:00<00:00,  1.47kit/s]

There. You should now be able to view the images at http://0.0.0.0:7447/ For more information on advanced usage, please see Usage. For a list of features, please see Features. A live preview is also available at nikhilweee.github.io/shis.