Metadata-Version: 2.4
Name: treestamps
Version: 2.3.0
Summary: Create timestamp records for recursive operations on directory trees.
Keywords: timestamps,library,recursive,directory
Author: AJ Slater
Author-email: AJ Slater <aj@slater.net>
License-Expression: GPL-3.0-only
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: ruamel-yaml>=0.19,<=1.0
Requires-Dist: termcolor~=3.0
Requires-Dist: typing-extensions~=4.13
Requires-Python: >=3.10, <4.0
Project-URL: Documentation, https://treestamps.readthedocs.io/
Project-URL: Homepage, https://github.com/ajslater/treestamps
Project-URL: Issues, https://github.com/ajslater/treestamps/issues
Project-URL: News, https://treestamps.readthedocs.io/NEWS/
Project-URL: Source, https://github.com/ajslater/treestamps
Description-Content-Type: text/markdown

# Treestamps

A library to set and retrieve timestamps to speed up operations run recursively
on directory trees.

Documentation is pretty poor.

## 📜 News

Treestamps has a [NEWS file](NEWS.md) to summarize changes that affect users.

## 🕸️ HTML Docs

[HTML formatted docs are available here](https://treestamps.readthedocs.io)

## 🛠️ Use

Used in [picopt](https://github.com/ajsater/picopt) and
[nudebomb](https://github.com/ajsater/nudebomb). You can see how it's used in
those projects.

<!-- eslint-skip -->

```python
    from pathlib import Path
    from treestamps import Grovestamps, GrovestampsConfig

    config = GrovestampsConfig(
        "MyProgramName",
        paths=("/foo", "/bar"),
        program_config={ "option_a": True, "option_b": False}
    )
    gs = Grovestamps(config)

    timestamp = gs[Path("/foo")].get()
    assert None == timestamp.get("file_relative_to_foo.txt")
    mtime = timestamp.set("file_relative_to_foo.txt")
    # mtime ~= now()
    # Also writes to `/foo/.MyProgramName_treestamps.wal.yaml`

    gs.dump()
```

Dumping removes `/foo/.MyProgramName_treestamps.wal.yaml` and writes to
`/foo/.MyProgramName_treestamps.yaml` and `/bar/.MyProgramName_treestamps.yaml`

<!-- eslint-skip -->

```python
    # With similar config to above
    gs = Grovestamps(config)
    # Auto loads timestamps relevant to paths in config.

    timestamp_foo = gs[Path("/foo")].get()
    mtime_b = timestamp_foo.get("file_relative_to_foo.txt")
    mtime_a = timestamp_foo.get("another_file_relative_to_foo.txt")
    # mtime will be the time gs.dump() you called above.
    assert mtime_a == mtime_b

    timestamp_bar = gs[Path("/bar")].get()
    mtime_c = timestamp_foo.get("file_relative_to_bar.txt")
    assert mtime_c == mtime_a
```

## 🛠️ API

There are some autogenerated API docs that might be better than nothing
available in the header of this documentations, but it might just be better to
read the code and look at the example of use in nudebomb.

## 🛠️ Development

Treestamps is hosted at [Github](https://github.com/ajslater/treestamps)
