markitect-main/capabilities/markitect-utils

MarkiTect Utils Capability

A self-contained capability providing common utility functions for the MarkiTect ecosystem.

Overview

The markitect-utils capability is a test capability created to validate the ComposableRepositoryParadigm process. It provides a collection of commonly used utility functions that can be shared across different MarkiTect capabilities and projects, while serving as a reference implementation for the paradigm.

Features

• String Utilities: Text manipulation and formatting functions
• File Utilities: File path and filesystem operation helpers
• Validation Utilities: Common validation functions for emails, URLs, versions, etc.
• Zero Dependencies: No external dependencies beyond Python standard library
• Comprehensive Testing: Full test coverage with pytest
• Type Hints: Complete type annotations for better development experience

API Reference

String Utilities (markitect_utils.string_utils)

slugify(text: str, separator: str = "-") -> str

Convert a string to a URL-friendly slug.

from markitect_utils import slugify

slug = slugify("Hello World!")  # Returns: "hello-world"
slug = slugify("My Article", "_")  # Returns: "my_article"

truncate(text: str, max_length: int, suffix: str = "...") -> str

Truncate a string to a maximum length with optional suffix.

from markitect_utils import truncate

short = truncate("This is a long string", 10)  # Returns: "This is..."

camel_to_snake(text: str) -> str

Convert camelCase or PascalCase to snake_case.

from markitect_utils import camel_to_snake

snake = camel_to_snake("camelCase")  # Returns: "camel_case"

snake_to_camel(text: str, pascal_case: bool = False) -> str

Convert snake_case to camelCase or PascalCase.

from markitect_utils import snake_to_camel

camel = snake_to_camel("snake_case")  # Returns: "snakeCase"
pascal = snake_to_camel("snake_case", pascal_case=True)  # Returns: "SnakeCase"

strip_ansi_codes(text: str) -> str

Remove ANSI escape sequences from text.

from markitect_utils import strip_ansi_codes

clean = strip_ansi_codes("\\033[31mRed text\\033[0m")  # Returns: "Red text"

File Utilities (markitect_utils.file_utils)

safe_filename(filename: str, replacement: str = "_") -> str

Convert a string to a safe filename by removing unsafe characters.

from markitect_utils import safe_filename

safe = safe_filename("file<name>.txt")  # Returns: "file_name_.txt"

ensure_extension(filename: str, extension: str) -> str

Ensure a filename has the specified extension.

from markitect_utils import ensure_extension

with_ext = ensure_extension("document", ".md")  # Returns: "document.md"

get_file_size(file_path: Union[str, Path]) -> Optional[int]

Get the size of a file in bytes.

from markitect_utils import get_file_size

size = get_file_size("document.txt")  # Returns: file size or None

is_text_file(file_path: Union[str, Path], sample_size: int = 512) -> bool

Check if a file appears to be a text file.

from markitect_utils import is_text_file

is_text = is_text_file("document.txt")  # Returns: True or False

normalize_path(path: Union[str, Path]) -> str

Normalize a file path by resolving relative components.

from markitect_utils import normalize_path

abs_path = normalize_path("./dir/../file.txt")  # Returns: absolute path

Validation Utilities (markitect_utils.validation_utils)

is_valid_email(email: str) -> bool

Check if a string is a valid email address format.

from markitect_utils import is_valid_email

valid = is_valid_email("user@example.com")  # Returns: True

is_valid_url(url: str) -> bool

Check if a string is a valid URL format.

from markitect_utils import is_valid_url

valid = is_valid_url("https://example.com")  # Returns: True

is_valid_semver(version: str) -> bool

Check if a string is a valid semantic version format.

from markitect_utils import is_valid_semver

valid = is_valid_semver("1.0.0")  # Returns: True
valid = is_valid_semver("1.0.0-alpha.1")  # Returns: True

validate_required_fields(data: Dict[str, Any], required_fields: List[str]) -> Dict[str, List[str]]

Validate that required fields are present and not empty.

from markitect_utils import validate_required_fields

data = {"name": "John", "email": "", "age": 30}
result = validate_required_fields(data, ["name", "email", "phone"])
# Returns: {"missing": ["phone"], "empty": ["email"]}

Installation

Install as an editable dependency in your MarkiTect environment:

pip install -e capabilities/markitect-utils/

Or install with development dependencies:

pip install -e "capabilities/markitect-utils/[dev]"

Testing

Run the capability test suite:

cd capabilities/markitect-utils/
pytest tests/

Run with coverage:

cd capabilities/markitect-utils/
pytest tests/ --cov=markitect_utils --cov-report=html

Development

This capability follows standard Python development practices:

1. Code Style: Follow PEP 8 conventions
2. Type Hints: All functions include complete type annotations
3. Documentation: Comprehensive docstrings with examples
4. Testing: Aim for 100% test coverage

ComposableRepositoryParadigm Compliance

This capability serves as a reference implementation and demonstrates compliance with the ComposableRepositoryParadigm:

✅ Structure Requirements

• Src Layout: Uses PEP 660 compliant src/ directory structure
• Consistent Testing: pytest configuration matches main project
• Independent Configuration: Self-contained pyproject.toml
• Documentation: Complete README with API documentation

✅ Dependency Management

• Unidirectional Dependencies: No imports from parent MarkiTect project
• External Dependencies: Minimal external dependencies (none in this case)
• Self-Contained: Can be developed and tested independently

✅ Quality Standards

• Type Safety: Complete type annotations with mypy configuration
• Test Coverage: Comprehensive test suite with unit and integration tests
• Documentation: Detailed API documentation with examples
• Version Management: Semantic versioning starting at 0.1.0-dev

Purpose as Test Capability

This capability was specifically created to validate the ComposableRepositoryParadigm process and serves multiple purposes:

1. Process Validation: Tests the capability creation workflow
2. Structure Template: Provides a reference for future capabilities
3. Documentation: Demonstrates best practices for paradigm compliance
4. Quality Standards: Establishes testing and documentation patterns

Dependencies

This capability intentionally has no external dependencies to keep it simple and demonstrate that useful functionality can be provided with just the Python standard library.

Development dependencies:

• pytest>=7.0.0 (for testing)
• pytest-cov (for coverage reporting)

License

This capability follows the same license as the main MarkiTect project.