prompt-comments 0.1.0__tar.gz

prompt_comments-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -v

prompt_comments-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

prompt_comments-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+.DS_Store
+.vscode/
+.idea/
+coverage.xml
+.coverage

prompt_comments-0.1.0/LICENSE

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

prompt_comments-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: prompt-comments
+Version: 0.1.0
+Summary: Write comments in your AI prompts, strip them before they reach the model.
+Project-URL: Homepage, https://github.com/viswanathms/prompt-comments
+Project-URL: Repository, https://github.com/viswanathms/prompt-comments
+Project-URL: Issues, https://github.com/viswanathms/prompt-comments/issues
+Author: viswanathms
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,comments,jinja,llm,markdown,prompt,prompt-engineering,template
+Classifier: Development Status :: 3 - Alpha
+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 :: Only
+Classifier: Programming Language :: Python :: 3.8
+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 :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Filters
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# prompt-comments
+
+[![CI](https://github.com/viswanathms/prompt-comments/actions/workflows/ci.yml/badge.svg)](https://github.com/viswanathms/prompt-comments/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/prompt-comments.svg)](https://pypi.org/project/prompt-comments/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Write comments in your AI prompts. Strip them before they reach the model.
+
+Prompts live in Markdown files, Jinja templates, YAML configs, plain
+`.txt` files — but none of those give you a way to leave a note for
+your future self ("why is this instruction here?", "TODO: tighten
+this up") without the note leaking into the actual text sent to the
+model. `prompt-comments` strips comments in whatever format your
+prompt already uses, right before you hand the text to your LLM SDK
+of choice.
+
+```python
+from prompt_comments import strip_comments
+
+prompt = """
+You are a helpful support assistant. {# keep tone friendly, not robotic #}
+Always answer in the user's language. <!-- TODO: revisit for RTL languages -->
+"""
+
+strip_comments(prompt)
+# "\nYou are a helpful support assistant.\nAlways answer in the user's language.\n"
+```
+
+## Install
+
+```bash
+pip install prompt-comments
+```
+
+## Usage
+
+### Strip comments from a string
+
+```python
+from prompt_comments import strip_comments
+
+strip_comments("Summarize this. {# only for the 'concise' variant #}")
+# "Summarize this."
+```
+
+By default, `strip_comments` removes a small set of comment styles
+that are unlikely to collide with real prompt text: Jinja-style block
+comments (`{# ... #}`), HTML/Markdown block comments (`<!-- ... -->`),
+and `//` line comments. Pick a different (or additional) dialect for
+formats with their own conventions:
+
+```python
+strip_comments(open("system_prompt.yaml").read(), dialect="yaml")
+
+# Combine multiple dialects
+strip_comments(text, dialect=["jinja", "yaml"])
+```
+
+### Load a prompt straight from a file
+
+`load_prompt` reads a file and infers the right dialect from its
+extension automatically (`.j2`/`.jinja2` → Jinja, `.md` → Markdown,
+`.yaml` → YAML, ...):
+
+```python
+from prompt_comments import load_prompt
+
+system_prompt = load_prompt("prompts/system.md")
+```
+
+Override the inferred dialect if needed:
+
+```python
+load_prompt("prompts/system.txt", dialect="yaml")
+```
+
+### Command line
+
+```bash
+prompt-comments prompts/system.md            # auto-detects dialect from extension
+prompt-comments prompts/system.txt -d yaml    # force a dialect
+cat prompt.txt | prompt-comments -d jinja     # read from stdin
+prompt-comments --list-dialects
+```
+
+### Escaping a literal marker
+
+Prefix a line-comment marker with `\` to keep it literally instead of
+treating it as a comment:
+
+```python
+strip_comments(r"The meeting room is \#3 today", dialect="yaml")
+# "The meeting room is #3 today"
+```
+
+### Dropping now-empty lines
+
+Comments that occupied a whole line leave a blank line behind by
+default. Pass `strip_blank_lines=True` to drop them instead:
+
+```python
+strip_comments("keep\n// only a comment\nkeep too", dialect="c", strip_blank_lines=True)
+# "keep\nkeep too"
+```
+
+## Supported dialects
+
+| Dialect | Line comments | Block comments |
+|---|---|---|
+| `default` | `//` | `{# #}`, `<!-- -->` |
+| `jinja` / `jinja2` | — | `{# #}` |
+| `django` | — | `{# #}`, `{% comment %}...{% endcomment %}` |
+| `liquid` | — | `{% comment %}...{% endcomment %}` |
+| `handlebars` / `mustache` | — | `{{! }}`, `{{!-- --}}` |
+| `markdown` / `html` / `xml` | — | `<!-- -->` |
+| `yaml` / `toml` / `env` | `#` | — |
+| `ini` | `#`, `;` | — |
+| `json5` / `jsonc` | `//` | `/* */` |
+| `python` | `#` | — |
+| `shell` / `bash` / `sh` / `zsh` | `#` | — |
+| `sql` | `--` | `/* */` |
+| `latex` | `%` | — |
+| `c` / `js` / `ts` / `go` / `rust` / `java` / `csharp` / ... | `//` | `/* */` |
+| `all` | every marker above | every block style above |
+
+Run `prompt-comments --list-dialects` (or `prompt_comments.list_dialects()`) for the exact, current list.
+
+Dialects can be combined by passing a list, e.g. `dialect=["yaml", "jinja"]`.
+
+## A note on false positives
+
+Comment stripping here is regex-based, not a full parser for every
+format. A line-comment marker only starts a comment when it's at the
+start of a line or preceded by whitespace (this is why
+`https://example.com` survives the `//` marker: the `//` is preceded
+by `:`, not whitespace). It is still a heuristic — e.g. `# Heading`
+in a Markdown file *would* be stripped if you opted into the `yaml`
+or `python` dialect (which treat `#` as a comment marker) on that
+text. Stick to `default`/`markdown`/`jinja`-style dialects for prose
+prompts with literal `#`, `--`, or `%` characters, or escape the
+character with a backslash where it must be kept literally.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

prompt_comments-0.1.0/README.md

@@ -0,0 +1,152 @@
+# prompt-comments
+
+[![CI](https://github.com/viswanathms/prompt-comments/actions/workflows/ci.yml/badge.svg)](https://github.com/viswanathms/prompt-comments/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/prompt-comments.svg)](https://pypi.org/project/prompt-comments/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Write comments in your AI prompts. Strip them before they reach the model.
+
+Prompts live in Markdown files, Jinja templates, YAML configs, plain
+`.txt` files — but none of those give you a way to leave a note for
+your future self ("why is this instruction here?", "TODO: tighten
+this up") without the note leaking into the actual text sent to the
+model. `prompt-comments` strips comments in whatever format your
+prompt already uses, right before you hand the text to your LLM SDK
+of choice.
+
+```python
+from prompt_comments import strip_comments
+
+prompt = """
+You are a helpful support assistant. {# keep tone friendly, not robotic #}
+Always answer in the user's language. <!-- TODO: revisit for RTL languages -->
+"""
+
+strip_comments(prompt)
+# "\nYou are a helpful support assistant.\nAlways answer in the user's language.\n"
+```
+
+## Install
+
+```bash
+pip install prompt-comments
+```
+
+## Usage
+
+### Strip comments from a string
+
+```python
+from prompt_comments import strip_comments
+
+strip_comments("Summarize this. {# only for the 'concise' variant #}")
+# "Summarize this."
+```
+
+By default, `strip_comments` removes a small set of comment styles
+that are unlikely to collide with real prompt text: Jinja-style block
+comments (`{# ... #}`), HTML/Markdown block comments (`<!-- ... -->`),
+and `//` line comments. Pick a different (or additional) dialect for
+formats with their own conventions:
+
+```python
+strip_comments(open("system_prompt.yaml").read(), dialect="yaml")
+
+# Combine multiple dialects
+strip_comments(text, dialect=["jinja", "yaml"])
+```
+
+### Load a prompt straight from a file
+
+`load_prompt` reads a file and infers the right dialect from its
+extension automatically (`.j2`/`.jinja2` → Jinja, `.md` → Markdown,
+`.yaml` → YAML, ...):
+
+```python
+from prompt_comments import load_prompt
+
+system_prompt = load_prompt("prompts/system.md")
+```
+
+Override the inferred dialect if needed:
+
+```python
+load_prompt("prompts/system.txt", dialect="yaml")
+```
+
+### Command line
+
+```bash
+prompt-comments prompts/system.md            # auto-detects dialect from extension
+prompt-comments prompts/system.txt -d yaml    # force a dialect
+cat prompt.txt | prompt-comments -d jinja     # read from stdin
+prompt-comments --list-dialects
+```
+
+### Escaping a literal marker
+
+Prefix a line-comment marker with `\` to keep it literally instead of
+treating it as a comment:
+
+```python
+strip_comments(r"The meeting room is \#3 today", dialect="yaml")
+# "The meeting room is #3 today"
+```
+
+### Dropping now-empty lines
+
+Comments that occupied a whole line leave a blank line behind by
+default. Pass `strip_blank_lines=True` to drop them instead:
+
+```python
+strip_comments("keep\n// only a comment\nkeep too", dialect="c", strip_blank_lines=True)
+# "keep\nkeep too"
+```
+
+## Supported dialects
+
+| Dialect | Line comments | Block comments |
+|---|---|---|
+| `default` | `//` | `{# #}`, `<!-- -->` |
+| `jinja` / `jinja2` | — | `{# #}` |
+| `django` | — | `{# #}`, `{% comment %}...{% endcomment %}` |
+| `liquid` | — | `{% comment %}...{% endcomment %}` |
+| `handlebars` / `mustache` | — | `{{! }}`, `{{!-- --}}` |
+| `markdown` / `html` / `xml` | — | `<!-- -->` |
+| `yaml` / `toml` / `env` | `#` | — |
+| `ini` | `#`, `;` | — |
+| `json5` / `jsonc` | `//` | `/* */` |
+| `python` | `#` | — |
+| `shell` / `bash` / `sh` / `zsh` | `#` | — |
+| `sql` | `--` | `/* */` |
+| `latex` | `%` | — |
+| `c` / `js` / `ts` / `go` / `rust` / `java` / `csharp` / ... | `//` | `/* */` |
+| `all` | every marker above | every block style above |
+
+Run `prompt-comments --list-dialects` (or `prompt_comments.list_dialects()`) for the exact, current list.
+
+Dialects can be combined by passing a list, e.g. `dialect=["yaml", "jinja"]`.
+
+## A note on false positives
+
+Comment stripping here is regex-based, not a full parser for every
+format. A line-comment marker only starts a comment when it's at the
+start of a line or preceded by whitespace (this is why
+`https://example.com` survives the `//` marker: the `//` is preceded
+by `:`, not whitespace). It is still a heuristic — e.g. `# Heading`
+in a Markdown file *would* be stripped if you opted into the `yaml`
+or `python` dialect (which treat `#` as a comment marker) on that
+text. Stick to `default`/`markdown`/`jinja`-style dialects for prose
+prompts with literal `#`, `--`, or `%` characters, or escape the
+character with a backslash where it must be kept literally.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

prompt_comments-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "prompt-comments"
+version = "0.1.0"
+description = "Write comments in your AI prompts, strip them before they reach the model."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "viswanathms" },
+]
+keywords = ["prompt", "prompt-engineering", "llm", "ai", "comments", "jinja", "template", "markdown"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "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 :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Filters",
+]
+
+[project.urls]
+Homepage = "https://github.com/viswanathms/prompt-comments"
+Repository = "https://github.com/viswanathms/prompt-comments"
+Issues = "https://github.com/viswanathms/prompt-comments/issues"
+
+[project.scripts]
+prompt-comments = "prompt_comments.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/prompt_comments"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

prompt_comments-0.1.0/src/prompt_comments/__init__.py

@@ -0,0 +1,21 @@
+"""prompt_comments: write comments in your AI prompts, strip them before
+they reach the model.
+
+    >>> from prompt_comments import strip_comments
+    >>> strip_comments("Summarize this. {# only for the 'concise' variant #}")
+    'Summarize this.'
+"""
+
+from .core import strip_comments
+from .dialects import Dialect, list_dialects
+from .loader import detect_dialect, load_prompt
+
+__all__ = [
+    "strip_comments",
+    "load_prompt",
+    "detect_dialect",
+    "list_dialects",
+    "Dialect",
+]
+
+__version__ = "0.1.0"

prompt_comments-0.1.0/src/prompt_comments/cli.py

@@ -0,0 +1,62 @@
+"""``prompt-comments`` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional, Sequence
+
+from .core import strip_comments
+from .dialects import list_dialects
+from .loader import detect_dialect
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="prompt-comments",
+        description="Strip comments from a prompt file (or stdin) and print the result.",
+    )
+    parser.add_argument("path", nargs="?", help="Prompt file to clean. Reads stdin if omitted.")
+    parser.add_argument(
+        "-d",
+        "--dialect",
+        action="append",
+        help="Comment dialect to strip (repeatable). Default: inferred from the file "
+        "extension, or 'default' when reading stdin.",
+    )
+    parser.add_argument(
+        "--strip-blank-lines",
+        action="store_true",
+        help="Drop lines that become empty after their comment is removed.",
+    )
+    parser.add_argument(
+        "--list-dialects",
+        action="store_true",
+        help="List available dialect names and exit.",
+    )
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.list_dialects:
+        for name in list_dialects():
+            print(name)
+        return 0
+
+    if args.path:
+        with open(args.path, "r", encoding="utf-8") as f:
+            text = f.read()
+        dialect = args.dialect or detect_dialect(args.path)
+    else:
+        text = sys.stdin.read()
+        dialect = args.dialect or "default"
+
+    sys.stdout.write(strip_comments(text, dialect=dialect, strip_blank_lines=args.strip_blank_lines))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

prompt_comments-0.1.0/src/prompt_comments/core.py

@@ -0,0 +1,85 @@
+"""Core comment-stripping logic."""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Union
+
+from .dialects import Dialect, resolve_dialects
+
+DialectLike = Union[str, Dialect, Iterable[Union[str, Dialect]]]
+
+_ESCAPE_PLACEHOLDER = "\0PROMPT_COMMENTS_ESCAPED\0"
+
+
+def strip_comments(text: str, dialect: DialectLike = "default", *, strip_blank_lines: bool = False) -> str:
+    """Remove comments from ``text``.
+
+    Args:
+        text: The prompt text to clean.
+        dialect: A dialect name (e.g. ``"jinja"``), a :class:`~prompt_comments.dialects.Dialect`
+            instance, or a list mixing either. Defaults to ``"default"``, a small
+            set of comment styles ( ``{# #}``, ``<!-- -->``, ``//`` ) chosen to be
+            unlikely to collide with real prompt text. See
+            :func:`prompt_comments.dialects.list_dialects` for all available names.
+        strip_blank_lines: If ``True``, lines that become empty after a comment
+            is removed are dropped entirely instead of left as blank lines.
+
+    Returns:
+        The text with all matching comments removed.
+
+    A line-comment marker can be kept literally by escaping it with a
+    backslash, e.g. ``\\# not a comment``.
+    """
+    dialects = resolve_dialects(dialect)
+    text = _strip_block_comments(text, dialects)
+    text = _strip_line_comments(text, dialects)
+    if strip_blank_lines:
+        text = "\n".join(line for line in text.split("\n") if line.strip())
+    return text
+
+
+def _strip_block_comments(text: str, dialects) -> str:
+    blocks = []
+    seen = set()
+    for d in dialects:
+        for block in d.block_comments:
+            key = (block.start, block.end)
+            if key not in seen:
+                seen.add(key)
+                blocks.append(block)
+    if not blocks:
+        return text
+
+    # Longer start delimiters first, so e.g. `{{!--` is tried before `{{!`.
+    blocks.sort(key=lambda b: len(b.start), reverse=True)
+    pattern = "|".join(re.escape(b.start) + r".*?" + re.escape(b.end) for b in blocks)
+    return re.sub(pattern, "", text, flags=re.DOTALL)
+
+
+def _strip_line_comments(text: str, dialects) -> str:
+    markers = set()
+    for d in dialects:
+        for lc in d.line_comments:
+            markers.add(lc.marker)
+    if not markers:
+        return text
+
+    # Longest markers first so e.g. `--` isn't a partial match ahead of a
+    # hypothetical `---` marker.
+    ordered = sorted(markers, key=len, reverse=True)
+    marker_pattern = "|".join(re.escape(m) for m in ordered)
+
+    escaped_re = re.compile(r"\\(" + marker_pattern + r")")
+    text = escaped_re.sub(lambda m: _ESCAPE_PLACEHOLDER + m.group(1), text)
+
+    # A marker only starts a comment at the beginning of a line or after
+    # whitespace -- this keeps things like `https://example.com` and
+    # `color: #fff` mid-token intact in common cases (URLs specifically:
+    # the char before `//` there is `:`, not whitespace, so it's skipped).
+    comment_re = re.compile(r"(?:^|(?<=\s))(?:" + marker_pattern + r").*$", re.MULTILINE)
+    text = comment_re.sub("", text)
+
+    text = text.replace(_ESCAPE_PLACEHOLDER, "")
+    text = re.sub(r"[ \t]+$", "", text, flags=re.MULTILINE)
+    return text

prompt_comments-0.1.0/src/prompt_comments/dialects.py

@@ -0,0 +1,189 @@
+"""Comment-syntax definitions for the file formats and template engines
+that AI prompts commonly live in.
+
+A :class:`Dialect` is just a named bundle of line-comment markers and
+block-comment delimiters. Dialects can be combined freely -- pass a list
+of names to :func:`prompt_comments.strip_comments` to strip several
+comment styles from the same text at once (handy for e.g. a Jinja
+template that is also a Markdown document).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Tuple
+
+
+@dataclass(frozen=True)
+class LineComment:
+    """A marker that comments out everything from itself to end of line."""
+
+    marker: str
+
+
+@dataclass(frozen=True)
+class BlockComment:
+    """A start/end delimiter pair that comments out everything between."""
+
+    start: str
+    end: str
+
+
+@dataclass(frozen=True)
+class Dialect:
+    """A named collection of comment styles."""
+
+    name: str
+    line_comments: Tuple[LineComment, ...] = field(default_factory=tuple)
+    block_comments: Tuple[BlockComment, ...] = field(default_factory=tuple)
+
+
+# --- Reusable comment-style building blocks --------------------------------
+
+_HASH_LINE = LineComment("#")
+_SLASH_LINE = LineComment("//")
+_DASH_LINE = LineComment("--")
+_SEMI_LINE = LineComment(";")
+_PERCENT_LINE = LineComment("%")
+
+_JINJA_BLOCK = BlockComment("{#", "#}")
+_HTML_BLOCK = BlockComment("<!--", "-->")
+_C_BLOCK = BlockComment("/*", "*/")
+_LIQUID_BLOCK = BlockComment("{% comment %}", "{% endcomment %}")
+_MUSTACHE_LONG_BLOCK = BlockComment("{{!--", "--}}")
+_MUSTACHE_SHORT_BLOCK = BlockComment("{{!", "}}")
+
+
+def _dialect(name: str, *, line=(), block=()) -> Dialect:
+    return Dialect(name=name, line_comments=tuple(line), block_comments=tuple(block))
+
+
+# --- Named dialects ----------------------------------------------------------
+#
+# "default" is deliberately small: only comment styles that are very
+# unlikely to collide with real prompt text. Format-specific dialects
+# (yaml, python, sql, ...) add markers like `#`, `--`, `%` that *do*
+# collide with plausible prompt content (Markdown headings, "item #3",
+# LaTeX-ish text) -- opt into those explicitly via the `dialect` argument.
+
+_BASE: Dict[str, Dialect] = {
+    "default": _dialect("default", line=[_SLASH_LINE], block=[_JINJA_BLOCK, _HTML_BLOCK]),
+    "jinja": _dialect("jinja", block=[_JINJA_BLOCK]),
+    "django": _dialect("django", block=[_JINJA_BLOCK, _LIQUID_BLOCK]),
+    "liquid": _dialect("liquid", block=[_LIQUID_BLOCK]),
+    "handlebars": _dialect("handlebars", block=[_MUSTACHE_LONG_BLOCK, _MUSTACHE_SHORT_BLOCK]),
+    "markdown": _dialect("markdown", block=[_HTML_BLOCK]),
+    "html": _dialect("html", block=[_HTML_BLOCK]),
+    "xml": _dialect("xml", block=[_HTML_BLOCK]),
+    "yaml": _dialect("yaml", line=[_HASH_LINE]),
+    "toml": _dialect("toml", line=[_HASH_LINE]),
+    "ini": _dialect("ini", line=[_HASH_LINE, _SEMI_LINE]),
+    "env": _dialect("env", line=[_HASH_LINE]),
+    "json5": _dialect("json5", line=[_SLASH_LINE], block=[_C_BLOCK]),
+    "python": _dialect("python", line=[_HASH_LINE]),
+    "shell": _dialect("shell", line=[_HASH_LINE]),
+    "sql": _dialect("sql", line=[_DASH_LINE], block=[_C_BLOCK]),
+    "latex": _dialect("latex", line=[_PERCENT_LINE]),
+    "c": _dialect("c", line=[_SLASH_LINE], block=[_C_BLOCK]),
+}
+
+# Aliases: alternate names that map to an existing dialect above.
+_ALIASES: Dict[str, str] = {
+    "jinja2": "jinja",
+    "mustache": "handlebars",
+    "jsonc": "json5",
+    "bash": "shell",
+    "sh": "shell",
+    "zsh": "shell",
+    "js": "c",
+    "javascript": "c",
+    "ts": "c",
+    "typescript": "c",
+    "go": "c",
+    "golang": "c",
+    "rust": "c",
+    "java": "c",
+    "csharp": "c",
+    "cs": "c",
+    "cpp": "c",
+    "c++": "c",
+}
+
+DIALECTS: Dict[str, Dialect] = dict(_BASE)
+for _alias, _target in _ALIASES.items():
+    DIALECTS[_alias] = DIALECTS[_target]
+
+# "all": every comment style from every named dialect, deduplicated. Handy
+# as a maximal default, though it maximizes the odds of a false-positive
+# match against literal prompt text -- prefer naming specific dialects.
+_all_line = {lc for d in _BASE.values() for lc in d.line_comments}
+_all_block = {bc for d in _BASE.values() for bc in d.block_comments}
+DIALECTS["all"] = _dialect("all", line=sorted(_all_line, key=lambda l: l.marker), block=sorted(_all_block, key=lambda b: b.start))
+
+
+def resolve_dialects(dialect):
+    """Normalize a dialect argument into a list of :class:`Dialect` objects.
+
+    `dialect` may be a dialect name, a :class:`Dialect` instance, or an
+    iterable mixing either.
+    """
+    if isinstance(dialect, (str, Dialect)):
+        items = [dialect]
+    else:
+        items = list(dialect)
+
+    resolved = []
+    for item in items:
+        if isinstance(item, Dialect):
+            resolved.append(item)
+            continue
+        name = str(item).lower()
+        if name not in DIALECTS:
+            raise ValueError(
+                f"Unknown dialect {item!r}. Available dialects: {', '.join(sorted(DIALECTS))}"
+            )
+        resolved.append(DIALECTS[name])
+    return resolved
+
+
+def list_dialects():
+    """Return the sorted list of known dialect names (including aliases)."""
+    return sorted(DIALECTS)
+
+
+# --- File-extension -> dialect mapping, used by prompt_comments.loader -----
+
+EXTENSION_DIALECTS: Dict[str, str] = {
+    ".md": "markdown",
+    ".markdown": "markdown",
+    ".j2": "jinja",
+    ".jinja": "jinja",
+    ".jinja2": "jinja",
+    ".html": "html",
+    ".htm": "html",
+    ".xml": "xml",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".ini": "ini",
+    ".cfg": "ini",
+    ".env": "env",
+    ".json5": "json5",
+    ".jsonc": "jsonc",
+    ".py": "python",
+    ".sh": "shell",
+    ".bash": "shell",
+    ".sql": "sql",
+    ".tex": "latex",
+    ".liquid": "liquid",
+    ".hbs": "handlebars",
+    ".handlebars": "handlebars",
+    ".mustache": "mustache",
+    ".js": "javascript",
+    ".ts": "typescript",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+    ".cs": "csharp",
+    ".txt": "default",
+}

prompt_comments-0.1.0/src/prompt_comments/loader.py

@@ -0,0 +1,34 @@
+"""File-aware convenience wrapper around :func:`prompt_comments.core.strip_comments`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Union
+
+from .core import DialectLike, strip_comments
+from .dialects import EXTENSION_DIALECTS
+
+
+def detect_dialect(path: Union[str, Path]) -> str:
+    """Guess a dialect name from a file's extension, defaulting to ``"default"``."""
+    return EXTENSION_DIALECTS.get(Path(path).suffix.lower(), "default")
+
+
+def load_prompt(
+    path: Union[str, Path],
+    dialect: Optional[DialectLike] = None,
+    *,
+    encoding: str = "utf-8",
+    strip_blank_lines: bool = False,
+) -> str:
+    """Read a prompt file and return it with comments stripped.
+
+    If ``dialect`` is omitted, it is inferred from the file extension
+    (e.g. ``.j2`` -> ``jinja``, ``.md`` -> ``markdown``), falling back to
+    ``"default"`` for unrecognized extensions.
+    """
+    path = Path(path)
+    text = path.read_text(encoding=encoding)
+    if dialect is None:
+        dialect = detect_dialect(path)
+    return strip_comments(text, dialect=dialect, strip_blank_lines=strip_blank_lines)

prompt_comments-0.1.0/tests/test_cli.py

@@ -0,0 +1,30 @@
+from prompt_comments.cli import main
+
+
+def test_cli_reads_file_and_strips_comments(tmp_path, capsys):
+    p = tmp_path / "prompt.j2"
+    p.write_text("Hello {# note #}world")
+    assert main([str(p)]) == 0
+    assert capsys.readouterr().out == "Hello world"
+
+
+def test_cli_explicit_dialect_flag(tmp_path, capsys):
+    p = tmp_path / "prompt.txt"
+    p.write_text("role: system # comment")
+    assert main([str(p), "-d", "yaml"]) == 0
+    assert capsys.readouterr().out == "role: system"
+
+
+def test_cli_list_dialects(capsys):
+    assert main(["--list-dialects"]) == 0
+    out = capsys.readouterr().out.splitlines()
+    assert "jinja" in out
+    assert "default" in out
+
+
+def test_cli_reads_stdin(monkeypatch, capsys):
+    import io
+
+    monkeypatch.setattr("sys.stdin", io.StringIO("Hi {# drop #}there"))
+    assert main([]) == 0
+    assert capsys.readouterr().out == "Hi there"

prompt_comments-0.1.0/tests/test_core.py

@@ -0,0 +1,94 @@
+import pytest
+
+from prompt_comments import strip_comments
+from prompt_comments.dialects import list_dialects
+
+
+def test_default_strips_jinja_block():
+    assert strip_comments("Hello {# note to self #}world") == "Hello world"
+
+
+def test_default_strips_html_block():
+    text = "Line one\n<!-- drop this\nand this -->\nLine two"
+    assert strip_comments(text) == "Line one\n\nLine two"
+
+
+def test_default_strips_slash_line_comment():
+    text = "Be concise. // internal note\nBe kind."
+    assert strip_comments(text) == "Be concise.\nBe kind."
+
+
+def test_default_preserves_url_double_slash():
+    text = "See https://example.com/path for details."
+    assert strip_comments(text) == text
+
+
+def test_default_does_not_strip_hash_by_default():
+    text = "# Heading\nBody # not stripped in default dialect"
+    assert strip_comments(text) == text
+
+
+def test_yaml_dialect_strips_hash_line_comment():
+    text = "role: system # who is speaking"
+    assert strip_comments(text, dialect="yaml") == "role: system"
+
+
+def test_multiple_dialects_combined():
+    text = "role: system # yaml comment\nGreet the user. // js comment"
+    result = strip_comments(text, dialect=["yaml", "c"])
+    assert result == "role: system\nGreet the user."
+
+
+def test_escaped_marker_is_preserved_literally():
+    text = r"The price is \# 3 today"
+    assert strip_comments(text, dialect="yaml") == "The price is # 3 today"
+
+
+def test_liquid_block_comment():
+    text = "before {% comment %} secret {% endcomment %} after"
+    assert strip_comments(text, dialect="liquid") == "before  after"
+
+
+def test_handlebars_short_and_long_forms():
+    text = "a {{! short }} b {{!-- long --}} c"
+    assert strip_comments(text, dialect="handlebars") == "a  b  c"
+
+
+def test_sql_dialect_line_and_block():
+    text = "SELECT * FROM t -- pick everything\n/* multi\nline */ WHERE 1=1"
+    assert strip_comments(text, dialect="sql") == "SELECT * FROM t\n WHERE 1=1"
+
+
+def test_latex_dialect():
+    # The marker only starts a comment when preceded by whitespace or line
+    # start, so the literal "100%" survives while " % this is..." is dropped.
+    text = r"100% done % this is a latex comment"
+    assert strip_comments(text, dialect="latex") == "100% done"
+
+
+def test_strip_blank_lines_option():
+    text = "keep\n// only a comment\nkeep too"
+    result = strip_comments(text, dialect="c", strip_blank_lines=True)
+    assert result == "keep\nkeep too"
+
+
+def test_unknown_dialect_raises():
+    with pytest.raises(ValueError):
+        strip_comments("text", dialect="not-a-real-dialect")
+
+
+def test_all_dialect_is_superset_and_listed():
+    assert "all" in list_dialects()
+    assert "jinja" in list_dialects()
+    assert "jinja2" in list_dialects()
+
+
+def test_dialect_alias_jinja2_matches_jinja():
+    text = "keep {# drop #} keep"
+    assert strip_comments(text, dialect="jinja2") == strip_comments(text, dialect="jinja")
+
+
+def test_no_dialects_selected_is_noop_for_line_only_text():
+    # "markdown" dialect only defines block comments; a lone // survives.
+    text = "visit https://example.com // not stripped"
+    assert strip_comments(text, dialect="markdown") == text

prompt_comments-0.1.0/tests/test_loader.py

@@ -0,0 +1,27 @@
+from prompt_comments import detect_dialect, load_prompt
+
+
+def test_detect_dialect_from_extension():
+    assert detect_dialect("prompt.j2") == "jinja"
+    assert detect_dialect("prompt.md") == "markdown"
+    assert detect_dialect("prompt.yaml") == "yaml"
+    assert detect_dialect("prompt.unknownext") == "default"
+
+
+def test_load_prompt_auto_detects_dialect(tmp_path):
+    p = tmp_path / "system.md"
+    p.write_text("You are a helpful assistant. <!-- internal note --> Be concise.")
+    assert load_prompt(p) == "You are a helpful assistant.  Be concise."
+
+
+def test_load_prompt_explicit_dialect_overrides_extension(tmp_path):
+    p = tmp_path / "system.txt"
+    p.write_text("role: system # not stripped by default dialect")
+    assert load_prompt(p, dialect="yaml") == "role: system"
+
+
+def test_load_prompt_strip_blank_lines(tmp_path):
+    p = tmp_path / "prompt.j2"
+    p.write_text("keep\n{# drop entire line #}\nkeep too")
+    result = load_prompt(p, strip_blank_lines=True)
+    assert result == "keep\nkeep too"