stringz 0.1.1__py3-none-any.whl

stringz/__init__.py

@@ -0,0 +1 @@
+from ._truncated_string import TStr, trunc_str  # noqa

stringz/_truncated_string.py

@@ -0,0 +1,163 @@
+from typing import Self, SupportsIndex
+
+
+def trunc_str(
+    text: str,
+    max_chars: int,
+    placeholder: str = "...",
+) -> str:
+    """A function that truncates a string to a maximum number of characters,
+    appending a placeholder if truncation occurs.
+
+    Example:
+        Basic usage:
+
+        >>> from stringz import trunc_str
+        >>> trunc_str("hello world", max_chars=10)
+        'hello w...'
+
+        No truncation needed:
+
+        >>> trunc_str("short", max_chars=10)
+        'short'
+
+        Custom placeholder:
+
+        >>> trunc_str("hello world", max_chars=10, placeholder=">>")
+        'hello wo>>'
+
+        Empty placeholder:
+
+        >>> trunc_str("hello world", max_chars=5, placeholder="")
+        'hello'
+
+    Args:
+        text: The string to be truncated.
+        max_chars: The maximum number of characters allowed in the output string.
+        placeholder: The string to append if truncation occurs. Default is '...'.
+
+    Returns:
+        The truncated string, if necessary, with the placeholder appended.
+
+    Raises:
+        TypeError: If text is not a string.
+        ValueError: If max_chars is not a positive integer or if placeholder length is greater than or
+            equal to max_chars.
+        TypeError: If placeholder is not a string.
+        ValueError: If placeholder length is greater than or equal to max_chars.
+    """
+
+    # ====> VALIDATION
+    if not isinstance(text, str):
+        _err: str = f"text must be a string, not {type(text).__name__}"
+        raise TypeError(_err)
+    if not isinstance(max_chars, int) or max_chars <= 0:
+        _err: str = f"max_chars must be a positive integer, got {max_chars}"
+        raise ValueError(_err)
+    if not isinstance(placeholder, str):
+        _err: str = f"placeholder must be a string, not {type(placeholder).__name__}"
+        raise TypeError(_err)
+    if len(placeholder) >= max_chars:
+        _err: str = f"placeholder length ({len(placeholder)}) must be smaller than max_chars ({max_chars})"
+        raise ValueError(_err)
+
+    # ====> TRUNCATE
+    if len(text) <= max_chars:
+        return text
+    return text[: max_chars - len(placeholder)] + placeholder
+
+
+class TStr(str):
+    """A string subclass that automatically truncates its content to a maximum length when created or modified through
+    string operations. The TStr class uses the `trunc_str` function for truncation under the hood.
+
+    Example:
+        Basic creation:
+
+        >>> from stringz import TStr
+        >>> s = TStr("hello world", max_chars=10)
+        >>> print(s)
+        hello w...
+        >>> len(s)
+        10
+
+        String operations maintain TStr type and truncation:
+
+        >>> s1 = TStr("hello", max_chars=10)
+        >>> s2 = s1 + " world"
+        >>> type(s2)
+        <class 'stringz._truncated_string.TStr'>
+        >>> print(s2)
+        hello w...
+    """
+
+    __slots__ = (
+        "max_chars",
+        "placeholder",
+    )
+
+    max_chars: int | None
+    placeholder: str
+
+    def __new__(
+        cls,
+        value: str,
+        max_chars: int | None = None,
+        placeholder: str = "...",
+    ) -> Self:
+        """Create a new TStr instance.
+
+        Args:
+            value: The initial string value.
+            max_chars: Maximum number of characters. If None, no truncation occurs.
+            placeholder: String to append when truncating. Default is '...'.
+
+        Returns:
+            A new TStr instance with the specified truncation settings.
+        """
+        if max_chars is not None:
+            value = trunc_str(
+                text=value,
+                max_chars=max_chars,
+                placeholder=placeholder,
+            )
+        instance = super().__new__(cls, value)
+        instance.max_chars = max_chars
+        instance.placeholder = placeholder
+        return instance
+
+    def __add__(self, other: str) -> Self:
+        result = super().__add__(other)
+        return type(self)(result, self.max_chars)
+
+    def __mul__(self, other: SupportsIndex) -> Self:
+        result = super().__mul__(other)
+        return type(self)(result, self.max_chars)
+
+    def __radd__(self, other: str) -> Self:
+        result = other + str(self)
+        return type(self)(result, self.max_chars)
+
+    def __rmul__(self, other: SupportsIndex) -> Self:
+        result = other * str(self)
+        return type(self)(result, self.max_chars)
+
+    def __mod__(self, other) -> Self:
+        result = super().__mod__(other)
+        return type(self)(result, self.max_chars)
+
+    def __rmod__(self, other) -> Self:
+        result = other % str(self)
+        return type(self)(result, self.max_chars)
+
+    def __getitem__(self, key) -> str | Self:
+        result = super().__getitem__(key)
+        if isinstance(key, int):
+            return result
+        return type(self)(result, self.max_chars)
+
+    def __format__(self, format_spec: str) -> str:
+        return super().__format__(format_spec)
+
+    def __repr__(self) -> str:
+        return f"TStr({super().__repr__()}, max_chars={self.max_chars}, placeholder={self.placeholder})"

stringz-0.1.1.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: stringz
+Version: 0.1.1
+Summary: Utilities library for working with strings
+Project-URL: Changelog, https://github.com/johandielangman/stringz/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://johandielangman.github.io/stringz/
+Project-URL: Issues, https://github.com/johandielangman/stringz/issues
+Project-URL: Source, https://github.com/johandielangman/stringz
+Author-email: Johandielangman <johan@datatreehouse.org>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://johandielangman.github.io/stringz/">
+    <img src="https://raw.githubusercontent.com/johandielangman/stringz/main/docs/static/images/banner.svg" alt="stringz">
+  </a>
+</p>
+<p align="center">
+  <em>Utilities library for working with strings.</em>
+</p>
+<p align="center">
+  <a href="https://pypi.org/project/stringz"><img src="https://img.shields.io/pypi/v/stringz.svg" alt="PyPI - Version"></a>
+  <a href="https://pypi.org/project/stringz"><img src="https://img.shields.io/pypi/pyversions/stringz.svg" alt="PyPI - Python Version"></a>
+  <a href="https://github.com/johandielangman/stringz/actions/workflows/ci.yml"><img src="https://github.com/johandielangman/stringz/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/johandielangman/stringz"><img src="https://codecov.io/gh/johandielangman/stringz/graph/badge.svg" alt="codecov"></a>
+  <a href="https://johandielangman.github.io/stringz/"><img src="https://img.shields.io/badge/docs-latest-blue" alt="Docs"></a>
+</p>
+
+---
+
+Simply install this amazing utilities package:
+
+``` console
+uv add stringz
+```
+
+And immediately get the benefits
+
+```python
+from stringz import pretty_str, ding
+
+result = pretty_str("Hello world!", max_chars=10)
+print(result)  # Output: 'Hello w...'
+```
+
+## Roadmap
+
+only the future will know!
+
+- [x] Pretty truncation and truncation string type
+- [ ] `mask` for sensitive information masking
+- [ ] converters (`to_snake`, `to_camel`, etc)
+- [ ] `join_human` that joins using Oxford comma
+- [ ] `ordinal(22)` should give `22nd`
+- [ ] `pluralize("box", n)` gives "boxes"... maybe
+- [ ] `slugify`
+- [ ] `is_blank`
+
+## License
+
+`stringz` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

stringz-0.1.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+stringz/__init__.py,sha256=UAMKx_eZUSe8EFQ8XwXt8yIWQ0-A7q4eb0NApPqCtrc,55
+stringz/_truncated_string.py,sha256=ZoCCpw_9hrGwamIk9uZBrikFaif-i7zgdUzwr7_briw,5046
+stringz-0.1.1.dist-info/METADATA,sha256=rK65iaYiT3n0No2S1_LLMLspP4RPFm9iVX9JSS3DsIs,2771
+stringz-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+stringz-0.1.1.dist-info/licenses/LICENSE.txt,sha256=x7yQuGcgYfBt-59XVxvZEzDp-rw8aRlEzu_mcxSNlKA,1080
+stringz-0.1.1.dist-info/RECORD,,

stringz-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stringz-0.1.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Johandielangman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.