tagsnip 1.0.0__tar.gz

tagsnip-1.0.0/LICENSE.md

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

tagsnip-1.0.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: tagsnip
+Version: 1.0.0
+Summary: Python package for extracting tagged code snippets from local files or remote sources.
+Author: Rostislav Brož
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/brozrost/tagsnip
+Project-URL: Repository, https://github.com/brozrost/tagsnip
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: requests
+Dynamic: license-file
+
+`tagsnip` is a Python CLI tool for extracting tagged code snippets from local files or remote URLs, such as GitHub raw files. It serves as the backend for the tagsnip LaTeX package and enables dynamic inclusion of code snippets directly in LaTeX documents.
+
+<div align="center">
+  <a href="https://github.com/brozrost/tagsnip/actions">
+    <img src="https://github.com/brozrost/tagsnip/actions/workflows/python-package.yml/badge.svg">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/graphs/contributors">
+    <img src="https://img.shields.io/github/contributors/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/issues">
+    <img src="https://img.shields.io/github/issues/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/pulls">
+    <img src="https://img.shields.io/github/issues-pr/brozrost/tagsnip">
+  </a>
+</div>
+
+## Installation
+
+Install `tagsnip` from PyPI:
+
+```sh
+pip install tagsnip
+```
+
+After installation, the command `tagsnip` should be available in your shell:
+
+```sh
+tagsnip --help
+```
+
+## Usage
+
+```sh
+tagsnip -s <source> -t <tag> [-o <output>]
+```
+
+```sh
+tagsnip -c <output>
+```
+
+### Command-line options
+```text
+-s, --source   Local file path or remote URL.  
+-t, --tag      Snippet tag to extract.  
+-o, --output   Optional output file path.
+-c, --cleanup  Removes temporary files at specified path. 
+```
+
+`--source` and `--tag` are mandatory arguments. If `--output` is provided, `tagsnip` writes the extracted snippet to the selected file. Otherwise, the snippet is written to `stdout`.
+
+When `--output` is used, `tagsnip` also writes a metadata file next to the output file. For example, if the output file is `snippet.tmp`, then the metadata file is `snippet.tmp.meta`. Both files can be removed using the `--cleanup` option.
+ 
+The metadata file contains the original start and end line numbers of the extracted snippet. This is used by the LaTeX package to preserve source line numbering.
+
+### Supported sources 
+
+- Local text files
+- Remote text files available over HTTP or HTTPS
+- GitHub raw file URLs
+
+### Tag format
+
+`tagsnip` extracts code between two matching markers:
+
+```text
+tagsnip-start <tag>
+...
+tagsnip-end <tag>
+```
+
+Tags are case-sensitive. Markers must appear on separate lines. The tag must follow the marker name after one space.
+
+For example:
+
+```python
+# tagsnip-start demo
+print("This line will be extracted.")
+# tagsnip-end demo
+```
+
+The marker lines themselves are not included in the extracted snippet.
+
+### Error handling
+
+`tagsnip` reports errors when:
+
+- The tag is not found
+- Start/end markers are mismatched
+- Multiple start markers exist
+- The source cannot be fetched
+
+## Quick example
+
+### Example source file
+
+```python
+# tagsnip-start demo
+def main():
+    x = 1
+    y = 2
+    print(x + y)
+
+    return 0
+# tagsnip-end demo
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())
+```
+
+### CLI usage
+
+Write the snippet to `stdout`:
+
+```bash    
+tagsnip -s example.py -t demo
+```
+
+Write the snippet to a file:
+```bash  
+tagsnip -s example.py -t demo -o out/out.txt
+```
+
+Get snippet from URL:
+```bash
+tagsnip -s https://raw.githubusercontent.com/brozrost/tagsnip/main/docs/example.py -t demo
+```
+
+Remove temporary files:
+```bash
+tagsnip -c out/out.txt
+```
+
+### Python usage
+
+```python
+from tagsnip import extractor
+
+snippet = extractor.extract_from_file("example.py", "demo")
+```
+
+## Compatibility note
+
+The Python package and the LaTeX package should be kept in sync. Backwards compatibility is not guaranteed.

tagsnip-1.0.0/README-pypi.md

@@ -0,0 +1,145 @@
+`tagsnip` is a Python CLI tool for extracting tagged code snippets from local files or remote URLs, such as GitHub raw files. It serves as the backend for the tagsnip LaTeX package and enables dynamic inclusion of code snippets directly in LaTeX documents.
+
+<div align="center">
+  <a href="https://github.com/brozrost/tagsnip/actions">
+    <img src="https://github.com/brozrost/tagsnip/actions/workflows/python-package.yml/badge.svg">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/graphs/contributors">
+    <img src="https://img.shields.io/github/contributors/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/issues">
+    <img src="https://img.shields.io/github/issues/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/pulls">
+    <img src="https://img.shields.io/github/issues-pr/brozrost/tagsnip">
+  </a>
+</div>
+
+## Installation
+
+Install `tagsnip` from PyPI:
+
+```sh
+pip install tagsnip
+```
+
+After installation, the command `tagsnip` should be available in your shell:
+
+```sh
+tagsnip --help
+```
+
+## Usage
+
+```sh
+tagsnip -s <source> -t <tag> [-o <output>]
+```
+
+```sh
+tagsnip -c <output>
+```
+
+### Command-line options
+```text
+-s, --source   Local file path or remote URL.  
+-t, --tag      Snippet tag to extract.  
+-o, --output   Optional output file path.
+-c, --cleanup  Removes temporary files at specified path. 
+```
+
+`--source` and `--tag` are mandatory arguments. If `--output` is provided, `tagsnip` writes the extracted snippet to the selected file. Otherwise, the snippet is written to `stdout`.
+
+When `--output` is used, `tagsnip` also writes a metadata file next to the output file. For example, if the output file is `snippet.tmp`, then the metadata file is `snippet.tmp.meta`. Both files can be removed using the `--cleanup` option.
+ 
+The metadata file contains the original start and end line numbers of the extracted snippet. This is used by the LaTeX package to preserve source line numbering.
+
+### Supported sources 
+
+- Local text files
+- Remote text files available over HTTP or HTTPS
+- GitHub raw file URLs
+
+### Tag format
+
+`tagsnip` extracts code between two matching markers:
+
+```text
+tagsnip-start <tag>
+...
+tagsnip-end <tag>
+```
+
+Tags are case-sensitive. Markers must appear on separate lines. The tag must follow the marker name after one space.
+
+For example:
+
+```python
+# tagsnip-start demo
+print("This line will be extracted.")
+# tagsnip-end demo
+```
+
+The marker lines themselves are not included in the extracted snippet.
+
+### Error handling
+
+`tagsnip` reports errors when:
+
+- The tag is not found
+- Start/end markers are mismatched
+- Multiple start markers exist
+- The source cannot be fetched
+
+## Quick example
+
+### Example source file
+
+```python
+# tagsnip-start demo
+def main():
+    x = 1
+    y = 2
+    print(x + y)
+
+    return 0
+# tagsnip-end demo
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())
+```
+
+### CLI usage
+
+Write the snippet to `stdout`:
+
+```bash    
+tagsnip -s example.py -t demo
+```
+
+Write the snippet to a file:
+```bash  
+tagsnip -s example.py -t demo -o out/out.txt
+```
+
+Get snippet from URL:
+```bash
+tagsnip -s https://raw.githubusercontent.com/brozrost/tagsnip/main/docs/example.py -t demo
+```
+
+Remove temporary files:
+```bash
+tagsnip -c out/out.txt
+```
+
+### Python usage
+
+```python
+from tagsnip import extractor
+
+snippet = extractor.extract_from_file("example.py", "demo")
+```
+
+## Compatibility note
+
+The Python package and the LaTeX package should be kept in sync. Backwards compatibility is not guaranteed.

tagsnip-1.0.0/README.md

@@ -0,0 +1,187 @@
+### `tagsnip` is a LaTeX package for including tagged code snippets from local files or remote URLs. It extracts marked sections of code and typesets them in a consistent style, supporting reproducible and maintainable documentation.
+
+<div align="center">
+  <a href="https://github.com/brozrost/tagsnip/actions">
+    <img src="https://github.com/brozrost/tagsnip/actions/workflows/python-package.yml/badge.svg">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/graphs/contributors">
+    <img src="https://img.shields.io/github/contributors/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/issues">
+    <img src="https://img.shields.io/github/issues/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/pulls">
+    <img src="https://img.shields.io/github/issues-pr/brozrost/tagsnip">
+  </a>
+</div>
+
+**Documentation:** <a href="https://github.com/brozrost/tagsnip/blob/main/docs/tagsnip-docs.pdf">tagsnip-docs.pdf</a>  
+**Czech documentation:** <a href="https://github.com/brozrost/tagsnip/blob/main/docs/tagsnip-docs-czech.pdf">tagsnip-docs-czech.pdf</a>
+
+> The documentation files also double as example documents for `tagsnip`.
+
+## Installation
+
+`tagsnip` consists of two parts:
+
+1. LaTeX package `tagsnip.sty`,
+2. Python backend package `tagsnip`.
+
+Both parts are required.
+
+### Installing the LaTeX package from CTAN
+
+Download the <a href="https://ctan.org/pkg/tagsnip">`tagsnip` package archive from CTAN</a> and extract it. For a local project installation, copy `tagsnip.sty` next to your main `.tex` file:
+
+```sh
+project/
+├── main.tex
+└── tagsnip.sty
+```
+
+This is the simplest installation method and is sufficient for compiling a single project. For a user-wide installation, place `tagsnip.sty` into your local TeX tree.
+
+Also see: https://ctan.org/pkg/tagsnip
+
+### Installing the Python backend
+
+`tagsnip` uses a Python backend with the same name to parse source files. The backend is published on PyPI. Before using the LaTeX package, install the backend:
+
+```sh
+pip install tagsnip
+```
+
+Also see: https://pypi.org/project/tagsnip/
+
+After installation, the backend must be available in the system `PATH` under the command name `tagsnip`. You can check this with:
+
+~~~sh
+tagsnip --help
+~~~
+
+## Compilation
+
+```sh
+lualatex --shell-escape docs/tagsnip-docs.tex
+```
+
+## Usage
+
+**Example document:** <a href="https://github.com/brozrost/tagsnip/blob/main/docs/docs.pdf">docs.pdf</a>
+
+`tagsnip` defines the command `\IncludeCode`, which is used as follows:
+
+```tex
+\IncludeCode[options]{source}{tag}{language}{caption}
+```
+
+The optional argument `options` allows the user to override code formatting settings. These options are passed directly to `minted`, so they must be valid `minted` options and must be separated by commas. For example:
+
+```tex
+\IncludeCode[
+  firstnumber=1,
+  fontsize=\scriptsize,
+  style=monokai
+]{docs/example.py}{tag1}{Python}{Example snippet.}
+```
+
+The option `firstnumber=1` starts line numbering at line 1, `fontsize=\scriptsize` changes the font size, and `style=monokai` changes the syntax highlighting style.
+
+Without changing `firstnumber`, `tagsnip` preserves the original line numbers from the source file.
+
+The mandatory argument `source` defines where the code should be loaded from. It can be either a local file path or a URL pointing to a remote text file. `tagsnip` distinguishes these cases automatically.
+
+The mandatory argument `tag` specifies the unique keyword identifying the requested snippet. A snippet is delimited in the source file by `tagsnip-start` and `tagsnip-end` markers:
+
+```python
+# tagsnip-start tag1
+def main():
+    x = 1
+    y = 2
+    print(x + y)
+
+    return 0
+# tagsnip-end tag1
+```
+
+The tag must follow the marker after exactly one space.
+
+The mandatory argument `language` selects the programming language used for syntax highlighting.
+
+The final argument `caption` defines the snippet caption. It may be empty, but the braces must still be written.
+
+## Local snippet
+
+Suppose the local file `docs/example.py` contains a function `main()` marked with the tag `tag1`, as seen above. The function can be included in the document with:
+
+```tex
+\IncludeCode{example.py}{tag1}{Python}{Úryvek 2: ...}
+```
+<div align="center">
+  <img width="835" height="265" alt="# tagsnip-start tag" src="https://github.com/user-attachments/assets/4ca1bd1a-abe8-4478-963d-15c42fbe9479" />
+</div>
+
+
+## Remote snippet
+
+`tagsnip` can also include snippets from source files available through web URLs.
+
+For example, a snippet marked with the tag `tag2` in a remote Python file can be included as follows:
+
+```tex
+\IncludeCode[firstnumber=1]{https://raw.githubusercontent.com/brozrost/tagsnip/main/docs/example2.py}{tag2}{Python}{Code snippet from a remote file.}
+```
+
+<div align="center">
+<img width="833" height="324" alt="Pasted Graphic 1 2" src="https://github.com/user-attachments/assets/02dfe4b5-0340-42b1-bb25-63cc0b331827" />
+</div>
+
+The remote file must be accessible over HTTP or HTTPS and must be readable as a plain text source file.
+
+## Architecture
+
+`tagsnip` consists of two main parts: a LaTeX frontend package and an external backend utility written in Python.
+
+The frontend defines the command `\IncludeCode` and handles the final typesetting of extracted snippets through the `minted` package.
+
+The backend is responsible for accessing source files, finding marked code regions, and extracting them into temporary files.
+
+During document compilation, the frontend uses shell escape to call the backend utility. It passes the source path or URL and the requested tag to the backend. The backend writes the extracted code to a temporary file, which is then inserted into the document and typeset by `minted`.
+
+## Backend
+
+The Python package `tagsnip` provides a command-line interface that accepts a source file, a tag name, and an output file path.
+
+The backend loads the source file, searches for the corresponding pair of `tagsnip-start` and `tagsnip-end` markers, and extracts the text between them.
+
+The package also checks for error states, such as:
+
+- a non-existent source file,
+- an inaccessible remote file,
+- a missing tag,
+- a missing start or end marker,
+- multiple occurrences of the same tag in one source file.
+
+If an error is detected, the backend raises an exception. This interrupts the LaTeX compilation and prints an appropriate error message.
+
+For local files, the backend uses Python's `pathlib` module. For tag matching, it uses `re`. For loading remote files over HTTP, it uses the `requests` library.
+
+## Limitations
+
+- `tagsnip` requires LuaLaTeX.
+- The document must be compiled with shell escape enabled, for example with `--shell-escape`.
+- The Python backend must be installed and available in the system `PATH` under the command `tagsnip`.
+- `tagsnip` depends on `minted`.
+- Remote source files must be accessible over HTTP or HTTPS.
+- Remote source files must be plain text files.
+
+## Security note
+
+`tagsnip` requires shell escape because it calls an external Python backend during compilation and removes temporary files (lines 80, 93, and 94 in `tagsnip.sty`).
+
+Only compile trusted documents with shell escape enabled.
+
+---
+Copyright (c) 2026 Rostislav Brož.
+
+> `tagsnip` is distributed under the MIT License. The full license text is included in the repository in the [`LICENSE`](https://github.com/brozrost/tagsnip/blob/main/LICENSE.md) file.

tagsnip-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tagsnip"
+version = "1.0.0"
+description = "Python package for extracting tagged code snippets from local files or remote sources."
+readme = "README-pypi.md"
+requires-python = ">=3.10"
+dependencies = ["requests"]
+authors = [
+    { name = "Rostislav Brož" }
+]
+license = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/brozrost/tagsnip"
+Repository = "https://github.com/brozrost/tagsnip"
+
+[tool.setuptools]
+packages = ["tagsnip"]
+
+[project.scripts]
+tagsnip = "tagsnip.cli:main"

tagsnip-1.0.0/setup.cfg

@@ -0,0 +1,8 @@
+[options.entry_points]
+console_scripts = 
+	tagsnip = tagsnip.cli:main
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

tagsnip-1.0.0/tagsnip/__main__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+"""
+Entrypoint for `python -m tagsnip`
+"""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

tagsnip-1.0.0/tagsnip/cli.py

@@ -0,0 +1,113 @@
+import sys
+import argparse
+from pathlib import Path
+
+from tagsnip import extractor
+from tagsnip import fetcher
+from tagsnip import validate
+
+def cleanup_generated_files(output_path: str) -> None:
+    snippet_path = Path(output_path)
+    meta_path = Path(str(snippet_path) + ".meta")
+
+    for path in (snippet_path, meta_path):
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError as exc:
+            raise RuntimeError(f"Error: Could not remove temporary file: {path}") from exc
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="tagsnip is a Python package for extracting tagged code snippets " \
+        "from local files or remote sources.",
+        usage="""
+        tagsnip --help
+
+        tagsnip --source <file path> --tag <tag>
+            tagsnip -s example.py -t demo
+
+        tagsnip --source <file path> --tag <tag> --out <out file path>
+            tagsnip -s example.py -t demo -o out/out.txt
+
+        tagsnip --source <url> --tag <tag>
+            tagsnip -s https://raw.githubusercontent.com/brozrost/tagsnip/main/docs/example.py -t demo
+
+        tagsnip --cleanup <generated file path>
+            tagsnip --cleanup out/out.txt
+        """
+    )
+
+    parser.add_argument(
+        "-s", "--source", 
+        help="Path to a local file or URL"
+    )
+    parser.add_argument(
+        "-t", "--tag", 
+        help="Snippet tag name."
+    )
+    parser.add_argument(
+        "-o", "--out", 
+        help="Path to the output file. If omitted, prints to stdout."
+    )
+
+    parser.add_argument(
+        "-c", "--cleanup",
+        metavar="FILE",
+        help="Remove a generated snippet file and its .meta file."
+    )
+
+    args = parser.parse_args()
+
+    if args.cleanup:
+        try:
+            cleanup_generated_files(args.cleanup)
+        except RuntimeError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+        
+        return 0
+
+    if not args.source or not args.tag:
+        parser.error("Error: Arguments -s/--source and -t/--tag are required unless --cleanup is used.")
+
+
+    try:
+        if validate.is_url(args.source):
+            fetch = fetcher.FetcherClient()
+            text = fetch.fetch_text(args.source)
+        else:
+            text = Path(args.source).read_text(encoding="utf-8")
+
+        snippet, first_line_num, last_line_num = extractor.extract_tagged_block(text, args.tag)
+
+    except fetcher.FetcherError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    except OSError:
+        print(f"Error: Could not read file: {args.source}", file=sys.stderr)
+        return 1
+    except extractor.TagsnipError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.out:
+        output_path = Path(args.out)
+    
+        try:
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(snippet, encoding="utf-8")
+
+            meta_path = Path(str(output_path) + ".meta")
+            meta_path.write_text(f"{first_line_num}\n{last_line_num}", encoding="utf-8")
+        except OSError as exc:
+            print(f"Error: Could not write file: {output_path}")
+            return 1
+    else:
+        print(snippet)
+
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

tagsnip-1.0.0/tagsnip/extractor.py

@@ -0,0 +1,51 @@
+import re
+from pathlib import Path
+
+class TagsnipError(RuntimeError):
+    pass
+
+def marker_matches(line: str, marker: str) -> bool:
+    pattern = rf"{re.escape(marker)}(?!\S)"
+    return re.search(pattern, line) is not None
+
+def extract_tagged_block(text: str, tag: str):
+    start_marker = f"tagsnip-start {tag}"
+    end_marker = f"tagsnip-end {tag}"
+
+    lines = text.splitlines()
+
+    start_index = None
+    end_index = None
+
+    for i, line in enumerate(lines):
+        if marker_matches(line, start_marker):
+            if start_index is not None:
+                raise TagsnipError(f"Multiple start tags found for '{tag}'")
+
+            start_index = i
+
+    if start_index is None:
+        raise TagsnipError(f"Start tag not found for '{tag}'")
+    
+    for i in range(start_index + 1, len(lines)):
+        if marker_matches(lines[i], end_marker):
+            end_index = i
+            break
+
+    if end_index is None:
+        raise TagsnipError(f"End tag not found for '{tag}'")
+    
+    return "\n".join(lines[start_index + 1:end_index]), start_index + 2, end_index
+
+def extract_from_file(path: str | Path, tag: str) -> str:
+    file_path = Path(path)
+
+    if not file_path.is_file():
+        raise TagsnipError(f"File not found: {file_path}")
+    
+    try:
+        text = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise TagsnipError(f"Could not read file: {file_path}") from exc
+
+    return extract_tagged_block(text, tag)

tagsnip-1.0.0/tagsnip/fetcher.py

@@ -0,0 +1,22 @@
+import requests
+
+class FetcherError(RuntimeError):
+    pass
+
+class FetcherClient:
+    def __init__(self, timeout: float = 30.0):
+        self.timeout = timeout
+
+    def fetch_text(self, url: str) -> str:
+        try:
+            response = requests.get(url, timeout=self.timeout)
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            raise FetcherError(f"HTTP error while fetching '{url}': {exc}") from exc
+        except requests.RequestException as exc:
+            raise FetcherError(f"Network error while fetching '{url}': {exc}") from exc
+        
+        if not response.text.strip():
+            raise FetcherError(f"Empty response from {url}")
+        
+        return response.text

tagsnip-1.0.0/tagsnip/validate.py

@@ -0,0 +1,5 @@
+from urllib.parse import urlparse
+
+def is_url(source: str) -> bool:
+    parsed = urlparse(source)
+    return parsed.scheme in ("http", "https") and bool(parsed.netloc)

tagsnip-1.0.0/tagsnip.egg-info/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: tagsnip
+Version: 1.0.0
+Summary: Python package for extracting tagged code snippets from local files or remote sources.
+Author: Rostislav Brož
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/brozrost/tagsnip
+Project-URL: Repository, https://github.com/brozrost/tagsnip
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: requests
+Dynamic: license-file
+
+`tagsnip` is a Python CLI tool for extracting tagged code snippets from local files or remote URLs, such as GitHub raw files. It serves as the backend for the tagsnip LaTeX package and enables dynamic inclusion of code snippets directly in LaTeX documents.
+
+<div align="center">
+  <a href="https://github.com/brozrost/tagsnip/actions">
+    <img src="https://github.com/brozrost/tagsnip/actions/workflows/python-package.yml/badge.svg">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/graphs/contributors">
+    <img src="https://img.shields.io/github/contributors/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/issues">
+    <img src="https://img.shields.io/github/issues/brozrost/tagsnip">
+  </a>
+  <a href="https://github.com/brozrost/tagsnip/pulls">
+    <img src="https://img.shields.io/github/issues-pr/brozrost/tagsnip">
+  </a>
+</div>
+
+## Installation
+
+Install `tagsnip` from PyPI:
+
+```sh
+pip install tagsnip
+```
+
+After installation, the command `tagsnip` should be available in your shell:
+
+```sh
+tagsnip --help
+```
+
+## Usage
+
+```sh
+tagsnip -s <source> -t <tag> [-o <output>]
+```
+
+```sh
+tagsnip -c <output>
+```
+
+### Command-line options
+```text
+-s, --source   Local file path or remote URL.  
+-t, --tag      Snippet tag to extract.  
+-o, --output   Optional output file path.
+-c, --cleanup  Removes temporary files at specified path. 
+```
+
+`--source` and `--tag` are mandatory arguments. If `--output` is provided, `tagsnip` writes the extracted snippet to the selected file. Otherwise, the snippet is written to `stdout`.
+
+When `--output` is used, `tagsnip` also writes a metadata file next to the output file. For example, if the output file is `snippet.tmp`, then the metadata file is `snippet.tmp.meta`. Both files can be removed using the `--cleanup` option.
+ 
+The metadata file contains the original start and end line numbers of the extracted snippet. This is used by the LaTeX package to preserve source line numbering.
+
+### Supported sources 
+
+- Local text files
+- Remote text files available over HTTP or HTTPS
+- GitHub raw file URLs
+
+### Tag format
+
+`tagsnip` extracts code between two matching markers:
+
+```text
+tagsnip-start <tag>
+...
+tagsnip-end <tag>
+```
+
+Tags are case-sensitive. Markers must appear on separate lines. The tag must follow the marker name after one space.
+
+For example:
+
+```python
+# tagsnip-start demo
+print("This line will be extracted.")
+# tagsnip-end demo
+```
+
+The marker lines themselves are not included in the extracted snippet.
+
+### Error handling
+
+`tagsnip` reports errors when:
+
+- The tag is not found
+- Start/end markers are mismatched
+- Multiple start markers exist
+- The source cannot be fetched
+
+## Quick example
+
+### Example source file
+
+```python
+# tagsnip-start demo
+def main():
+    x = 1
+    y = 2
+    print(x + y)
+
+    return 0
+# tagsnip-end demo
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())
+```
+
+### CLI usage
+
+Write the snippet to `stdout`:
+
+```bash    
+tagsnip -s example.py -t demo
+```
+
+Write the snippet to a file:
+```bash  
+tagsnip -s example.py -t demo -o out/out.txt
+```
+
+Get snippet from URL:
+```bash
+tagsnip -s https://raw.githubusercontent.com/brozrost/tagsnip/main/docs/example.py -t demo
+```
+
+Remove temporary files:
+```bash
+tagsnip -c out/out.txt
+```
+
+### Python usage
+
+```python
+from tagsnip import extractor
+
+snippet = extractor.extract_from_file("example.py", "demo")
+```
+
+## Compatibility note
+
+The Python package and the LaTeX package should be kept in sync. Backwards compatibility is not guaranteed.

tagsnip-1.0.0/tagsnip.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE.md
+README-pypi.md
+README.md
+pyproject.toml
+setup.cfg
+tagsnip/__init__.py
+tagsnip/__main__.py
+tagsnip/cli.py
+tagsnip/extractor.py
+tagsnip/fetcher.py
+tagsnip/validate.py
+tagsnip.egg-info/PKG-INFO
+tagsnip.egg-info/SOURCES.txt
+tagsnip.egg-info/dependency_links.txt
+tagsnip.egg-info/entry_points.txt
+tagsnip.egg-info/requires.txt
+tagsnip.egg-info/top_level.txt
+tests/test_extractor.py
+tests/test_fetcher.py

tagsnip-1.0.0/tagsnip.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tagsnip-1.0.0/tagsnip.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tagsnip = tagsnip.cli:main

tagsnip-1.0.0/tagsnip.egg-info/requires.txt

@@ -0,0 +1 @@
+requests

tagsnip-1.0.0/tagsnip.egg-info/top_level.txt

@@ -0,0 +1 @@
+tagsnip

tagsnip-1.0.0/tests/test_extractor.py

@@ -0,0 +1,91 @@
+from tagsnip import extractor
+
+PATH = "./docs/example.py"
+
+TEXT = """
+# tagsnip-start demo
+def main():
+    x = 1
+    y = 2
+    print(x + y)
+
+    return 0
+# tagsnip-end demo
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())"""
+
+OUT = """def main():
+    x = 1
+    y = 2
+    print(x + y)
+
+    return 0"""
+
+def test_extract_tagged_block():
+    snippet, first_line_num, last_line_num = extractor.extract_tagged_block(TEXT, "demo")
+    assert snippet == OUT
+
+def test_extract_from_file():
+    snippet, first_line_num, last_line_num = extractor.extract_from_file(PATH, "tag1")
+    assert snippet == OUT
+
+def test_missing_start_tag():
+    text = """
+    hello
+    # tagsnip-end 1
+    """
+
+    try:
+        extractor.extract_tagged_block(text, "1")
+        assert False, "Expected TagsnipError"
+    except extractor.TagsnipError as err:
+        assert str(err) == "Start tag not found for '1'"
+
+
+def test_missing_end_tag():
+    text = """
+    # tagsnip-start 1
+    hello
+    """
+
+    try:
+        extractor.extract_tagged_block(text, "1")
+        assert False, "Expected TagsnipError"
+    except extractor.TagsnipError as err:
+        assert str(err) == "End tag not found for '1'"
+
+
+def test_multiple_start_tags():
+    text = """
+    # tagsnip-start 1
+    hello
+    # tagsnip-start 1
+    world
+    # tagsnip-end 1
+    """
+
+    try:
+        extractor.extract_tagged_block(text, "1")
+        assert False, "Expected TagsnipError"
+    except extractor.TagsnipError as err:
+        assert str(err) == "Multiple start tags found for '1'"
+
+def test_missing_file():
+    try:
+        extractor.extract_from_file("./does_not_exist.py", "1")
+        assert False, "Expected TagsnipError"
+    except extractor.TagsnipError:
+        pass
+
+def main():
+    test_extract_tagged_block()
+    test_extract_from_file()
+    test_missing_start_tag()
+    test_missing_end_tag()
+    test_multiple_start_tags()
+    test_missing_file()
+
+if __name__ == "__main__":
+    main()

tagsnip-1.0.0/tests/test_fetcher.py

@@ -0,0 +1,4 @@
+from tagsnip import fetcher
+
+URL = "https://raw.githubusercontent.com/brozrost/tagsnip/refs/heads/main/docs/example.py"
+