tagsnip 1.0.0

Python package for extracting tagged code snippets from local files or remote sources.

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.

Installation

Install tagsnip from PyPI:

pip install tagsnip

After installation, the command tagsnip should be available in your shell:

tagsnip --help

Usage

tagsnip -s <source> -t <tag> [-o <output>]

tagsnip -c <output>

Command-line options

-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:

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:

# 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

# 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:

tagsnip -s example.py -t demo

Write the snippet to a file:

tagsnip -s example.py -t demo -o out/out.txt

Get snippet from URL:

tagsnip -s https://raw.githubusercontent.com/brozrost/tagsnip/main/docs/example.py -t demo

Remove temporary files:

tagsnip -c out/out.txt

Python usage

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.