236 lines
7.3 KiB
Markdown
236 lines
7.3 KiB
Markdown
# 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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
pip install -e capabilities/markitect-utils/
|
|
```
|
|
|
|
Or install with development dependencies:
|
|
|
|
```bash
|
|
pip install -e "capabilities/markitect-utils/[dev]"
|
|
```
|
|
|
|
## Testing
|
|
|
|
Run the capability test suite:
|
|
|
|
```bash
|
|
cd capabilities/markitect-utils/
|
|
pytest tests/
|
|
```
|
|
|
|
Run with coverage:
|
|
|
|
```bash
|
|
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. |