utilitz 0.9.2__tar.gz → 0.9.4__tar.gz

{utilitz-0.9.2 → utilitz-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: utilitz
-Version: 0.9.2
+Version: 0.9.4
 Summary: Simple Python utility functions to save and load data
 Project-URL: Homepage, https://github.com/artitzco/utilitz
 Project-URL: Issues, https://github.com/artitzco/utilitz/issues
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 
 It is built with a modular approach, keeping the core library lightweight while providing powerful specialized modules through optional dependencies.
 
-Current release: **0.9.1**
+Current release: see package metadata.
 
 ## 🚀 Installation
 

{utilitz-0.9.2 → utilitz-0.9.4}/README.md

@@ -4,7 +4,7 @@
 
 It is built with a modular approach, keeping the core library lightweight while providing powerful specialized modules through optional dependencies.
 
-Current release: **0.9.1**
+Current release: see package metadata.
 
 ## 🚀 Installation
 

{utilitz-0.9.2 → utilitz-0.9.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "utilitz"
-version = "0.9.2"
+version = "0.9.4"
 authors = [
   { name = "Artitzco", email = "artitzco@proton.me" },
 ]

{utilitz-0.9.2 → utilitz-0.9.4}/src/utilitz/crypto/decryptor.py

@@ -235,17 +235,45 @@ class Decryptor:
         finally:
             del password, password_bytes, parts, config, salt, ciphertext, kdf, key
 
+    def _portable_document(self) -> tuple[str | None, dict[str, Any], bytes] | None:
+        if self.content is None or not self.content.startswith(DOCUMENT_MAGIC + b":"):
+            return None
+
+        try:
+            payload = base64.urlsafe_b64decode(
+                self.content[len(DOCUMENT_MAGIC) + 1 :].strip()
+            )
+            document_header, document_content = _unpack_document_payload(payload)
+        except (ValueError, json.JSONDecodeError) as exc:
+            raise ValueError("Invalid portable document format.") from exc
+
+        kind = document_header.get("kind")
+        metadata = document_header.get("metadata", {})
+        return kind, metadata if isinstance(metadata, dict) else {}, document_content
+
+    def _available_content(self) -> tuple[bytes, str | None, dict[str, Any], bool]:
+        if self.decrypted_content is not None:
+            return self.decrypted_content, self.kind, self.metadata, True
+
+        portable_document = self._portable_document()
+        if portable_document is not None:
+            kind, metadata, content = portable_document
+            return content, kind, metadata, True
+
+        if self.content is not None:
+            return self.content, None, {}, False
+
+        raise ValueError("No encrypted, portable, or decrypted content is available.")
+
     def to_bytes(self) -> bytes:
-        if self.decrypted_content is None:
-            raise ValueError("No decrypted content has been generated.")
-        return self.decrypted_content
+        content, _, _, _ = self._available_content()
+        return content
 
     def to_string(self, encoding: str | None = None) -> str:
-        if self.decrypted_content is None:
-            raise ValueError("No decrypted content has been generated.")
         if encoding is None:
-            encoding = self.metadata.get("encoding", "utf-8")
-        return self.decrypted_content.decode(encoding)
+            _, _, metadata, _ = self._available_content()
+            encoding = metadata.get("encoding", "utf-8")
+        return self.to_bytes().decode(encoding)
 
     def to_clipboard(self, encoding: str | None = None) -> str:
         """
@@ -265,24 +293,25 @@ class Decryptor:
         If ``file_path`` is a directory, the stored filename is appended.
         Set ``create_parent=True`` to create missing parent directories.
         """
-        if self.decrypted_content is None:
-            raise ValueError("No decrypted content has been generated.")
+        content, _, metadata, has_document = self._available_content()
 
         if file_path is None:
-            filename = self.metadata.get("filename")
+            filename = metadata.get("filename")
             if not filename:
-                raise ValueError(
-                    "No filename was stored in the decrypted metadata. "
-                    "Provide file_path explicitly."
-                )
+                if has_document:
+                    raise ValueError(
+                        "No filename was stored in the document metadata. "
+                        "Provide file_path explicitly."
+                    )
+                raise ValueError("Provide file_path to write encrypted content.")
             file_path = filename
 
         path = os.path.abspath(os.path.expanduser(file_path))
         if os.path.isdir(path):
-            filename = self.metadata.get("filename")
+            filename = metadata.get("filename")
             if not filename:
                 raise ValueError(
-                    "No filename was stored in the decrypted metadata. "
+                    "No filename was stored in the document metadata. "
                     "Provide file_path explicitly."
                 )
             path = os.path.join(path, filename)
@@ -302,7 +331,7 @@ class Decryptor:
             )
 
         with open(path, "wb") as file_obj:
-            file_obj.write(self.decrypted_content)
+            file_obj.write(content)
 
         return path
 
@@ -320,13 +349,14 @@ class Decryptor:
         root folder. Set ``exact_path=True`` to treat it as the final folder
         path, and ``create_parent=True`` to create missing parent directories.
         """
-        if self.decrypted_content is None:
-            raise ValueError("No decrypted content has been generated.")
-        if self.kind != "directory":
-            raise ValueError("The decrypted content is not a directory archive.")
+        content, kind, _, has_document = self._available_content()
+        if not has_document:
+            raise ValueError("No decrypted or portable document content has been generated.")
+        if kind != "directory":
+            raise ValueError("The document content is not a directory archive.")
 
         try:
-            root_name = _contains_single_root(self.decrypted_content)
+            root_name = _contains_single_root(content)
         except zipfile.BadZipFile as exc:
             raise ValueError("Invalid directory archive.") from exc
 
@@ -364,7 +394,7 @@ class Decryptor:
 
         temp_extract_dir = tempfile.mkdtemp(prefix=".tmp_extract_")
         try:
-            _safe_extract_zip(self.decrypted_content, temp_extract_dir)
+            _safe_extract_zip(content, temp_extract_dir)
 
             extracted_root = os.path.join(temp_extract_dir, root_name)
             if not os.path.isdir(extracted_root):
@@ -376,31 +406,36 @@ class Decryptor:
         return final_dir_path
 
     def to_value(self) -> Any:
-        if self.decrypted_content is None:
-            raise ValueError("No decrypted content has been generated.")
-        if self.kind != "value":
-            raise ValueError("The decrypted content is not a Python value.")
-        if self.metadata.get("serializer") != "pickle":
+        content, kind, metadata, has_document = self._available_content()
+        if not has_document:
+            raise ValueError("No decrypted or portable document content has been generated.")
+        if kind != "value":
+            raise ValueError("The document content is not a Python value.")
+        if metadata.get("serializer") != "pickle":
             raise ValueError("Unsupported value serializer.")
-        return pickle.loads(self.decrypted_content)
+        return pickle.loads(content)
 
     def __str__(self) -> str:
-        state = "idle" if self.content is None else "ready"
-        if self.decrypted_content is not None:
-            state = f"{state}, decrypted"
-        return f"Decryptor<{state}>"
-
-    def __repr__(self) -> str:
-        if self.content is None and self.decrypted_content is None:
-            return "Decryptor(content=None, decrypted_content=None)"
-        content_part = "None" if self.content is None else f"{len(self.content)} bytes"
+        content_part = "none" if self.content is None else f"{len(self.content)} bytes"
         decrypted_part = (
-            "None"
+            "none"
             if self.decrypted_content is None
             else f"{len(self.decrypted_content)} bytes"
         )
+        metadata_keys = ", ".join(sorted(self.metadata)) or "none"
+        return (
+            "Decryptor\n"
+            f"  has_content: {self.has_content}\n"
+            f"  content: {content_part}\n"
+            f"  has_decrypted_content: {self.has_decrypted_content}\n"
+            f"  decrypted_content: {decrypted_part}\n"
+            f"  kind: {self.kind}\n"
+            f"  metadata keys: {metadata_keys}\n"
+            f"  key_env_varname: {self.key_env_varname}"
+        )
+
+    def __repr__(self) -> str:
         return (
-            f"Decryptor(content={content_part}, "
-            f"decrypted_content={decrypted_part}, "
-            f"kind={self.kind!r})"
+            f"Decryptor(has_content={self.has_content}, "
+            f"has_decrypted_content={self.has_decrypted_content}, kind={self.kind!r})"
         )

{utilitz-0.9.2 → utilitz-0.9.4}/src/utilitz/crypto/encryptor.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from .decryptor import Decryptor
 from .input import CryptoInput
+from . import _utils
 from ._utils import (
     CRYPT_MAGIC,
     DOCUMENT_MAGIC,
@@ -204,23 +205,37 @@ class Encryptor:
         finally:
             del password, password_bytes, salt, kdf, key, document_payload, ciphertext, config, encrypted_content
 
-    def to_bytes(self) -> bytes:
-        if self.output is None:
-            raise ValueError("No encrypted output has been generated.")
-        return self.output.to_bytes()
+    def _exportable_content(self) -> bytes:
+        if self.output is not None:
+            return self.output.to_bytes()
+        if self.input is not None:
+            return self.input.to_bytes()
+        raise ValueError("No crypto input or encrypted output is available.")
 
-    def to_string(self, encoding: str = "utf-8") -> str:
-        if self.output is None:
-            raise ValueError("No encrypted output has been generated.")
-        return self.output.to_string(encoding=encoding)
+    def _portable_content(self) -> bytes:
+        if self.output is not None:
+            return self.output.to_bytes()
+        if self.input is not None:
+            return DOCUMENT_MAGIC + b":" + base64.urlsafe_b64encode(
+                _build_document_payload(self.input)
+            )
+        raise ValueError("No crypto input or encrypted output is available.")
+
+    def to_bytes(self, *, portable: bool = False) -> bytes:
+        if portable:
+            return self._portable_content()
+        return self._exportable_content()
 
-    def to_clipboard(self, encoding: str = "utf-8") -> str:
+    def to_string(self, encoding: str = "utf-8", *, portable: bool = False) -> str:
+        return self.to_bytes(portable=portable).decode(encoding)
+
+    def to_clipboard(self, encoding: str = "utf-8", *, portable: bool = False) -> str:
         """
-        Copy the encrypted output to the system clipboard as text.
+        Copy the encrypted output, or the input when no output exists, as text.
         """
-        if self.output is None:
-            raise ValueError("No encrypted output has been generated.")
-        return self.output.to_clipboard(encoding=encoding)
+        return _utils.copy_text_to_clipboard(
+            self.to_string(encoding=encoding, portable=portable)
+        )
 
     def to_file(
         self,
@@ -229,10 +244,9 @@ class Encryptor:
         encoding: str = "utf-8",
         overwrite: bool = False,
         binary: bool = False,
+        portable: bool = False,
     ) -> str:
-        if self.output is None:
-            raise ValueError("No encrypted output has been generated.")
-        return self.output.to_file(
+        return CryptoOutput.create(self.to_bytes(portable=portable)).to_file(
             file_path,
             encoding=encoding,
             overwrite=overwrite,
@@ -248,9 +262,13 @@ class Encryptor:
         return f"Encryptor(has_input={self.has_input}, has_output={self.has_output})"
 
     def __str__(self) -> str:
-        state = "idle"
-        if self.input is not None:
-            state = "ready"
-        if self.output is not None:
-            state = f"{state}, encrypted"
-        return f"Encryptor<{state}>"
+        input_part = "none" if self.input is None else f"{self.input.kind}, {self.input.size} bytes"
+        output_part = "none" if self.output is None else f"{self.output.size} bytes"
+        return (
+            "Encryptor\n"
+            f"  has_input: {self.has_input}\n"
+            f"  input: {input_part}\n"
+            f"  has_output: {self.has_output}\n"
+            f"  output: {output_part}\n"
+            f"  key_env_varname: {self.key_env_varname}"
+        )

{utilitz-0.9.2 → utilitz-0.9.4}/src/utilitz/crypto/input.py

@@ -136,13 +136,17 @@ class CryptoInput:
         return self.content
 
     def __repr__(self) -> str:
-        return (
-            f"CryptoInput(kind={self.kind!r}, size={self.size}, "
-            f"content_hash={self.content_hash!r}, metadata={self.metadata!r})"
-        )
+        return f"CryptoInput(kind={self.kind!r}, size={self.size}, hash={self.content_hash[:12]!r})"
 
     def __str__(self) -> str:
-        return f"CryptoInput<{self.kind}, {self.size} bytes>"
+        metadata_keys = ", ".join(sorted(self.metadata)) or "none"
+        return (
+            "CryptoInput\n"
+            f"  kind: {self.kind}\n"
+            f"  size: {self.size} bytes\n"
+            f"  hash: {self.content_hash[:12]}\n"
+            f"  metadata keys: {metadata_keys}"
+        )
 
     @classmethod
     def from_string(

{utilitz-0.9.2 → utilitz-0.9.4}/src/utilitz/crypto/output.py

@@ -78,13 +78,12 @@ class CryptoOutput:
         return path
 
     def __repr__(self) -> str:
-        return (
-            f"CryptoOutput(size={self.size}, "
-            f"created_at={self.created_at.isoformat()!r}, "
-            f"content_hash={self.content_hash!r})"
-        )
+        return f"CryptoOutput(size={self.size}, hash={self.content_hash[:12]!r})"
 
     def __str__(self) -> str:
         return (
-            f"CryptoOutput<{self.size} bytes, hash={self.content_hash[:12]}>"
+            "CryptoOutput\n"
+            f"  size: {self.size} bytes\n"
+            f"  created_at: {self.created_at.isoformat()}\n"
+            f"  hash: {self.content_hash[:12]}"
         )

{utilitz-0.9.2 → utilitz-0.9.4}/src/utilitz/sys.py

@@ -16,7 +16,7 @@ from datetime import datetime
 import time
 
 
-class MonitorActivity:
+class MonitorActivity:
 
     def __init__(self):
         _check_gui()
@@ -50,9 +50,24 @@ class MonitorActivity:
         self._keyboard_listener.start()
         self._mouse_listener.start()
 
-    def stop(self):
-        self._keyboard_listener.stop()
-        self._mouse_listener.stop()
+    def stop(self):
+        self._keyboard_listener.stop()
+        self._mouse_listener.stop()
+
+    @property
+    def inactive_seconds(self):
+        return time.monotonic() - self.last_activity_time
+
+    def __repr__(self):
+        return f"MonitorActivity(inactive_seconds={self.inactive_seconds:.3f})"
+
+    def __str__(self):
+        return (
+            "MonitorActivity\n"
+            f"  inactive_seconds: {self.inactive_seconds:.3f}\n"
+            f"  keyboard_listener: {type(self._keyboard_listener).__name__}\n"
+            f"  mouse_listener: {type(self._mouse_listener).__name__}"
+        )
 
 
 def monitor_keep_alive(seconds, key='ctrl', verbose=1, tolerance=0.1):

{utilitz-0.9.2 → utilitz-0.9.4}/src/utilitz/windows/__init__.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from .context_menu import ContextMenu
+from .environment import UserEnvironment
 
 __all__ = [
     "ContextMenu",
+    "UserEnvironment",
 ]