Utility for Research (URes)

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

pip install ures

API reference is generated from source on the documentation site: https://stone-home.github.io/Python-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:

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:

   git clone https://github.com/stone-home/Python-URes.git
   

2. Install the dependencies:

   cd Python-URes
   poetry install
   

3. Run the tests:

   poetry run pytest
   

License

This project is licensed under the MIT License – see the LICENSE file for details.