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 tuple of (paths, num_pages, stale).

  • paths (tuple) - 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().

  • num_pages (int) - the number of webpages to generate.

  • stale (bool) - indicates whether a stale thumbnail was deleted.

Return type

Tuple[Tuple[str, str, str, str], int, bool]

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

find_thumb(album_path, image_root, thumb_dir)

Finds the first available image in a directory.

Parameters

  • album_path (str) – the directory to scan.

  • image_root (str) – the path to thumbnails of images in album_path.

  • thumb_dir (str) – the path to the generated website.

Returns

relative path to an image in album_path if it exists, empty string otherwise.

Return type

str

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

scale_dims(width, height, min_val)

Scales width and height according to min_val.

The smaller out of width and height is assigned a value of min_val, and the other parameter is scaled accordingly.

Parameters

  • width (int) – the width to scale

  • height (int) – the height to scale

  • min_val (int) – the minimum value of width or height

Returns

a tuple containing the scaled width and height

Return type

Tuple[int, int]

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