charded 0.1.0__py3-none-any.whl

charded/__init__.py

@@ -0,0 +1,3 @@
+from charded.string import Str
+
+__all__ = ("Str",)

charded/string.py

@@ -0,0 +1,272 @@
+from contextlib import suppress
+from logging import getLogger
+from math import log2
+from re import findall
+
+from kain.descriptors import pin, proxy_to
+from kain.importer import optional
+from kain.internals import Who, to_ascii, unique
+
+logger = getLogger(__name__)
+
+
+def generate_binary_offsets(x: int):
+    power = int(log2(x))
+
+    yield 0
+    for base in range(power):
+        bias = (2 ** (power - base))
+        for no in range(x // bias + 1):
+            if no % 2:
+                yield no * bias
+
+
+def iter_by_binary_offsets(x: bytes | str, /, ordinate: bool):
+    getter = x.__getitem__
+    offset = len(x) - len(x) % 2 - 1
+
+    if offset != -1:
+        iterator = generate_binary_offsets(offset)
+
+        offsets = map(getter, iterator)
+        if ordinate:
+            offsets = map(ord, offsets)
+        yield from enumerate(offsets)
+
+
+def replace_class_with_str(method, *args, **kw):
+    if args and isinstance(args[0], Str):
+        args = (str(args[0]), *args[1:])
+    return method(*args, **kw)
+
+
+class External:
+
+    @pin.cls
+    def _charset_detect(cls):
+        return optional("charset_normalizer.detect")
+
+    @pin.cls
+    def _from_buffer(cls):
+        return optional("magic.from_buffer")
+
+    @pin.cls
+    def _from_content(cls):
+        return optional("magic.detect_from_content")
+
+    #
+
+    @pin.cls
+    def charset_detect(cls):
+        if detect := External._charset_detect:
+            def charset_detect(x: bytes) -> str:
+                return detect(x)
+        else:
+            def charset_detect(x: bytes) -> None: ...
+
+        return charset_detect
+
+    @pin.cls
+    def mime_reader(cls):
+        if (read := cls._from_buffer) and (detect := cls._from_content):
+            def mime_reader(x: bytes) -> dict[str, str]:
+                return {
+                    "type": detect(x).mime_type,
+                    "description": read(x)}
+        else:
+            def mime_reader(x: bytes) -> None: ...
+
+        return mime_reader
+
+
+@proxy_to(
+    "text",
+    "__add__", "__contains__", "__eq__", "__format__", "__hash__", "__ge__",
+    "__getitem__", "__gt__", "__iter__", "__le__", "__len__", "__lt__", "__mod__",
+    "__mul__", "__ne__", "__rmod__", "__rmul__", "__sizeof__", "capitalize",
+    "casefold", "center", "count", "encode", "endswith", "expandtabs", "find",
+    "format", "format_map", "index", "isalnum", "isalpha", "isascii", "isdecimal",
+    "isdigit", "isidentifier", "islower", "isnumeric", "isprintable", "isspace",
+    "istitle", "isupper", "join", "ljust", "lower", "lstrip", "maketrans",
+    "partition", "removeprefix", "removesuffix", "replace", "rfind", "rindex",
+    "rjust", "rpartition", "rsplit", "rstrip", "split", "splitlines", "startswith",
+    "strip", "swapcase", "title", "translate", "upper", "zfill",
+    pin, pre=replace_class_with_str,
+)
+class Str:
+    """A class for handling bytes | str objects.
+
+    Autodetect charsets, autoencode/decode from bytes/text.
+    Just pass any bytes | str object to Str and use it:
+
+    x = Str(b'hello')
+    str(x) == 'hello'
+    bytes(x) == b'hello'
+
+    """
+
+    InternalCharset   : str = "utf-8"
+    DetectionSizeLimit: int = 2 ** 20
+    DetectionScanLimit: int = 2 ** 10
+
+    to_ascii = staticmethod(to_ascii)
+
+    @classmethod
+    def to_bytes(cls, obj, *args, **kw):
+        return bytes(cls(obj, *args, **kw))
+
+    @classmethod
+    def to_text(cls, obj, *args, **kw):
+        return str(cls(obj, *args, **kw))
+
+    #
+
+    @classmethod
+    def downcast(cls, obj):
+        if isinstance(obj, bytes | str):
+            return obj
+
+        if isinstance(obj, int):
+            return str(obj)
+
+        msg = f"{Who(cls)} accept bytes | str, got {Who.Is(obj)}"
+        raise TypeError(msg)
+
+    @pin
+    def mime(self):
+        try:
+            return External.mime_reader(self.bytes)
+
+        except Exception:  # noqa: BLE001 Do not catch blind exception: `Exception`
+            logger.warning(
+                f"something went wrong for {self.bytes[:2**10]!r}", exc_info=True)
+
+    #
+
+    def __bytes__(self):
+        return self.bytes
+
+    def __str__(self):
+        return self.text
+
+    def __init__(self, obj, /, charset=None):
+        self._object = obj
+        self._charset = charset or self.InternalCharset
+
+    @pin
+    def _value(self):
+        return self.downcast(self._object)
+
+    #
+
+    @pin
+    def external_charset(self):
+        return External.charset_detect(self.bytes)
+
+    @pin
+    def probe_order(self):
+        result = [self._charset]
+
+        if meta := self.external_charset:
+            result.append(meta["encoding"])
+
+        return tuple(unique([*result, "ascii"]))
+
+    @pin
+    def compatible_charset(self):
+        string = self._value
+
+        if isinstance(string, bytes):
+            method = string.decode
+            order = self.probe_order
+
+        else:
+            method = string.encode
+            order = tuple(reversed(self.probe_order))
+
+        for charset in filter(bool, order):
+            with suppress(UnicodeEncodeError, UnicodeDecodeError):
+                method(charset)
+                return charset
+
+    @pin
+    def charset(self):
+        string = self._value
+        is_bytes = isinstance(string, bytes)
+
+        read_limit = self.DetectionSizeLimit
+        if not is_bytes and len(string) <= read_limit:
+            read_limit = 0
+
+        default = "ascii"
+        if not string:
+            return default
+
+        collected = set()
+        scan_limit = self.DetectionScanLimit
+
+        for no, char in iter_by_binary_offsets(string, ordinate=not is_bytes):
+            if no > read_limit:
+                break
+
+            if char < 0x20:  # noqa: PLR2004
+                if char in (0x9, 0xa, 0xc, 0xd):
+                    continue
+                return "binary"
+
+            if char >= 0x7f:  # noqa: PLR2004, ANSI Extended Border
+                if is_bytes:
+                    default = "ansi"
+
+                elif char not in collected:
+                    if len(collected) >= scan_limit:
+                        return self.compatible_charset
+                    collected.add(char)
+
+        return default if is_bytes else self.compatible_charset
+
+    #
+
+    @pin
+    def bytes(self):
+        string = self._value
+        return string if isinstance(string, bytes) else string.encode(self._charset)
+
+    @pin
+    def text(self):
+        string = self._value
+        if isinstance(string, str):
+            return string
+
+        charset = self.charset
+        if charset == "ansi":
+            charset = self.compatible_charset
+
+        if charset != "binary":
+            return string.decode(charset)
+
+        msg = f"couldn't {charset=} decode {string[:2**10]!r}"
+        if charset := self.charset:
+            msg = f"{msg}; {charset}"
+
+        raise ValueError(msg)
+
+    def __repr__(self):
+        string = self._value
+        size = f"{len(self.bytes):d}"
+
+        length = ""
+        charset = (f"{self.charset} ".upper()) if self.charset else ""
+
+        if isinstance(string, str) and len(self.bytes) != len(self.text):
+            length = f"={len(self.text):d}"
+
+        return (
+            f"<{charset}{Who(self, full=False)}"
+            f"[{Who(self._object, full=False)}"
+            f"({size})]{length} at {id(self):#x}>")
+
+    #
+
+    def tokenize(self, regex=r"([\w\d]+)"):
+        return findall(regex, self.text)

charded-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: charded
+Version: 0.1.0
+Summary: charded
+Author-email: Alex Kalaverin <alex@kalaver.in>
+Project-URL: Homepage, https://kalaver.in
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: charset-normalizer>=3.4.2
+Requires-Dist: kain<0.2.0,>=0.1.3
+Requires-Dist: python-magic>=0.4.27
+
+# Simple project for Python 3.10+
+#### All-in-one repository with supervisor, crontab, linters and many useful tools
+
+**Version control** is handled using [Astral UV](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer) tool. When building the image, uv is sourced from the official repository by copying the binary. Installation on a developer's machine can be done in various ways, which we'll cover shortly.
+
+**Managing the interpreter version**, project environment variables, and setting up the virtual environment is done with the [Mise](https://mise.jdx.dev/installing-mise.html) tool. It automatically install any interpreter version by reading it from the project description and/or the version bound by uv. It can also fetch the appropriate uv binary for the platform and architecture.
+
+## How to install required tools?
+
+#### A. Quick start for test
+
+Therefore, the quickest and most minimal way to get touch is to install mise on your system and prepare tools with mise, **not for development**:
+
+1. `brew install mise`
+
+That's all, go to **Shell configuration** section.
+
+#### B. Engineer full-featured setup
+
+**True engineer way** it's prepare rust environment, build mise and configure shell:
+
+1. Install Cargo via [Rustup](https://doc.rust-lang.org/book/ch01-01-installation.html).
+2. Do not forget add cargo path for your shell:
+   - `export PATH="~/.cargo/bin:$PATH"`
+3. Install sccache to avoid electricity bills:
+   - `cargo install sccache`
+4. Activate sccache:
+   - `export RUSTC_WRAPPER="~/.cargo/bin/sccache"` (and add it to your shell)
+5. Install cargo packages updater and mise:
+   - `cargo install cargo-update mise`
+6. Install uv:
+   - `mise install uv@latest && mise use -g uv@latest`
+7. That's all, you have last version of optimized tools; for update all packages just run sometime:
+   - `rustup update && cargo install-update --all`
+
+### Shell configuration
+
+1. **Mise provide dotenv functionality** (automatic read per-project environment variables from .env file and from .mise.toml config) from the box with batteries, but your shell must have entry hook, add to your shell it, example for zsh (your can replace it for bash, fish, etc):
+   - `eval "$(mise activate zsh)"`
+2. Also you can want using autocompletion, same story for zsh:
+   - `eval "$(mise completion zsh && uv generate-shell-completion zsh)"`
+3. Restart your shell session:
+   - `exec "$SHELL"`
+
+### Kickstart
+
+1. Go to project root.
+2. Just run `make`:
+   - mise will mark project directory as trusted
+   - mise copy sample development environment variables to .env
+   - mise grab environment variables defined in project .env, evaluate it and provide to current shell session
+   - mise checks what project python versions is installed, otherwise download and install it
+   - uv make virtual environment in project root (`uv venv`)
+   - uv read project packages list, download, install and link it (via `uv sync` run, read Makefile)
+   - uv install pre-commit and pre-push hooks
+
+## Work with project
+
+### Warning about pip
+
+**NEVER CALL pip, NEVER!** Instead it use native uv calls, [read uv manual](https://docs.astral.sh/uv/guides/projects/#managing-dependencies), it's very easy, for example:
+
+1. Set or change python version (when python 3.11 already installed), before run do not forget change your python version in pyproject.toml:
+   - `uv python pin 3.11 && make sync`
+
+2. If python 3.11 isn't installed, run `mise install python@3.11` and mise download and install python 3.11, recreate virtual environment with 3.11 context. Do not forget to pin python version by uv from previous step (and, may be you need to update your pyproject.toml).
+
+2. Just add new dependency:
+   - `uv add phpbb<=1.2`
+
+3. Add some development library:
+   - `uv add --group development backyard-memleak`
+
+4. Work with locally cloned repository:
+   - `uv add --editable ~/src/lib/chrome-v8-core`
+
+### Common workflow
+
+1. `make`:
+   - same as `mise install`, but also call `mise trust --yes` for initial deployment
+   - call `make sync`
+
+2. `make sync`
+   - drop and recreate .venv by `uv venv`
+   - read project dependencies graph from pyproject.toml and install it to virtual environment by `uv sync`)
+   - call `make freeze`
+
+3. `make freeze`:
+   - dump state to uv.lock by `uv lock`
+   - for development and debugging puproses uv save all used packages in current virtual environment to `packages.json` (with all development packages!) by `uv pip list`
+   - for repeatable production purposes uv save project dependencies to `packages.txt` with hashes for release builds strict version checks, read Dockerfile example (only project dependencies!) by `uv pip compile`
+
+4. `make upgrade`:
+   - read project dependencies graph from pyproject.toml
+   - fetch information about all updated packages, recreate dependencies graph and install it to virtual environment by `uv sync --upgrade`
+   - update `uv.lock` with updated packages version by `uv lock --upgrade`
+   - call `make freeze`
+   - show all installed packages in local virtual environment
+   - all you need it's just manually update versions in pyproject.toml
+
+5. `make check`:
+   It's non-destructive action, just run all checks and stop at first fail.
+
+6. `make lint`:
+   **Destructive action**, always commit all changes before run it. Runs all compatible linters with --fix and --edit mode, after it call `make check` for final polishing.

charded-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+charded/__init__.py,sha256=BAPU0Z8j9BS4AyJ4fuk4HDDuv-V08XTlZjRMqE0Tcn0,51
+charded/string.py,sha256=dAeBm9ietA1qjwuYV0-F6FSaZA2oSvLWMvow7CkfLkM,7330
+charded-0.1.0.dist-info/METADATA,sha256=J0hzWvs6uxg7N1moqigl93V20K2qPDdpaIaT1G2xJPw,6138
+charded-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+charded-0.1.0.dist-info/top_level.txt,sha256=dp0lwnMr-wQOUmTRVMLXZEHKLq-7gawcmB8VE--TTQE,8
+charded-0.1.0.dist-info/RECORD,,

charded-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

charded-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+charded