Metadata-Version: 2.4
Name: alexwlchan-chives
Version: 46
Summary: Utility functions for working with my local media archives
Author-email: Alex Chan <alex@alexwlchan.net>
Maintainer-email: Alex Chan <alex@alexwlchan.net>
License-Expression: MIT
Project-URL: Homepage, https://alexwlchan.net/projects/chives/
Project-URL: Changelog, https://alexwlchan.net/projects/chives/releases/
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: browser-fixtures
Requires-Dist: playwright; extra == "browser-fixtures"
Provides-Extra: fetch
Requires-Dist: certifi; extra == "fetch"
Provides-Extra: media
Requires-Dist: Pillow; extra == "media"
Provides-Extra: static-site-tests
Requires-Dist: pytest; extra == "static-site-tests"
Provides-Extra: urls
Requires-Dist: certifi; extra == "urls"
Dynamic: license-file

# chives

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][static-sites] and use Python scripts to keep everything running smoothly.
This package bundles the common, reusable code I share across multiple archives and sites.

[static-sites]: https://alexwlchan.net/2024/static-websites/

## Features

Here's what chives includes:

-   **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.

## 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:

1.  **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.

2.  **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.

3.  **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 really want the full package, you can install it from PyPI (but pin the version):

```console
$ pip install alexwlchan-chives==42
```

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

## Development and feedback

Want to contribute or tweak something?
Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup instructions.

## License

This project is shared under the [MIT license](./LICENSE).
