Metadata-Version: 2.3
Name: ures
Version: 2.1.0
Summary: The project is designed to provide standard utilization functions for improving the reusability of frequently used functions.
License: MIT
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 :: 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: 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/semantic-release/semantic-release)
[![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://opensource.org/licenses/MIT)
[![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 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

```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

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

```python
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:
    ```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://www.google.com/search?q=LICENSE) file for details.

