go-embed-py 0.1.0__tar.gz

go_embed_py-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+_embedded.py
+*.whl
+.venv/

go_embed_py-0.1.0/LICENSE

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

go_embed_py-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: go-embed-py
+Version: 0.1.0
+Summary: Go-style file embedding for Python — embed static files into generated Python modules at build time
+Project-URL: Homepage, https://github.com/thirukguru/go-embed-py
+Project-URL: Repository, https://github.com/thirukguru/go-embed-py
+Project-URL: Issues, https://github.com/thirukguru/go-embed-py/issues
+Project-URL: Documentation, https://github.com/thirukguru/go-embed-py#readme
+Project-URL: Changelog, https://github.com/thirukguru/go-embed-py/blob/main/CHANGELOG.md
+Author-email: Thiruthanikan <thirukguru@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: assets,binary,build-tool,bundle,codegen,embed,go-embed,static
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# staticembed
+
+[![PyPI](https://img.shields.io/pypi/v/staticembed)](https://pypi.org/project/staticembed/)
+[![Python](https://img.shields.io/pypi/pyversions/staticembed)](https://pypi.org/project/staticembed/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Go-style file embedding for Python.** Embed static files into generated Python modules at build time. At runtime, everything is in-memory — zero filesystem access.
+
+```
+Go:     //go:embed schema.sql       →  var schema []byte
+Python: # staticembed: schema.sql   →  SCHEMA: bytes
+```
+
+## Why?
+
+Python has `importlib.resources` for accessing package data, but it still reads from the filesystem at runtime. If you want **true embedding** — data baked into your code as byte literals, no `open()`, no `Path`, no filesystem dependency — you need a code generation step. That's what `staticembed` does.
+
+**Use cases:**
+- SQL schemas, migrations, and queries
+- HTML/Jinja templates
+- Default config files (JSON, YAML, TOML)
+- Binary assets (icons, fonts, wasm)
+- Anything you'd `//go:embed` in Go
+
+## Install
+
+```bash
+pip install staticembed
+```
+
+## Quick Start
+
+### Option 1: One-liner API
+
+```python
+# build_embed.py — run once at build time
+from staticembed import embed_files
+
+embed_files({
+    "SCHEMA": "sql/schema.sql",
+    "TEMPLATES": "templates/*.html",
+    "CONFIG": "static/defaults.json",
+}, root_dir="assets", as_string=True)
+```
+
+Then in your application:
+
+```python
+from _embedded import SCHEMA, TEMPLATES, CONFIG
+
+print(CONFIG)  # str — zero file I/O
+```
+
+### Option 2: Go-style Directives
+
+Add `# staticembed:` comments to your source file:
+
+```python
+# app.py
+
+# staticembed: sql/schema.sql
+SCHEMA: bytes
+
+# staticembed: templates/*.html
+TEMPLATES: dict[str, bytes]
+
+# staticembed: static/config.json -> CONFIG string
+```
+
+Generate the embed module:
+
+```bash
+staticembed generate --source app.py --root assets/
+```
+
+### Option 3: CLI Only
+
+```bash
+staticembed generate \
+    --root ./assets \
+    --output _embedded.py \
+    --string \
+    -f SCHEMA=sql/schema.sql \
+       TEMPLATES="templates/*.html" \
+       CONFIG=static/config.json
+```
+
+## Directive Syntax
+
+```
+# staticembed: <glob> [-> VAR_NAME] [string] [compress]
+```
+
+| Part | Required | Description |
+|------|----------|-------------|
+| `<glob>` | Yes | File path or glob pattern |
+| `-> VAR_NAME` | No | Explicit variable name (auto-derived from filename otherwise) |
+| `string` | No | Decode as UTF-8 `str` instead of `bytes` |
+| `compress` | No | zlib compress (smaller module, tiny runtime cost) |
+
+**Annotation style** — variable name + type hint on the next line:
+
+```python
+# staticembed: sql/schema.sql
+SCHEMA: bytes
+
+# staticembed: templates/*.html
+TEMPLATES: dict[str, bytes]
+
+# staticembed: config.json
+CONFIG: str          # ← 'str' annotation enables string mode automatically
+```
+
+## Features
+
+- **Glob support**: `*.html`, `sql/**/*.sql`, `static/*`
+- **Single file → variable**, **glob → `dict[str, bytes|str]`**
+- **Compression**: `--compress` flag → zlib level 9
+- **String decode**: `--string` flag → UTF-8 `str`
+- **Binary safe**: images, fonts, wasm, protobuf — anything
+- **Manifest**: SHA-256 hashes + sizes for cache invalidation
+- **AST validation**: generated code is syntax-checked before writing
+- **Inspect mode**: preview what would be embedded without generating
+- **Zero dependencies**: stdlib only, Python 3.9+
+
+## CLI Reference
+
+```bash
+# Generate from source directives
+staticembed generate --source app.py --root ./data
+
+# Generate from CLI args
+staticembed generate -f SCHEMA=sql/*.sql CONFIG=config.json --root .
+
+# With compression
+staticembed generate -f DATA=big_file.json --compress --root .
+
+# As strings instead of bytes
+staticembed generate -f PAGES="*.html" --string --root .
+
+# Inspect (dry run)
+staticembed inspect --source app.py --root ./data
+staticembed inspect -f SCHEMA=sql/*.sql --root .
+
+# Version
+staticembed --version
+```
+
+## Integration
+
+### Makefile
+
+```makefile
+embed:
+	staticembed generate --source app.py --root assets/
+
+build: embed
+	pyinstaller --onefile app.py
+```
+
+### pyproject.toml (hatch build hook)
+
+```toml
+[tool.hatch.build.hooks.custom]
+path = "build_hooks.py"
+```
+
+```python
+# build_hooks.py
+from staticembed import embed_files
+
+embed_files({"SCHEMA": "sql/*.sql"}, root_dir="src/assets")
+```
+
+### Pre-commit / CI
+
+```yaml
+# .github/workflows/embed.yml
+- run: pip install staticembed
+- run: staticembed generate --source src/app.py --root assets/
+- run: git diff --exit-code _embedded.py  # fail if stale
+```
+
+## Go ↔ Python Comparison
+
+| Go | staticembed |
+|----|-------------|
+| `//go:embed schema.sql` | `# staticembed: schema.sql` |
+| `var schema []byte` | `SCHEMA: bytes` |
+| `//go:embed static/*` | `# staticembed: static/*` |
+| `var static embed.FS` | `STATIC: dict[str, bytes]` |
+| Compile-time | Build-time (pre-step) |
+| In binary | In generated `.py` module |
+
+## API Reference
+
+### `embed_files(file_map, root_dir=".", output="_embedded.py", compress=False, as_string=False)`
+
+One-liner API. Maps variable names to file paths/globs. Returns `Path` to the generated module.
+
+### `embed_from_source(source_path, root_dir=None, output="_embedded.py", compress=False)`
+
+Parses `# staticembed:` directives from a Python source file. Returns `Path`.
+
+### `generate(spec: EmbedSpec) -> str`
+
+Low-level: returns the generated module source as a string.
+
+### `parse_directives(source_path: Path) -> list[EmbedDirective]`
+
+Extract directives from a source file without generating.
+
+### `resolve_files(root: Path, pattern: str) -> list[tuple[str, bytes]]`
+
+Resolve a glob pattern and read matching files.
+
+## Contributing
+
+```bash
+git clone https://github.com/thirukguru/staticembed
+cd staticembed
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

go_embed_py-0.1.0/README.md

@@ -0,0 +1,228 @@
+# staticembed
+
+[![PyPI](https://img.shields.io/pypi/v/staticembed)](https://pypi.org/project/staticembed/)
+[![Python](https://img.shields.io/pypi/pyversions/staticembed)](https://pypi.org/project/staticembed/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Go-style file embedding for Python.** Embed static files into generated Python modules at build time. At runtime, everything is in-memory — zero filesystem access.
+
+```
+Go:     //go:embed schema.sql       →  var schema []byte
+Python: # staticembed: schema.sql   →  SCHEMA: bytes
+```
+
+## Why?
+
+Python has `importlib.resources` for accessing package data, but it still reads from the filesystem at runtime. If you want **true embedding** — data baked into your code as byte literals, no `open()`, no `Path`, no filesystem dependency — you need a code generation step. That's what `staticembed` does.
+
+**Use cases:**
+- SQL schemas, migrations, and queries
+- HTML/Jinja templates
+- Default config files (JSON, YAML, TOML)
+- Binary assets (icons, fonts, wasm)
+- Anything you'd `//go:embed` in Go
+
+## Install
+
+```bash
+pip install staticembed
+```
+
+## Quick Start
+
+### Option 1: One-liner API
+
+```python
+# build_embed.py — run once at build time
+from staticembed import embed_files
+
+embed_files({
+    "SCHEMA": "sql/schema.sql",
+    "TEMPLATES": "templates/*.html",
+    "CONFIG": "static/defaults.json",
+}, root_dir="assets", as_string=True)
+```
+
+Then in your application:
+
+```python
+from _embedded import SCHEMA, TEMPLATES, CONFIG
+
+print(CONFIG)  # str — zero file I/O
+```
+
+### Option 2: Go-style Directives
+
+Add `# staticembed:` comments to your source file:
+
+```python
+# app.py
+
+# staticembed: sql/schema.sql
+SCHEMA: bytes
+
+# staticembed: templates/*.html
+TEMPLATES: dict[str, bytes]
+
+# staticembed: static/config.json -> CONFIG string
+```
+
+Generate the embed module:
+
+```bash
+staticembed generate --source app.py --root assets/
+```
+
+### Option 3: CLI Only
+
+```bash
+staticembed generate \
+    --root ./assets \
+    --output _embedded.py \
+    --string \
+    -f SCHEMA=sql/schema.sql \
+       TEMPLATES="templates/*.html" \
+       CONFIG=static/config.json
+```
+
+## Directive Syntax
+
+```
+# staticembed: <glob> [-> VAR_NAME] [string] [compress]
+```
+
+| Part | Required | Description |
+|------|----------|-------------|
+| `<glob>` | Yes | File path or glob pattern |
+| `-> VAR_NAME` | No | Explicit variable name (auto-derived from filename otherwise) |
+| `string` | No | Decode as UTF-8 `str` instead of `bytes` |
+| `compress` | No | zlib compress (smaller module, tiny runtime cost) |
+
+**Annotation style** — variable name + type hint on the next line:
+
+```python
+# staticembed: sql/schema.sql
+SCHEMA: bytes
+
+# staticembed: templates/*.html
+TEMPLATES: dict[str, bytes]
+
+# staticembed: config.json
+CONFIG: str          # ← 'str' annotation enables string mode automatically
+```
+
+## Features
+
+- **Glob support**: `*.html`, `sql/**/*.sql`, `static/*`
+- **Single file → variable**, **glob → `dict[str, bytes|str]`**
+- **Compression**: `--compress` flag → zlib level 9
+- **String decode**: `--string` flag → UTF-8 `str`
+- **Binary safe**: images, fonts, wasm, protobuf — anything
+- **Manifest**: SHA-256 hashes + sizes for cache invalidation
+- **AST validation**: generated code is syntax-checked before writing
+- **Inspect mode**: preview what would be embedded without generating
+- **Zero dependencies**: stdlib only, Python 3.9+
+
+## CLI Reference
+
+```bash
+# Generate from source directives
+staticembed generate --source app.py --root ./data
+
+# Generate from CLI args
+staticembed generate -f SCHEMA=sql/*.sql CONFIG=config.json --root .
+
+# With compression
+staticembed generate -f DATA=big_file.json --compress --root .
+
+# As strings instead of bytes
+staticembed generate -f PAGES="*.html" --string --root .
+
+# Inspect (dry run)
+staticembed inspect --source app.py --root ./data
+staticembed inspect -f SCHEMA=sql/*.sql --root .
+
+# Version
+staticembed --version
+```
+
+## Integration
+
+### Makefile
+
+```makefile
+embed:
+	staticembed generate --source app.py --root assets/
+
+build: embed
+	pyinstaller --onefile app.py
+```
+
+### pyproject.toml (hatch build hook)
+
+```toml
+[tool.hatch.build.hooks.custom]
+path = "build_hooks.py"
+```
+
+```python
+# build_hooks.py
+from staticembed import embed_files
+
+embed_files({"SCHEMA": "sql/*.sql"}, root_dir="src/assets")
+```
+
+### Pre-commit / CI
+
+```yaml
+# .github/workflows/embed.yml
+- run: pip install staticembed
+- run: staticembed generate --source src/app.py --root assets/
+- run: git diff --exit-code _embedded.py  # fail if stale
+```
+
+## Go ↔ Python Comparison
+
+| Go | staticembed |
+|----|-------------|
+| `//go:embed schema.sql` | `# staticembed: schema.sql` |
+| `var schema []byte` | `SCHEMA: bytes` |
+| `//go:embed static/*` | `# staticembed: static/*` |
+| `var static embed.FS` | `STATIC: dict[str, bytes]` |
+| Compile-time | Build-time (pre-step) |
+| In binary | In generated `.py` module |
+
+## API Reference
+
+### `embed_files(file_map, root_dir=".", output="_embedded.py", compress=False, as_string=False)`
+
+One-liner API. Maps variable names to file paths/globs. Returns `Path` to the generated module.
+
+### `embed_from_source(source_path, root_dir=None, output="_embedded.py", compress=False)`
+
+Parses `# staticembed:` directives from a Python source file. Returns `Path`.
+
+### `generate(spec: EmbedSpec) -> str`
+
+Low-level: returns the generated module source as a string.
+
+### `parse_directives(source_path: Path) -> list[EmbedDirective]`
+
+Extract directives from a source file without generating.
+
+### `resolve_files(root: Path, pattern: str) -> list[tuple[str, bytes]]`
+
+Resolve a glob pattern and read matching files.
+
+## Contributing
+
+```bash
+git clone https://github.com/thirukguru/staticembed
+cd staticembed
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

go_embed_py-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "go-embed-py"
+version = "0.1.0"
+description = "Go-style file embedding for Python — embed static files into generated Python modules at build time"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Thiruthanikan", email = "thirukguru@gmail.com" },
+]
+keywords = [
+    "embed",
+    "static",
+    "assets",
+    "codegen",
+    "build-tool",
+    "go-embed",
+    "bundle",
+    "binary",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/thirukguru/go-embed-py"
+Repository = "https://github.com/thirukguru/go-embed-py"
+Issues = "https://github.com/thirukguru/go-embed-py/issues"
+Documentation = "https://github.com/thirukguru/go-embed-py#readme"
+Changelog = "https://github.com/thirukguru/go-embed-py/blob/main/CHANGELOG.md"
+
+[project.scripts]
+staticembed = "staticembed._cli:main"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/staticembed/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/staticembed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]

go_embed_py-0.1.0/src/staticembed/__init__.py

@@ -0,0 +1,48 @@
+"""
+staticembed — Go-style file embedding for Python.
+
+Embed static files into generated Python modules at build time.
+At runtime, everything is in-memory — zero filesystem access.
+
+Quick start::
+
+    from staticembed import embed_files
+
+    embed_files({
+        "SCHEMA": "sql/schema.sql",
+        "TEMPLATES": "templates/*.html",
+    })
+
+Go equivalent mapping::
+
+    //go:embed schema.sql          →  # staticembed: schema.sql
+    //go:embed static/*            →  # staticembed: static/*
+    //go:embed templates/*.html    →  # staticembed: templates/*.html
+"""
+
+from __future__ import annotations
+
+from staticembed._core import (
+    EmbedDirective,
+    EmbedEntry,
+    EmbedSpec,
+    embed_files,
+    embed_from_source,
+    generate,
+    parse_directives,
+    resolve_files,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EmbedDirective",
+    "EmbedEntry",
+    "EmbedSpec",
+    "embed_files",
+    "embed_from_source",
+    "generate",
+    "parse_directives",
+    "resolve_files",
+    "__version__",
+]

go_embed_py-0.1.0/src/staticembed/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running as: python -m staticembed"""
+
+import sys
+
+from staticembed._cli import main
+
+sys.exit(main())

go_embed_py-0.1.0/src/staticembed/_cli.py

@@ -0,0 +1,156 @@
+"""CLI for staticembed.
+
+Usage::
+
+    # From directives in source file
+    staticembed generate --source app.py --root assets/
+
+    # From CLI arguments
+    staticembed generate -f SCHEMA=sql/schema.sql TEMPLATES="templates/*.html"
+
+    # Inspect without generating
+    staticembed inspect --source app.py --root assets/
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from staticembed._core import (
+    embed_files,
+    embed_from_source,
+    parse_directives,
+    resolve_files,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``staticembed`` CLI."""
+    parser = argparse.ArgumentParser(
+        prog="staticembed",
+        description="Go-style file embedding for Python",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {_get_version()}",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # --- generate ---
+    gen = sub.add_parser("generate", help="Generate embedded Python module")
+    gen.add_argument(
+        "--source", "-s",
+        help="Source file containing # staticembed: directives",
+    )
+    gen.add_argument("--root", "-r", default=".", help="Root directory for file resolution")
+    gen.add_argument("--output", "-o", default="_embedded.py", help="Output module path")
+    gen.add_argument("--compress", "-z", action="store_true", help="Compress with zlib")
+    gen.add_argument("--string", action="store_true", help="Decode as UTF-8 strings")
+    gen.add_argument(
+        "--files", "-f",
+        nargs="+",
+        metavar="VAR=GLOB",
+        help="Embed files: VAR_NAME=path/glob (e.g. SCHEMA=sql/*.sql)",
+    )
+
+    # --- inspect ---
+    insp = sub.add_parser("inspect", help="Show what would be embedded (dry run)")
+    insp.add_argument("--source", "-s", help="Source file with directives")
+    insp.add_argument("--root", "-r", default=".", help="Root directory")
+    insp.add_argument("--files", "-f", nargs="+", metavar="VAR=GLOB")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "generate":
+        return _cmd_generate(args, parser)
+    elif args.command == "inspect":
+        return _cmd_inspect(args, parser)
+    else:
+        parser.print_help()
+        return 0
+
+
+def _cmd_generate(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
+    if args.source:
+        out = embed_from_source(args.source, args.root, args.output, args.compress)
+        print(f"Generated {out} from directives in {args.source}")
+        return 0
+
+    if args.files:
+        file_map = _parse_file_args(args.files, parser)
+        out = embed_files(file_map, args.root, args.output, args.compress, args.string)
+        print(f"Generated {out} with {len(file_map)} embed(s)")
+        return 0
+
+    parser.error("Provide --source or --files")
+    return 1  # unreachable
+
+
+def _cmd_inspect(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
+    root = Path(args.root).resolve()
+    total_files = 0
+    total_bytes = 0
+
+    if args.source:
+        directives = parse_directives(Path(args.source))
+        if not directives:
+            print(f"No staticembed directives found in {args.source}")
+            return 1
+        print(f"Directives in {args.source}:\n")
+        for d in directives:
+            files = resolve_files(root, d.pattern)
+            flags = []
+            if d.as_string:
+                flags.append("string")
+            if d.compress:
+                flags.append("compress")
+            flag_str = f" [{', '.join(flags)}]" if flags else ""
+            print(f"  {d.var_name} <- {d.pattern}{flag_str}  ({len(files)} file(s))")
+            for rel, data in files:
+                print(f"    {rel}  ({len(data):,} bytes)")
+                total_files += 1
+                total_bytes += len(data)
+
+    elif args.files:
+        file_map = _parse_file_args(args.files, parser)
+        for var, glob in file_map.items():
+            files = resolve_files(root, glob)
+            print(f"  {var} <- {glob}  ({len(files)} file(s))")
+            for rel, data in files:
+                print(f"    {rel}  ({len(data):,} bytes)")
+                total_files += 1
+                total_bytes += len(data)
+    else:
+        parser.error("Provide --source or --files")
+        return 1
+
+    print(f"\nTotal: {total_files} file(s), {total_bytes:,} bytes")
+    return 0
+
+
+def _parse_file_args(
+    items: list[str], parser: argparse.ArgumentParser
+) -> dict[str, str]:
+    file_map: dict[str, str] = {}
+    for item in items:
+        var, sep, glob = item.partition("=")
+        if not sep or not glob:
+            parser.error(f"Invalid format: {item!r} (expected VAR=GLOB)")
+        file_map[var.strip()] = glob.strip()
+    return file_map
+
+
+def _get_version() -> str:
+    try:
+        from staticembed import __version__
+
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+if __name__ == "__main__":
+    sys.exit(main())

go_embed_py-0.1.0/src/staticembed/_core.py

@@ -0,0 +1,378 @@
+"""Core embedding engine for staticembed."""
+
+from __future__ import annotations
+
+import ast
+import base64
+import hashlib
+import json
+import re
+import zlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EmbedEntry:
+    """A single embedded file with metadata."""
+
+    name: str
+    path: str
+    data: bytes
+    size: int = 0
+    sha256: str = ""
+
+    def __post_init__(self) -> None:
+        self.size = len(self.data)
+        self.sha256 = hashlib.sha256(self.data).hexdigest()
+
+
+@dataclass
+class EmbedDirective:
+    """Parsed from source file ``# staticembed:`` comments."""
+
+    var_name: str
+    pattern: str
+    as_string: bool = False
+    compress: bool = False
+    line_number: int = 0
+
+
+@dataclass
+class EmbedSpec:
+    """Complete specification for a code generation run."""
+
+    root_dir: Path
+    output_path: Path
+    directives: list[EmbedDirective] = field(default_factory=list)
+    file_map: dict[str, str] = field(default_factory=dict)
+    compress: bool = False
+    as_string: bool = False
+    banner: str = "# AUTO-GENERATED by staticembed — do not edit"
+
+
+# ---------------------------------------------------------------------------
+# Directive parser
+# ---------------------------------------------------------------------------
+
+_DIRECTIVE_RE = re.compile(
+    r"^\s*#\s*staticembed:\s*"
+    r"(?P<pattern>[^\s#]+)"
+    r"(?:\s*->\s*(?P<var>[A-Za-z_][A-Za-z0-9_]*))?"
+    r"(?P<flags>(?:\s+(?:string|compress))*)"
+    r"\s*$"
+)
+
+
+def parse_directives(source_path: Path) -> list[EmbedDirective]:
+    """Extract ``# staticembed:`` directives from a Python source file.
+
+    Supports two styles:
+
+    **Style 1 — inline (Go-like)**::
+
+        # staticembed: sql/schema.sql
+        # staticembed: templates/*.html -> TEMPLATES
+        # staticembed: config.json string compress
+
+    **Style 2 — comment + annotation on next line**::
+
+        # staticembed: sql/schema.sql
+        SCHEMA: bytes
+
+        # staticembed: templates/*.html
+        TEMPLATES: dict[str, bytes]
+    """
+    directives: list[EmbedDirective] = []
+    lines = source_path.read_text(encoding="utf-8").splitlines()
+
+    i = 0
+    while i < len(lines):
+        m = _DIRECTIVE_RE.match(lines[i])
+        if m:
+            pattern = m.group("pattern")
+            var_name = m.group("var")
+            flags = m.group("flags") or ""
+            as_string = "string" in flags
+            compress = "compress" in flags
+
+            # Check next line for annotation-style var name
+            if not var_name and i + 1 < len(lines):
+                next_line = lines[i + 1].strip()
+                ann_match = re.match(r"^([A-Za-z_][A-Za-z0-9_]*)\s*:", next_line)
+                if ann_match:
+                    var_name = ann_match.group(1)
+                    if "str" in next_line and "bytes" not in next_line:
+                        as_string = True
+                    i += 1
+
+            if not var_name:
+                var_name = _path_to_var(pattern)
+
+            directives.append(
+                EmbedDirective(
+                    var_name=var_name,
+                    pattern=pattern,
+                    as_string=as_string,
+                    compress=compress,
+                    line_number=i + 1,
+                )
+            )
+        i += 1
+
+    return directives
+
+
+def _path_to_var(pattern: str) -> str:
+    """Convert a file path/glob to a valid Python variable name."""
+    name = Path(pattern).stem
+    name = re.sub(r"[^A-Za-z0-9]", "_", name)
+    name = name.strip("_").upper()
+    if name and name[0].isdigit():
+        name = "_" + name
+    return name or "_EMBED"
+
+
+# ---------------------------------------------------------------------------
+# File resolver
+# ---------------------------------------------------------------------------
+
+def resolve_files(root: Path, pattern: str) -> list[tuple[str, bytes]]:
+    """Resolve a glob pattern relative to *root*.
+
+    Returns a sorted list of ``(relative_path, content)`` pairs.
+    """
+    matches = sorted(root.glob(pattern))
+    results: list[tuple[str, bytes]] = []
+    for p in matches:
+        if p.is_file():
+            rel = p.relative_to(root)
+            results.append((str(rel), p.read_bytes()))
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Code generator
+# ---------------------------------------------------------------------------
+
+def generate(spec: EmbedSpec) -> str:
+    """Generate a Python module containing all embedded data.
+
+    Returns the module source code as a string.
+    """
+    lines: list[str] = [
+        spec.banner,
+        '"""Embedded assets generated by staticembed."""',
+        "",
+        "from __future__ import annotations",
+        "",
+        "import base64 as _b64",
+    ]
+
+    needs_zlib = spec.compress or any(d.compress for d in spec.directives)
+    if needs_zlib:
+        lines.append("import zlib as _zlib")
+
+    lines.append("")
+
+    entries: list[EmbedEntry] = []
+
+    # Process directives (from source file parsing)
+    for directive in spec.directives:
+        _generate_for_pattern(
+            lines=lines,
+            entries=entries,
+            root=spec.root_dir,
+            var_name=directive.var_name,
+            pattern=directive.pattern,
+            compress=directive.compress or spec.compress,
+            as_string=directive.as_string or spec.as_string,
+        )
+
+    # Process file_map (programmatic API)
+    for var_name, pattern in spec.file_map.items():
+        _generate_for_pattern(
+            lines=lines,
+            entries=entries,
+            root=spec.root_dir,
+            var_name=var_name,
+            pattern=pattern,
+            compress=spec.compress,
+            as_string=spec.as_string,
+        )
+
+    # Manifest
+    manifest = {
+        entry.path: {"size": entry.size, "sha256": entry.sha256}
+        for entry in entries
+    }
+    lines.append("# Embed manifest (for cache invalidation / debugging)")
+    lines.append(f"_MANIFEST: dict = {json.dumps(manifest, indent=2)}")
+    lines.append("")
+
+    source = "\n".join(lines)
+
+    # Validate syntax
+    try:
+        ast.parse(source)
+    except SyntaxError as e:
+        raise RuntimeError(f"staticembed: generated invalid Python: {e}") from e
+
+    return source
+
+
+def _generate_for_pattern(
+    *,
+    lines: list[str],
+    entries: list[EmbedEntry],
+    root: Path,
+    var_name: str,
+    pattern: str,
+    compress: bool,
+    as_string: bool,
+) -> None:
+    """Generate code for a single variable/pattern pair."""
+    files = resolve_files(root, pattern)
+
+    if not files:
+        lines.append(f"# WARNING: no files matched pattern '{pattern}'")
+        lines.append("")
+        return
+
+    is_glob = "*" in pattern or "?" in pattern
+    type_name = "str" if as_string else "bytes"
+
+    if is_glob or len(files) > 1:
+        lines.append(f"# Embedded from: {pattern}")
+        lines.append(f"{var_name}: dict[str, {type_name}] = {{")
+        for rel_path, data in files:
+            entries.append(EmbedEntry(name=rel_path, path=rel_path, data=data))
+            encoded = _encode_data(data, compress)
+            accessor = _decode_expr(encoded, compress, as_string)
+            lines.append(f"    {rel_path!r}: {accessor},")
+        lines.append("}")
+    else:
+        rel_path, data = files[0]
+        entries.append(EmbedEntry(name=var_name, path=rel_path, data=data))
+        encoded = _encode_data(data, compress)
+        accessor = _decode_expr(encoded, compress, as_string)
+        lines.append(f"# Embedded from: {rel_path}")
+        lines.append(f"{var_name}: {type_name} = {accessor}")
+
+    lines.append("")
+
+
+def _encode_data(data: bytes, compress: bool) -> str:
+    if compress:
+        data = zlib.compress(data, level=9)
+    return base64.b64encode(data).decode("ascii")
+
+
+def _decode_expr(encoded: str, compress: bool, as_string: bool) -> str:
+    if len(encoded) > 76:
+        chunks = [encoded[i : i + 76] for i in range(0, len(encoded), 76)]
+        b64_literal = (
+            "(\n        " + "\n        ".join(f'"{c}"' for c in chunks) + "\n    )"
+        )
+    else:
+        b64_literal = f'"{encoded}"'
+
+    expr = f"_b64.b64decode({b64_literal})"
+
+    if compress:
+        expr = f"_zlib.decompress({expr})"
+
+    if as_string:
+        expr = f"({expr}).decode('utf-8')"
+
+    return expr
+
+
+# ---------------------------------------------------------------------------
+# Convenience API
+# ---------------------------------------------------------------------------
+
+def embed_files(
+    file_map: dict[str, str],
+    root_dir: str | Path = ".",
+    output: str | Path = "_embedded.py",
+    compress: bool = False,
+    as_string: bool = False,
+) -> Path:
+    """Embed files into a generated Python module.
+
+    Args:
+        file_map: Mapping of ``{"VAR_NAME": "path/or/glob", ...}``.
+        root_dir: Base directory for resolving file paths.
+        output: Path for the generated module.
+        compress: Compress data with zlib (smaller output, tiny runtime cost).
+        as_string: Decode embedded data as UTF-8 ``str`` instead of ``bytes``.
+
+    Returns:
+        Path to the generated module file.
+
+    Example::
+
+        from staticembed import embed_files
+
+        embed_files({
+            "SCHEMA": "sql/schema.sql",
+            "TEMPLATES": "templates/*.html",
+            "CONFIG": "static/defaults.json",
+        }, as_string=True)
+    """
+    root = Path(root_dir).resolve()
+    out = Path(output)
+
+    spec = EmbedSpec(
+        root_dir=root,
+        output_path=out,
+        file_map=file_map,
+        compress=compress,
+        as_string=as_string,
+    )
+
+    source = generate(spec)
+    out.write_text(source, encoding="utf-8")
+    return out
+
+
+def embed_from_source(
+    source_path: str | Path,
+    root_dir: Optional[str | Path] = None,
+    output: str | Path = "_embedded.py",
+    compress: bool = False,
+) -> Path:
+    """Parse ``# staticembed:`` directives from a source file and generate the embed module.
+
+    Args:
+        source_path: Python file containing ``# staticembed:`` directives.
+        root_dir: Base directory (defaults to source file's parent).
+        output: Path for the generated module.
+        compress: Compress all embedded data.
+
+    Returns:
+        Path to the generated module file.
+    """
+    src = Path(source_path).resolve()
+    root = Path(root_dir).resolve() if root_dir else src.parent
+
+    directives = parse_directives(src)
+    if not directives:
+        raise ValueError(f"No staticembed directives found in {src}")
+
+    spec = EmbedSpec(
+        root_dir=root,
+        output_path=Path(output),
+        directives=directives,
+        compress=compress,
+    )
+
+    source = generate(spec)
+    Path(output).write_text(source, encoding="utf-8")
+    return Path(output)