utfbundle 0.1.0__py3-none-any.whl

utfbundle-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: utfbundle
+Version: 0.1.0
+Summary: Pack a directory of text files into one self-extracting Python script, and unpack it back.
+Project-URL: Homepage, https://github.com/griffijf/utfbundle
+Project-URL: Issues, https://github.com/griffijf/utfbundle/issues
+Author-email: Jeff Griffin <pypi@brainslugsolutions.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: archive,bundle,cli,directory,self-extracting,text
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: pathspec
+Description-Content-Type: text/markdown
+
+# utfbundle
+
+Packs a directory of text files into a single Python script, and unpacks
+it back into an identical directory tree.
+
+Some workflows only accept a single file, or a single block of pasted
+text (a chat window, a text box in a web tool, a single attachment
+field). If what you want to share is actually a small directory of files 
+that's unwieldy: pasting each file in separately loses the directory 
+structure, and a zip file isn't always usable in a text-only context
+or readable in aggregate.
+
+`utfbundle` writes a directory's contents into one `.py` file, with
+each original file's path and content stored inside it as plain text
+where possible, or base64 for anything that isn't valid UTF-8. Running
+that file writes every file back out, unchanged, to a directory of your
+choosing. Packing and unpacking are inverses.  Files come back out
+byte-for-byte identical, whichever form they were stored in.
+
+Not intended to be a general-purpose archiver. No compression, no 
+encryption. `tar` or `zip` already cover those use cases. This is 
+specifically for the case where the constraint is "one plain text file,
+exactly reversible" including directories that have a few binary files 
+mixed in with the text.
+
+## Install
+
+```bash
+pip install utfbundle
+```
+
+This installs the `utfbundle` command (and pulls in `pathspec` as a
+dependency automatically).
+
+## Requirements
+
+- Python 3.8+
+- [`pathspec`](https://pypi.org/project/pathspec/) (installed automatically with the package above; `pip install pathspec` if running from source)
+
+## Quick start
+
+Pack the current directory:
+
+```bash
+[python3] utfbundle
+```
+
+This writes `<dirname>_bundle.py` in the current directory.
+
+Reconstruct the tree later by running the bundle:
+
+```bash
+python3 <dirname>_bundle.py
+```
+
+With no arguments, it writes back into `.`. Packing `.` and running the
+resulting bundle from the same location are complements. Pass a path to
+extract elsewhere instead:
+
+```bash
+python3 <dirname>_bundle.py /path/to/restore/into
+```
+
+You can also pack a specific directory rather than the current one:
+
+```bash
+[python3] utfbundle path/to/project -o project_bundle.py
+```
+
+Here, since a named directory was packed rather than `.`, the bundle's
+default destination is a subdirectory named after it.  Running
+`project_bundle.py` with no arguments elsewhere recreates
+`path/to/project/` as `project/`.
+
+## Choosing what's included: `.bundlespec`
+
+By default, packing includes everything except common junk (`.git/`,
+`node_modules/`, `target/`, `__pycache__/`, `.DS_Store`, prior bundle
+files). To control this directly, add a `.bundlespec` file at the root
+of the directory you're packing.
+
+The syntax is `.gitignore`'s glob syntax, inverted. A
+`.gitignore` excludes by default, so a bare line excludes and `!`
+re-includes. A `.bundlespec` includes by default, so a bare line
+**includes**, and `!` **excludes** something an earlier line already
+matched:
+
+```
+# what to bundle
+src/**
+assets/**
+Cargo.toml
+
+# exceptions
+!target/
+!node_modules/
+!*.log
+!secrets.rs
+```
+
+Rules apply top to bottom; the last matching rule for a given path wins.
+List broad includes first, then narrow with `!`.
+
+## Command-line reference
+
+```
+[python3] utfbundle [src_dir] [-o bundle.py] [-s SPEC] [-p PATTERN ...] [-n NAME]
+```
+
+| Flag | Meaning |
+|---|---|
+| `src_dir` | Directory to pack. Defaults to `.` |
+| `-o, --output` | Output bundle path. Defaults to `<name>_bundle.py` |
+| `-s, --spec` | Path to a patterns file. Defaults to `<src_dir>/.bundlespec` if present |
+| `-p, --pattern` | An extra pattern, may be repeated; applied after the spec file |
+| `-n, --project-name` | Name used for the bundle file and default extract destination |
+
+## Limitations
+
+- **Binary files are supported, but not free.** Each file is read as
+  UTF-8 text; if that fails, it's stored instead as base64 inside the
+  bundle (and a note is printed to stderr) and decoded back to exact
+  bytes on extract. Either way the round-trip is exact, but base64
+  content isn't meant to be read by eye the way the text entries are,
+  and it inflates that file's size by roughly a third.
+- **No secret-scanning.** It bundles whatever the patterns match. Keep
+  credentials and `.env` files out via `.bundlespec`, the same way you
+  would for a commit.
+- **No compression.** Bundle size is roughly the sum of the included
+  files' sizes (plus the base64 overhead on any binary files).
+- **Non-UTF-8 text is treated as binary.** A file in Latin-1,
+  Windows-1252, UTF-16, etc. will fail the UTF-8 decode check and get
+  stored as base64 rather than as a readable literal. It still
+  round-trips exactly.  This only affects whether it's human-readable
+  inside the bundle file.
+
+## License
+
+MIT

utfbundle-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+utfbundle.py,sha256=RP9Nq_lh4skxwWiDEzKMF_9B0bZhIwRBa0WMb9uiG_Q,12102
+utfbundle-0.1.0.dist-info/METADATA,sha256=tYRZqOyd_DaeXdc6eJvjP0-ybciIf62wk5mWEE-kw2o,5547
+utfbundle-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+utfbundle-0.1.0.dist-info/entry_points.txt,sha256=Q_Amnl9ZDHqalGTd1aGHrH2lTqUBnfJToUozz075ngI,45
+utfbundle-0.1.0.dist-info/licenses/LICENSE,sha256=E8BWYWZHaRzL6TqhGZ1qRgNaD_1nY6A_DFuV8LVH8FA,1069
+utfbundle-0.1.0.dist-info/RECORD,,

utfbundle-0.1.0.dist-info/WHEEL

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

utfbundle-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+utfbundle = utfbundle:main

utfbundle-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Griffin
+
+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.

utfbundle.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""
+utfbundle   
+Build a self-extracting bundle script from a source directory tree.
+
+The bundle it produces is a drop-in sibling of tectonos_bevy_extract.py:
+a FILES = [(relative_path, kind, content), ...] list plus an extract()
+function, so it can be uploaded as a single plaintext file, or run with 
+`python3 bundle.py [dest]` to recreate the tree. `kind` is "text" for 
+UTF-8-decodable files (content stored as a readable string literal) 
+or "b64" for anything else (content stored as base64, decoded losslessly 
+on extract).
+
+Requires: pip install pathspec
+
+------------------------------------------------------------------------
+USAGE
+------------------------------------------------------------------------
+  [python3] utfbundle [src_dir] [-o bundle.py] [-s SPEC] [-p PATTERN ...] [-n NAME]
+
+  src_dir            Directory to pack (default: current directory)
+  -o, --output       Output bundle path (default: <src_dir_name>_bundle.py)
+  -s, --spec         Patterns file (default: <src_dir>/.bundlespec if present)
+  -p, --pattern      Extra pattern, may be repeated; applied after the spec
+  -n, --project-name Name for the bundle file/dest (default: src_dir's name)
+
+------------------------------------------------------------------------
+PATTERN SYNTAX (gitignore glob syntax, inverted)
+------------------------------------------------------------------------
+A .gitignore's job is to exclude, so a bare pattern there excludes and
+`!` re-includes. A .bundlespec's job is the opposite — to say what to
+include: a bare pattern INCLUDES, and `!` EXCLUDES a match that an 
+earlier pattern already included.
+
+  src/**              include everything under src/
+  *.rs                include any .rs file anywhere
+  Cargo.toml           include this file at the root
+  !src/**/*.test.rs   exclude test files a broader include pulled in
+  !target/            exclude a directory entirely, even if some
+                       other pattern would include it
+
+Every file starts EXCLUDED. Rules apply top to bottom — spec file first,
+then --pattern flags in order — and the last match wins, so list broad
+includes first and narrow them with `!` afterward.
+
+If no .bundlespec is found and no -s is given, the default is:
+  **
+  !.git/
+  !__pycache__/
+  !*.pyc
+  !target/
+  !node_modules/
+  !.DS_Store
+  !*_bundle.py
+i.e. "include everything except common junk."
+"""
+
+__version__ = "0.1.0"
+
+import argparse
+import base64
+import os
+import sys
+
+from pathspec.patterns.gitwildmatch import GitIgnoreSpecPattern
+
+DEFAULT_PATTERNS = [
+    "**",
+    "!.git/",
+    "!__pycache__/",
+    "!*.pyc",
+    "!target/",
+    "!node_modules/",
+    "!.DS_Store",
+    "!*_bundle.py",
+]
+
+
+class Pattern:
+    """One line of a .bundlespec.
+
+    Wraps pathspec's gitignore-glob compiler. Its `.include` flag maps
+    directly onto our inversion: pathspec sets `include=True` for
+    a normal (unprefixed) pattern and `False` for a `!`-prefixed one —
+    exactly our own bare=include, `!`=exclude scheme — so
+    `self.exclude = not compiled.include` is the entire adapter.
+    """
+
+    def __init__(self, raw):
+        self.raw = raw.rstrip("\n")
+        compiled = GitIgnoreSpecPattern(self.raw)
+        self.exclude = not compiled.include
+        self._regex = compiled.regex
+
+    def matches(self, relpath):
+        return self._regex is not None and self._regex.match(relpath) is not None
+
+
+def load_patterns(spec_path, extra_patterns):
+    patterns = []
+    if spec_path and os.path.isfile(spec_path):
+        with open(spec_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                patterns.append(Pattern(line))
+    elif spec_path is None:
+        patterns = [Pattern(line) for line in DEFAULT_PATTERNS]
+    patterns += [Pattern(p) for p in (extra_patterns or [])]
+    return patterns
+
+
+def is_included(relpath, patterns):
+    """Every path starts excluded; the last matching pattern decides."""
+    included = False
+    for pat in patterns:
+        if pat.matches(relpath):
+            included = not pat.exclude
+    return included
+
+
+def dir_is_hard_excluded(rel_dir, patterns):
+    """Whether to prune a directory from the walk entirely.
+
+    Since the default state is "excluded", we can't prune on "not
+    included" — an unmatched directory may still contain files a later
+    include pattern pulls in. We only prune when a pattern explicitly
+    EXCLUDES the directory itself (a `!some/dir/`-style rule).
+    """
+    excluded = False
+    for pat in patterns:
+        if pat.matches(rel_dir) or pat.matches(rel_dir + "/"):
+            excluded = pat.exclude
+    return excluded
+
+
+def collect_files(src_dir, patterns):
+    """Return sorted list of relative (posix-style) file paths to include."""
+    results = []
+    for root, dirs, files in os.walk(src_dir):
+        rel_root = os.path.relpath(root, src_dir)
+        rel_root = "" if rel_root == "." else rel_root.replace(os.sep, "/")
+
+        kept_dirs = []
+        for d in dirs:
+            rel_d = f"{rel_root}/{d}" if rel_root else d
+            if not dir_is_hard_excluded(rel_d, patterns):
+                kept_dirs.append(d)
+        dirs[:] = kept_dirs
+
+        for fname in files:
+            rel_f = f"{rel_root}/{fname}" if rel_root else fname
+            if is_included(rel_f, patterns):
+                results.append(rel_f)
+    return sorted(results)
+
+
+def encode_file_literal(content):
+    """Render `content` as a Python string literal for the bundle.
+
+    Prefers a readable triple-double-quoted block (backslashes escaped so
+    the extracted bytes are exact). Falls back to repr() if the content
+    contains a triple-quote or ends in a bare double-quote, either of
+    which would break the block form.
+    """
+    if '"""' in content or content.rstrip("\n").endswith('"'):
+        return repr(content)
+    escaped = content.replace("\\", "\\\\")
+    return '"""\\\n' + escaped + '"""'
+
+
+BUNDLE_HEADER = '''#!/usr/bin/env python3
+"""
+{bundle_name}
+Self-extracting bundle for {project_name}.
+
+Usage:
+  python3 {bundle_name}            # extract into {default_dest_display}
+  python3 {bundle_name} <dest>     # extract into <dest>/
+
+Generated by utfbundle. Text files are stored as plain string literals
+between delimiters. Files that aren't valid UTF-8 are stored as base64 instead ("b64"
+kind) and decoded losslessly on extract, in addition to running this
+script to recreate the tree on disk.
+"""
+
+import base64, os, sys
+
+# ===========================================================================
+# FILE BUNDLE
+# Each entry: (relative_path, kind, content)
+#   kind "text" -> content is the file's exact text, ready to write as-is
+#   kind "b64"  -> content is base64; decode to bytes before writing
+# ===========================================================================
+
+FILES = [
+'''
+
+BUNDLE_FOOTER = ''']
+
+# ===========================================================================
+# EXTRACTOR
+# ===========================================================================
+
+def extract(dest={default_dest_repr}):
+    for rel_path, kind, content in FILES:
+        out = os.path.join(dest, rel_path)
+        os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+        if kind == "text":
+            with open(out, 'w', encoding='utf-8') as f:
+                f.write(content)
+        else:
+            with open(out, 'wb') as f:
+                f.write(base64.b64decode(content))
+        print(f'  wrote {{out}}')
+    print(f'Done. {{len(FILES)}} files extracted to {{dest!r}}.')
+
+if __name__ == '__main__':
+    dest = sys.argv[1] if len(sys.argv) > 1 else {default_dest_repr}
+    extract(dest)
+'''
+
+
+def write_bundle(out_path, project_name, default_dest, files_with_content):
+    bundle_name = os.path.basename(out_path)
+    default_dest_display = "./" if default_dest == "." else f"./{default_dest}/"
+    with open(out_path, "w", encoding="utf-8") as out:
+        out.write(
+            BUNDLE_HEADER.format(
+                bundle_name=bundle_name,
+                project_name=project_name,
+                default_dest_display=default_dest_display,
+            )
+        )
+        for rel_path, kind, content in files_with_content:
+            out.write("    # " + "-" * 72 + "\n")
+            out.write(f"    # {rel_path} ({kind})\n")
+            out.write("    # " + "-" * 72 + "\n")
+            out.write("    (\n")
+            out.write(f"        {rel_path!r},\n")
+            out.write(f"        {kind!r},\n")
+            if kind == "text":
+                literal = encode_file_literal(content)
+                # Only the opening marker gets indented — the rest of
+                # `literal` is the literal string *value* (it may contain
+                # real newlines from the line-continuation trick), so it
+                # must not be reindented line-by-line or the indentation
+                # would become part of the extracted file's content.
+                out.write("        " + literal)
+            else:  # "b64" — plain repr is fine, it's just an ascii string
+                out.write("        " + repr(content))
+            out.write(",\n    ),\n\n")
+        out.write(BUNDLE_FOOTER.format(default_dest_repr=repr(default_dest)))
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("src_dir", nargs="?", default=".", help="Directory to pack (default: current directory)")
+    ap.add_argument("-o", "--output", help="Output bundle path (default: <src_dir_name>_bundle.py)")
+    ap.add_argument("-s", "--spec", help="Patterns file (default: <src_dir>/.bundlespec if present)")
+    ap.add_argument("-p", "--pattern", action="append", default=[], help="Extra pattern, may be repeated")
+    ap.add_argument("-n", "--project-name", help="Name for the bundle file/dest (default: src_dir's name)")
+    args = ap.parse_args()
+
+    src_dir = os.path.abspath(args.src_dir)
+    if not os.path.isdir(src_dir):
+        print(f"error: not a directory: {src_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    project_name = args.project_name or os.path.basename(src_dir.rstrip("/")) or "bundle"
+
+    # Pack and extract are complements: `utfbundle` with no args packs
+    # the current directory, so running the resulting bundle with no args
+    # writes straight back into the current directory, not a subdirectory
+    # one level deeper. Only default to a named subdirectory when a
+    # *specific* directory (other than cwd) was packed.
+    default_dest = "." if src_dir == os.path.abspath(".") else project_name
+    out_path = args.output or f"{project_name}_bundle.py"
+
+    spec_path = args.spec
+    if spec_path is None:
+        candidate = os.path.join(src_dir, ".bundlespec")
+        spec_path = candidate if os.path.isfile(candidate) else None
+
+    patterns = load_patterns(spec_path, args.pattern)
+    rel_files = collect_files(src_dir, patterns)
+
+    if not rel_files:
+        print("warning: no files matched — check your patterns", file=sys.stderr)
+
+    files_with_content = []
+    for rel in rel_files:
+        abs_path = os.path.join(src_dir, rel)
+        try:
+            with open(abs_path, "r", encoding="utf-8") as f:
+                content = f.read()
+            files_with_content.append((rel, "text", content))
+        except UnicodeDecodeError:
+            print(f"stored as binary (not valid UTF-8): {rel}", file=sys.stderr)
+            with open(abs_path, "rb") as f:
+                raw = f.read()
+            content = base64.b64encode(raw).decode("ascii")
+            files_with_content.append((rel, "b64", content))
+
+    write_bundle(out_path, project_name, default_dest, files_with_content)
+    print(f"Packed {len(files_with_content)} files from {src_dir!r} into {out_path!r}.")
+    print(f"  running the bundle with no args extracts into: {default_dest!r}")
+    print(f"  using spec: {spec_path}" if spec_path else "  using built-in default patterns (no .bundlespec found)")
+
+
+if __name__ == "__main__":
+    main()