ures 2.3.0

The project is designed to provide standard utilization functions for improving the reusability of frequently used functions.

Utility for Research (URes)

---

Overview

URes (Utility for Research) is a versatile Python library that simplifies common research and development tasks. It offers a wide range of modules to handle everything from Docker container management to advanced data visualization and file operations.

Key Features

• Docker Management: Build, run, and manage Docker images and containers with an intuitive Python interface.
• Markdown and Zettelkasten: Create, manipulate, and organize Markdown documents, with support for the Zettelkasten note-taking method.
• Data Structures: Implement and use advanced data structures like Trees and Bi-Directional Links for complex data organization.
• File and Network Utilities: Simplify file system operations and network-related tasks with a collection of helper functions.
• Time and Date Converters: Easily convert between different time and date formats, including ISO 8601 and Unix timestamps.
• String Manipulation: A set of functions for common string operations, such as capitalization and unique ID generation.
• Advanced Plotting: A comprehensive, multi-backend visualization library for scientific research, data analysis, and machine learning.

Installation

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:

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

The ures.markdown module offers tools for working with Markdown files, including those with YAML front matter. The Zettelkasten class extends this functionality for note-taking.

Key Features:

• Load, create, and manipulate Markdown files with MarkdownDocument.
• Manage YAML front matter with support for nested keys.
• Implement the Zettelkasten method with the Zettelkasten class, which includes mandatory metadata fields like title, type, and tags.

Example:

from ures.markdown import Zettelkasten

# Create a new Zettelkasten note
note = Zettelkasten(
    title="My Research Note",
    n_type="permanent",
    tags=["research", "python"],
    aliases=["research-note"]
)

# Add content
note.add_content("This is a sample research note.")

# Save to file
note.save("my_note.md")

Data Structures

The ures.data_structure module provides implementations of advanced data structures.

• TreeNode: A tree data structure with methods for adding, removing, and traversing nodes.
• BiDirectional: A bi-directional linked list that allows for easy traversal in both forward and backward directions.

File and Network Utilities

• ures.files: A collection of functions for file system operations, such as recursively getting file paths, filtering files, and managing temporary directories.
• ures.network: Helper functions for network-related tasks, including IP address validation and generation.

Time and Date Converters

The ures.timedate module provides functions for converting between different time and date formats.

• datetime_converter(): Converts a datetime object to a formatted string (ISO 8601 or custom).
• timestamp_converter(): Converts a Unix timestamp to a formatted string.
• time_now(): Returns the current time as a formatted string.

String Manipulation

The ures.string module offers a variety of string utility functions.

• zettelkasten_id(): Generates a unique ID suitable for Zettelkasten notes.
• unique_id(): Creates a standard unique identifier.
• format_memory(): Formats a memory size into a human-readable string.
• capitalize_string(): Capitalizes each word in a string.

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.