detextive 3.0__tar.gz → 3.2__tar.gz

{detextive-3.0 → detextive-3.2}/.gitignore

@@ -5,3 +5,5 @@ __pycache__/
 bugs/
 build/
 dist/
+
+uv.lock

{detextive-3.0 → detextive-3.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: detextive
-Version: 3.0
+Version: 3.2
 Summary: Detects textual content.
 Project-URL: Homepage, https://github.com/emcd/python-detextive
 Project-URL: Documentation, https://emcd.github.io/python-detextive
@@ -15,15 +15,13 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Requires-Dist: absence~=1.1
 Requires-Dist: accretive~=4.1
 Requires-Dist: chardet
@@ -113,6 +111,8 @@ Key Features ⭐
   using control character and printability heuristics.
 
 
+
+
 Installation 📦
 ===============================================================================
 
@@ -229,12 +229,14 @@ For complete bytes-to-text processing with automatic charset detection and valid
     print( f"Decoded text: {text}" )
 
 
+
+
 Contribution 🤝
 ===============================================================================
 
 Contribution to this project is welcome! However, it must follow the `code of
 conduct
-<https://emcd.github.io/python-project-common/stable/sphinx-html/common/conduct.html>`_
+<https://emcd.github.io/documentation-common/v1/sphinx-html/common/conduct.html>`_
 for the project.
 
 Please file bug reports and feature requests in the `issue tracker
@@ -286,9 +288,15 @@ Other Projects by This Author 🌟
 ===============================================================================
 
 
-* `python-absence <https://github.com/emcd/python-absence>`_ (`absence <https://pypi.org/project/absence/>`_ on PyPI)
+* `agentmux <https://github.com/emcd/agentmux>`_  (`agentmux <https://crates.io/crates/agentmux/>`_ on Crates.io)
 
-  🕳️ A Python library package which provides a **sentinel for absent values** - a falsey, immutable singleton that represents the absence of a value in contexts where ``None`` or ``False`` may be valid values.
+  📡 Provides **relays for inter-agent communication** and a single pane of glass for managing multiple agent harness sessions.
+* `cistella <https://github.com/emcd/cistella>`_  (`cistella <https://crates.io/crates/cistella/>`_ on Crates.io)
+
+  🧱 A **sandboxing application** which **isolates agent sessions** via various technologies.
+* `nb-mcp-server <https://github.com/emcd/nb-mcp-server>`_  (`nb-mcp-server <https://crates.io/crates/nb-mcp-server/>`_ on Crates.io)
+
+  🗒️ An MCP server wrapping the ``nb`` CLI for **LLM-friendly note-taking**.
 * `python-accretive <https://github.com/emcd/python-accretive>`_ (`accretive <https://pypi.org/project/accretive/>`_ on PyPI)
 
   🌌 A Python library package which provides **accretive data structures** - collections which can grow but never shrink.
@@ -304,12 +312,6 @@ Other Projects by This Author 🌟
 * `python-frigid <https://github.com/emcd/python-frigid>`_ (`frigid <https://pypi.org/project/frigid/>`_ on PyPI)
 
   🔒 A Python library package which provides **immutable data structures** - collections which cannot be modified after creation.
-* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI)
-
-  🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
-* `python-librovore <https://github.com/emcd/python-librovore>`_ (`librovore <https://pypi.org/project/librovore/>`_ on PyPI)
-
-  🐲 **Documentation Search Engine** - An intelligent documentation search and extraction tool that provides both a command-line interface for humans and an MCP (Model Context Protocol) server for AI agents. Search across Sphinx and MkDocs sites with fuzzy matching, extract clean markdown content, and integrate seamlessly with AI development workflows.
-* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI)
+* `python-ictr <https://github.com/emcd/python-ictr>`_ (`ictr <https://pypi.org/project/ictr/>`_ on PyPI)
 
-  📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.
+  🍦 **Non-Intrusive Debugging** - A Python library which provides flavored traces, configuration hierarchies, customized outputs, and ready-made recipes for logging and debug printing.

{detextive-3.0 → detextive-3.2}/README.rst

@@ -69,6 +69,8 @@ Key Features ⭐
   using control character and printability heuristics.
 
 
+
+
 Installation 📦
 ===============================================================================
 
@@ -185,12 +187,14 @@ For complete bytes-to-text processing with automatic charset detection and valid
     print( f"Decoded text: {text}" )
 
 
+
+
 Contribution 🤝
 ===============================================================================
 
 Contribution to this project is welcome! However, it must follow the `code of
 conduct
-<https://emcd.github.io/python-project-common/stable/sphinx-html/common/conduct.html>`_
+<https://emcd.github.io/documentation-common/v1/sphinx-html/common/conduct.html>`_
 for the project.
 
 Please file bug reports and feature requests in the `issue tracker
@@ -242,9 +246,15 @@ Other Projects by This Author 🌟
 ===============================================================================
 
 
-* `python-absence <https://github.com/emcd/python-absence>`_ (`absence <https://pypi.org/project/absence/>`_ on PyPI)
+* `agentmux <https://github.com/emcd/agentmux>`_  (`agentmux <https://crates.io/crates/agentmux/>`_ on Crates.io)
 
-  🕳️ A Python library package which provides a **sentinel for absent values** - a falsey, immutable singleton that represents the absence of a value in contexts where ``None`` or ``False`` may be valid values.
+  📡 Provides **relays for inter-agent communication** and a single pane of glass for managing multiple agent harness sessions.
+* `cistella <https://github.com/emcd/cistella>`_  (`cistella <https://crates.io/crates/cistella/>`_ on Crates.io)
+
+  🧱 A **sandboxing application** which **isolates agent sessions** via various technologies.
+* `nb-mcp-server <https://github.com/emcd/nb-mcp-server>`_  (`nb-mcp-server <https://crates.io/crates/nb-mcp-server/>`_ on Crates.io)
+
+  🗒️ An MCP server wrapping the ``nb`` CLI for **LLM-friendly note-taking**.
 * `python-accretive <https://github.com/emcd/python-accretive>`_ (`accretive <https://pypi.org/project/accretive/>`_ on PyPI)
 
   🌌 A Python library package which provides **accretive data structures** - collections which can grow but never shrink.
@@ -260,12 +270,6 @@ Other Projects by This Author 🌟
 * `python-frigid <https://github.com/emcd/python-frigid>`_ (`frigid <https://pypi.org/project/frigid/>`_ on PyPI)
 
   🔒 A Python library package which provides **immutable data structures** - collections which cannot be modified after creation.
-* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI)
-
-  🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
-* `python-librovore <https://github.com/emcd/python-librovore>`_ (`librovore <https://pypi.org/project/librovore/>`_ on PyPI)
-
-  🐲 **Documentation Search Engine** - An intelligent documentation search and extraction tool that provides both a command-line interface for humans and an MCP (Model Context Protocol) server for AI agents. Search across Sphinx and MkDocs sites with fuzzy matching, extract clean markdown content, and integrate seamlessly with AI development workflows.
-* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI)
+* `python-ictr <https://github.com/emcd/python-ictr>`_ (`ictr <https://pypi.org/project/ictr/>`_ on PyPI)
 
-  📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.
+  🍦 **Non-Intrusive Debugging** - A Python library which provides flavored traces, configuration hierarchies, customized outputs, and ready-made recipes for logging and debug printing.

{detextive-3.0 → detextive-3.2}/pyproject.toml

@@ -13,7 +13,7 @@ description = 'Detects textual content.'
 dynamic = [ 'version' ]
 license = 'Apache-2.0'
 readme = { 'file' = 'README.rst', 'content-type' = 'text/x-rst' }
-requires-python = '>= 3.10'
+requires-python = '>= 3.12'
 dependencies = [
   'accretive~=4.1',
   'chardet',
@@ -31,13 +31,11 @@ classifiers = [ # https://pypi.org/classifiers
   'License :: OSI Approved :: Apache Software License',
   'Programming Language :: Python :: 3 :: Only',
   # --- BEGIN: Injected by Copier ---
-  'Programming Language :: Python :: 3.10',
-  'Programming Language :: Python :: 3.11',
   'Programming Language :: Python :: 3.12',
   'Programming Language :: Python :: 3.13',
   'Programming Language :: Python :: 3.14',
+  'Programming Language :: Python :: 3.15',
   'Programming Language :: Python :: Implementation :: CPython',
-  'Programming Language :: Python :: Implementation :: PyPy',
   # --- END: Injected by Copier ---
   'Topic :: Software Development',
 ]
@@ -103,7 +101,7 @@ strict-naming = false
 # --- BEGIN: Injected by Copier ---
 # --- END: Injected by Copier ---
 [tool.hatch.envs.default]
-python = '3.10'
+python = '3.12'
 [tool.hatch.envs.develop]
 description = ''' Development environment. '''
 builder = true
@@ -113,7 +111,6 @@ dependencies = [
   'furo',
   'isort',
   'myst-parser',
-  'pre-commit',
   'pyright',
   'pytest',
   'ruff',
@@ -141,13 +138,23 @@ docsgen = [
   """sphinx-build -a -d .auxiliary/caches/sphinx --quiet \
       documentation .auxiliary/artifacts/sphinx-html""",
 ]
+fragments = [
+  """python .auxiliary/scripts/validate-fragments.py""",
+]
+module-sizes = [
+  """python .auxiliary/scripts/validate-module-sizes.py""",
+]
 linters = [
   """ruff check --quiet sources documentation tests""",
-  """vibelinter check""",
+  # External install only (e.g. uv tool install): a develop dependency
+  # cycles for packages below emcd-vibe-linter in the stack.
+  #"""vibelinter check""",
   # --- BEGIN: Injected by Copier ---
   # --- END: Injected by Copier ---
   """isort --check-only --diff sources tests""",
   """pyright sources""",
+  'fragments',
+  'module-sizes',
 ]
 packagers = [
   """hatch build""",
@@ -184,13 +191,10 @@ description = ''' Quality assurance environment. '''
 template = 'develop'
 [[tool.hatch.envs.qa.matrix]]
 python = [
-    '3.10',
-    '3.11',
     '3.12',
     '3.13',
     '3.14',
-    'pypy3.10',
-    'pypy3.11',
+    '3.15',
 ]
 [tool.hatch.version]
 path = 'sources/detextive/__init__.py'

{detextive-3.0 → detextive-3.2}/sources/detextive/__init__.py

@@ -37,7 +37,7 @@ from . import exceptions
 # --- END: Injected by Copier ---
 
 
-__version__ = '3.0'
+__version__ = '3.2'
 
 
 __.immut.finalize_module( __name__, recursive = True )

{detextive-3.0 → detextive-3.2}/sources/detextive/charsets.py

@@ -35,7 +35,7 @@ from .core import ( # isort: skip
 )
 
 
-def attempt_decodes(  # noqa: C901,PLR0912,PLR0913,PLR0915
+def attempt_decodes( # noqa: PLR0913
     content: _nomina.Content, /, *,
     behaviors: _Behaviors = _BEHAVIORS_DEFAULT,
     inference: __.Absential[ str ] = __.absent,
@@ -52,29 +52,20 @@ def attempt_decodes(  # noqa: C901,PLR0912,PLR0913,PLR0915
     '''
     confidence = _core.confidence_from_bytes_quantity(
         content, behaviors = behaviors )
-    on_decode_error = behaviors.on_decode_error
+    trial_codecs = _collect_trial_codecs(
+        content,
+        behaviors = behaviors,
+        inference = inference,
+        supplement = supplement )
     trials: set[ str ] = set( )
-    for codec in behaviors.trial_codecs:
-        match codec:
-            case _CodecSpecifiers.FromInference:
-                if __.is_absent( inference ): continue
-                charset = inference
-            case _CodecSpecifiers.OsDefault:
-                charset = discover_os_charset_default( )
-            case _CodecSpecifiers.PythonDefault:
-                charset = __.locale.getpreferredencoding( )
-            case _CodecSpecifiers.UserSupplement:
-                if __.is_absent( supplement ): continue
-                charset = supplement
-            case str( ): charset = codec
-            case _: continue
-        charset = normalize_charset(
-            charset, bom_cognizant = behaviors.remove_bom )
-        if charset in trials: continue
-        try: text = content.decode( charset, errors = on_decode_error )
+    for trial_codec in trial_codecs:
+        try: text = content.decode(
+            trial_codec, errors = behaviors.on_decode_error )
         except UnicodeDecodeError: continue
-        finally: trials.add( charset )
-        result = _CharsetResult( charset = charset, confidence = confidence )
+        finally: trials.add( trial_codec )
+        result = _CharsetResult(
+            charset = normalize_charset_for_content( content, trial_codec ),
+            confidence = confidence )
         if not __.is_absent( validator ):
             try: validator( text, result )
             except _exceptions.TextInvalidity: continue
@@ -97,6 +88,23 @@ def normalize_charset( charset: str, bom_cognizant: bool = False ) -> str:
     return charset_
 
 
+def normalize_charset_for_content(
+    content: _nomina.Content, charset: str
+) -> str:
+    ''' Normalizes charset reporting based on byte-order mark provenance. '''
+    charset_ = normalize_charset( charset )
+    bom_charset = _discover_utf_bom_charset( content )
+    if charset_ in ( 'utf-8', 'utf-8-sig' ):
+        if bom_charset == 'utf-8-sig': return 'utf-8-sig'
+        return 'utf-8'
+    for family in ( 'utf-16', 'utf-32' ):
+        if not charset_.startswith( family ): continue
+        if bom_charset in ( f"{family}-le", f"{family}-be" ):
+            return family
+        return charset_
+    return charset_
+
+
 def trial_decode_as_confident( # noqa: PLR0913
     content: _nomina.Content, /, *,
     behaviors: _Behaviors = _BEHAVIORS_DEFAULT,
@@ -126,3 +134,68 @@ def trial_decode_as_confident( # noqa: PLR0913
     if __.is_absent( inference ):
         raise _exceptions.CharsetDetectFailure( location = location )
     return _CharsetResult( charset = inference, confidence = confidence )
+
+
+def _collect_trial_codecs(
+    content: _nomina.Content, /, *,
+    behaviors: _Behaviors,
+    inference: __.Absential[ str ],
+    supplement: __.Absential[ str ],
+) -> tuple[ str, ... ]:
+    codecs: list[ str ] = [ ]  # No set needed; this candidate list is tiny.
+    for codec in behaviors.trial_codecs:
+        charset = _resolve_trial_codec(
+            codec, inference = inference, supplement = supplement )
+        if __.is_absent( charset ): continue
+        charset = normalize_charset( charset )
+        if _is_ambiguous_utf_trial( content, charset, behaviors ): continue
+        if behaviors.remove_bom and charset == 'utf-8': charset = 'utf-8-sig'
+        if charset in codecs: continue
+        codecs.append( charset )
+    return tuple( codecs )
+
+
+def _discover_utf_bom_charset(
+    content: _nomina.Content
+) -> __.typx.Optional[ str ]:
+    # Must check UTF-32 markers first, since they prefix-match UTF-16 markers.
+    if content.startswith( __.codecs.BOM_UTF32_LE ): return 'utf-32-le'
+    if content.startswith( __.codecs.BOM_UTF32_BE ): return 'utf-32-be'
+    if content.startswith( __.codecs.BOM_UTF8 ): return 'utf-8-sig'
+    if content.startswith( __.codecs.BOM_UTF16_LE ): return 'utf-16-le'
+    if content.startswith( __.codecs.BOM_UTF16_BE ): return 'utf-16-be'
+    return None
+
+
+def _is_ambiguous_utf_trial(
+    content: _nomina.Content, charset: str, behaviors: _Behaviors
+) -> bool:
+    if not behaviors.utf_16_32_requires_byte_order: return False
+    match charset:
+        case 'utf-16':
+            bom_charset = _discover_utf_bom_charset( content )
+            return bom_charset not in ( 'utf-16-le', 'utf-16-be' )
+        case 'utf-32':
+            bom_charset = _discover_utf_bom_charset( content )
+            return bom_charset not in ( 'utf-32-le', 'utf-32-be' )
+        case _: return False
+
+
+def _resolve_trial_codec(
+    codec: __.typx.Any, /, *,
+    inference: __.Absential[ str ],
+    supplement: __.Absential[ str ],
+) -> __.Absential[ str ]:
+    charset: __.Absential[ str ] = __.absent
+    match codec:
+        case _CodecSpecifiers.FromInference:
+            if not __.is_absent( inference ): charset = inference
+        case _CodecSpecifiers.OsDefault:
+            charset = discover_os_charset_default( )
+        case _CodecSpecifiers.PythonDefault:
+            charset = __.locale.getpreferredencoding( )
+        case _CodecSpecifiers.UserSupplement:
+            if not __.is_absent( supplement ): charset = supplement
+        case str( ): charset = codec
+        case _: pass
+    return charset

{detextive-3.0 → detextive-3.2}/sources/detextive/core.py

@@ -128,6 +128,12 @@ class Behaviors( __.immut.DataclassObject ):
     trial_decode_confidence: __.typx.Annotated[
         float, __.ddoc.Doc( ''' Minimum confidence to skip trial decode. ''')
     ] = 0.80
+    utf_16_32_requires_byte_order: __.typx.Annotated[
+        bool,
+        __.ddoc.Doc(
+            ''' Require explicit byte order for BOM-less generic UTF-16/32? '''
+        ),
+    ] = False
 
     def __post_init__( self ) -> None:
         if not isinstance( self.charset_detect, bool ):
@@ -136,6 +142,9 @@ class Behaviors( __.immut.DataclassObject ):
         if not isinstance( self.mimetype_detect, bool ):
             raise _exceptions.BehaviorsInvalidity(
                 'mimetype_detect', 'a boolean' )
+        if not isinstance( self.utf_16_32_requires_byte_order, bool ):
+            raise _exceptions.BehaviorsInvalidity(
+                'utf_16_32_requires_byte_order', 'a boolean' )
 
 
 BehaviorsArgument: __.typx.TypeAlias = __.typx.Annotated[

{detextive-3.0 → detextive-3.2}/sources/detextive/decoders.py

@@ -160,15 +160,16 @@ def _decode_content_charset_result( # noqa: PLR0913
     if not __.is_absent( httpct_result ): return httpct_result
     behaviors_ = __.dcls.replace(
         behaviors, trial_decode = _BehaviorTristate.Never )
-    with __.ctxl.suppress( _exceptions.CharsetDetectFailure ):
-        result = _detectors.detect_charset_confidence(
-            content,
-            behaviors = behaviors_,
-            supplement = charset_supplement,
-            location = location )
-        if (    result.charset
-            and result.confidence >= behaviors.trial_decode_confidence
-        ): charset = result.charset
+    if behaviors.charset_detect:
+        with __.ctxl.suppress( _exceptions.CharsetDetectFailure ):
+            result = _detectors.detect_charset_confidence(
+                content,
+                behaviors = behaviors_,
+                supplement = charset_supplement,
+                location = location )
+            if (    result.charset
+                and result.confidence >= behaviors.trial_decode_confidence
+            ): charset = result.charset
     validator = __.funct.partial(
         _validate_text_in_decode_attempt,
         behaviors = behaviors,

{detextive-3.0 → detextive-3.2}/sources/detextive/detectors.py

@@ -340,11 +340,9 @@ mimetype_detectors[ 'puremagic' ] = _detect_via_puremagic
 
 
 def _normalize_charset_detection(
-    content: _nomina.Content, behaviors: _Behaviors, result: _CharsetResult
+    content: _nomina.Content, _behaviors: _Behaviors, result: _CharsetResult
 ) -> _CharsetResult:
     if result.charset is None: return result  # pragma: no cover
-    charset = _charsets.normalize_charset( result.charset )
-    # TODO? Consider endianness variations for BOM.
-    if charset == 'utf-8-sig' and not content.startswith( __.codecs.BOM ):
-        charset = 'utf-8'
+    charset = _charsets.normalize_charset_for_content(
+        content, result.charset )
     return _CharsetResult( charset = charset, confidence = result.confidence )