Metadata-Version: 2.4
Name: ures
Version: 2.4.0
Summary: Utility library for research and development: Docker workflows, Markdown and Zettelkasten, data structures, and core file/network/string/time helpers.
License: MIT
License-File: LICENSE
Keywords: utilization,Research Tool,Python
Author: stone
Author-email: github@stone-bo.com
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Dist: beautifulsoup4 (>=4.13.4,<5.0.0)
Requires-Dist: bibtexparser (>=2.0.0b8,<3.0.0)
Requires-Dist: docker (>=7.1.0,<8.0.0)
Requires-Dist: onepassword-sdk (>=0.3.1,<0.4.0)
Requires-Dist: pycountry (>=24.6.1,<25.0.0)
Requires-Dist: pydantic (>=2.10.6,<3.0.0)
Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
Requires-Dist: python-frontmatter (>=1.1.0,<2.0.0)
Requires-Dist: requests (>=2.32.5,<3.0.0)
Requires-Dist: sortedcontainers (>=2.4.0,<3.0.0)
Requires-Dist: tqdm (>=4.67.1,<5.0.0)
Requires-Dist: unidecode (>=1.4.0,<2.0.0)
Project-URL: Documentation, https://stone-home.github.io/Python-URes/
Project-URL: Homepage, https://stone-home.github.io/Python-URes/
Project-URL: Repository, https://github.com/stone-home/Python-URes
Description-Content-Type: text/markdown

# Utility for Research (URes)

[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/stone-home/Python-URes)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stone-home/Python-URes/blob/main/LICENSE)
[![Super-Linter](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/linter.yaml)
[![Trufflehog](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/secret-check.yaml)
[![Code Testing](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml/badge.svg)](https://github.com/stone-home/Python-URes/actions/workflows/test.yaml)

---

## Overview

URes (Utility for Research) is a Python library that centralizes **reusable utilities for research and development**. It provides batteries-included helpers for Docker workflows, Markdown and Zettelkasten notes, data structures, filesystem and network tasks, time/date conversion, string manipulation, and more.

## Key Features

- **Docker management**: Build, run, and orchestrate Docker images and containers with structured configuration objects.
- **Markdown & Zettelkasten**: Work with Markdown files and front matter, and manage Zettelkasten-style notes with required metadata.
- **Data structures**: Use tree and bi-directional link structures for organizing and traversing complex data.
- **Core utilities**: File, time/date, string, secrets, and network helpers used across projects.
- **Literature tooling**: Search across literature sources and manage citation data (when those modules are enabled).



## Installation

```bash
pip install ures
```

## Modules

### Docker

The `ures.docker` module provides a high-level interface for managing Docker images and containers.

**Key Features**:

  - Programmatically build Docker images from a `BuildConfig` object.
  - Run containers with detailed runtime configurations using `RuntimeConfig`.
  - Orchestrate the building of multiple images with dependencies using `ImageOrchestrator`.

**Example**:

```python
from ures.docker import Image, BuildConfig, Containers

# Define build configuration
build_config = BuildConfig(
    base_image="python:3.10-slim",
    python_dependencies=["flask", "gunicorn"],
    copies=[{"src": "./app", "dest": "/app"}],
    entrypoint=["gunicorn", "-b", "0.0.0.0:80", "app:app"]
)

# Build the image
image = Image("my-web-app")
image.build_image(build_config, dest=".")

# Run the container
containers = Containers(image)
container = containers.create()
containers.run()
```

### Markdown & Zettelkasten

The `ures.markdown` module offers tools for working with Markdown files, including YAML front matter. The `Zettelkasten` class builds on this for note-taking with structured metadata.

- `MarkdownDocument`: Load, create, and manipulate Markdown files with front matter.
- `Zettelkasten`: Create Zettelkasten notes with required fields such as `title`, `type`, and `tags`.

### Data structures

The `ures.data_structure` module provides reusable data structures:

- `TreeNode`: A tree structure with methods for adding, removing, and traversing nodes.
- `BiDirectional`: A bi-directional linked list for forward and backward traversal.

### Core utilities

- `ures.files`: File system helpers (recursive file listing, filtering by name, listing directories, creating temp folders).
- `ures.timedate`: Time/date conversion helpers (datetimes and Unix timestamps to formatted strings, getting the current time).
- `ures.string`: String utilities such as Zettelkasten-style IDs, unique IDs, memory-size formatting, and capitalization.
- `ures.secrets`: `SecureKeyManager` for managing API keys and other secrets via different storage methods.
- `ures.network`: IP and subnet helpers (validation, containment checks, and IP generation from subnets).

### Literature tooling (optional)

If you use the literature search and citation modules, URes can also help with:

- **Literature search**: Configuration-driven multi-source paper search, with adapters and caching.
- **Literature citation**: Extractors and helpers to manage citation data and apply citation rules.

## Development

To contribute to URes, please follow these steps:

1.  Clone the repository:
    ```bash
    git clone https://github.com/stone-home/Python-URes.git
    ```
2.  Install the dependencies:
    ```bash
    cd Python-URes
    poetry install
    ```
3.  Run the tests:
    ```bash
    poetry run pytest
    ```

## License

This project is licensed under the MIT License – see the [LICENSE](https://github.com/stone-home/Python-URes/blob/main/LICENSE) file for details.

