Metadata-Version: 2.1
Name: smarttitletool
Version: 1.0.0
Summary: A simple tool for flexible smart title case formatting
Author: Khalid Sulaiman Al-Mulaify
Author-email: khalidmfy@gmail.com
Keywords: title case formatter smart title tool string manipulation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# SmartTitleTool: Flexible Smart Title Case Formatter

SmartTitleTool is a Python function designed to transform strings into flexible title case format while excluding specified words from capitalization. This simple yet powerful tool supports various input styles and offers unmatched flexibility for users with diverse formatting needs.

## Features
- Converts strings to a "flexible" title case format.
- Allows exclusions for specific words (e.g., articles, prepositions).
- Handles exclusions provided as:
  - A single word.
  - A list of words.
  - Multiple words as separate arguments.
- Automatically normalizes exclusions to lowercase for consistency.

---

## Importing the Function
```python
from smarttitletool import SmartTitleTool
```

---

## Example Usages

### Example 1: Single exclusion word
```python
formatter = SmartTitleTool("the")
result = formatter.to_smart_title_case("the quick brown fox jumps over the lazy dog")
print(result)  # Output: "The Quick Brown Fox Jumps Over The Lazy Dog"
```

### Example 2: Multiple exclusions as separate arguments
```python
formatter = SmartTitleTool("the", "over", "jumps")
result = formatter.to_smart_title_case("the quick brown fox jumps over the lazy dog")
print(result)  # Output: "The Quick Brown Fox Jumps over the Lazy Dog"
```

### Example 3: Exclusions as a list
```python
formatter = SmartTitleTool(["the", "over", "quick"])
result = formatter.to_smart_title_case("the quick brown fox jumps over the lazy dog")
print(result)  # Output: "The quick Brown Fox Jumps over the Lazy Dog"
```

### Example 4: Combining lists and strings
```python
formatter = SmartTitleTool(["the", "over"], "jumps")
result = formatter.to_smart_title_case("the quick brown fox jumps over the lazy dog")
print(result)  # Output: "The Quick Brown Fox jumps over the Lazy Dog"
```

### Example 5: No exclusions
```python
formatter = SmartTitleTool()
result = formatter.to_smart_title_case("the quick brown fox jumps over the lazy dog")
print(result)  # Output: "The Quick Brown Fox Jumps Over The Lazy Dog"
```

### Example 6: Dynamic word splitting
```python
formatter = SmartTitleTool("brown over quick")
result = formatter.to_smart_title_case("the quick brown fox jumps over the lazy dog")
print(result)  # Output: "The quick brown Fox Jumps over The Lazy Dog"
```

### Example 7: Case insensitivity
```python
formatter = SmartTitleTool("ThE", "OVer", "QUICK")
result = formatter.to_smart_title_case("the quick brown fox jumps over the lazy dog")
print(result)  # Output: "The quick Brown Fox Jumps over the Lazy Dog"
```

### Example 8: First word always capitalized
```python
formatter = SmartTitleTool("the", "and")
result = formatter.to_smart_title_case("and then there was light")
print(result)  # Output: "And Then There Was Light"
```

### Example 9: Single word input
```python
formatter = SmartTitleTool("the")
result = formatter.to_smart_title_case("fox")
print(result)  # Output: "Fox"
```

### Example 10: Empty string input
```python
formatter = SmartTitleTool("the")
result = formatter.to_smart_title_case("")
print(result)  # Output: ""
```

### Example 11: Large input with many exclusions
```python
exclusions = ["the", "over", "and", "a", "of", "in", "to", "on"]
formatter = SmartTitleTool(*exclusions)
text = "the history of art in the renaissance and its impact on society"
result = formatter.to_smart_title_case(text)
print(result)  # Output: "The History of Art in the Renaissance and Its Impact on Society"
```

---

## API Reference

### Function: SmartTitleTool
#### Constructor
```python
SmartTitleTool(*exclusions)
```
- **exclusions** (`str`, `list`, or multiple strings): Words to exclude from capitalization.

#### Method: to_smart_title_case
```python
to_smart_title_case(text)
```
- **text** (`str`): The input string to format.
- **Returns**: A string formatted in flexible title case.

---

## Author
- **Name**: Khalid Sulaiman Al-Mulaify
- **Email**: khalidmfy@gmail.com
- **X Account**: [@Python__Task](https://x.com/Python__Task)

---

## License
This project is licensed under the MIT License.

