chives

Utility functions for working with my local media archives

chives is a collection of personal helper utilities for managing, validating, and maintaining local media archives.

I store my local media archives as static websites and use Python scripts to keep everything running smoothly. This package bundles the common, reusable code I share across multiple archives and sites.

Features

This repo is a dual-language toolkit with utilities for managing the metadata and rendering the front-end.

The Python library handles:

Media inspection and processing: get information like image dimensions and video duration, and convert subtitle files.
Metadata validation: ensure high-quality metadata by verifying that files in metadata actually exist on disk, and enforcing consistent timestamp formats.
Static site testing: pytest fixtures to check that static sites can be loaded without console or network errors.
HTTP and date utilities: standardised helpers for downloading web pages (for bookmarking/archiving) and handling common date patterns.

The JavaScript components handle front-end UI, including:

Image rendering: render the image entities created by the Python library.

Design goals

My media archives are saved on my personal computer and I want them to last for years (ideally decades), which influences the design of this library:

Human comprehensibility: I want to understand every line of code, so everything is written by hand. I understood it once, which gives me a decent chance of understanding it later.
Minimal dependencies: I keep third-party dependencies to a minimum. This is to reduce my exposure to supply-chain attacks and reduce the risk of dependency rot.
Rock-solid reliable: Everything is fully type-checked and throughly tested. I want this to be a reliable foundation for my media archive.

Versioning and stability

This library is monotonically versioned (releases simply go up sequentially).

I make breaking changes regularly, and I make no promise of compatibility between versions. When I make a breaking change, I update all my local media archives to the latest version immediately and fix the breakage at the same time.

I’ve made this repository public because it’s convenient for my deployment and to contribute to the public corpus of open-source code for everybody to learn from, but expect things to shift around without warning.

Installation and usage

Because this is a personal utility library, I recommend you copy the code: duplicate the relevant functions and tests into your codebase (with a link back to this repo for attribution!). Having your own copy will protect you from disruption caused by my breaking changes.

If you want the Python package, you can install it from PyPI (but pin the version):
```
$ pip install alexwlchan-chives==42
```
If you want the JavaScript files, you have to add them as files in your project.

If you have the Python package installed, you can see a list of available files and install them with the Chives CLI:
```
$ chives-list-js
available 'chives-*.js' files:
chives-image.js

$ chives-write-js chives-image.js
chives-image.js
```
This saves the chives-image.js to your current directory.

You can get the latest JS versions by running:
```
$ chives-update-js
Updating chives-image.js
Updating static/chives-image.js
Successfully updated 1 JavaScript component file(s)!
```
The JavaScript files are not available in npm or other package repositories.

For detailed usage instructions, check the docstrings inside the individual functions.

Development and feedback

Want to contribute or tweak something? Check out CONTRIBUTING.md for local setup instructions.

License

This project is shared under the MIT license.