Skip to main content

snex - snippet extractor

Project description

snex - snippet extractor

(Accompanying blog post)

Extract snippets for blog posts or examples.

How to use


pip install snex

Tag Snippets

Let's assume that you have a project in /path/to/your/project. You navigate to the region where you want to extract a snippet and tag it as follows (# is regarded as comment prefix):

# :snippet snippet-name-without-whitespace

def foobar():

# :endsnippet
  • Empty lines after the start and before the end are removed.
  • A snippet name is mandatory.
  • The snippet name is sanitized to prevent malicious code to overwrite arbitrary files on your system.

Advanced snippet tagging

You can also overwrite the lang config to use a different language for this snippet.

# :snippet snippet-name-without-whitespace lang: scala

Everything after the snippet name is parsed as YAML dict: { $text_after_snippet_name }, e.g. lang: scala, other_param: "hello world" is parsed as { lang: scala, other_param: "hello world" } YAML.

This means that you can also customise your parameter substitutions with a config like:

config {
  default {
    "output_template": "```{{lang}} - {{other_param}}\n{{{snippet}}}\n```\n",
    "valid_param_keys": [ "lang", "name", "other_param" ]

The output template is parsed as mustache template.


create a snex.conf.yaml in the root directory of a project you want to create snippets from:

  output_path: "snippets"
  comment_prefix: "# "
  comment_suffix: ""

  lang: "python"
  root: "src"
  glob: "**/*.py"

  comment_prefix: "# "
  lang: "python"
  path: ""

The config syntax is YAML.

You have 3 layers of settings in a section:

  1. the global default config in docs/snippets/
  2. the config section default in your snex.conf.yaml file (which overwrites the global default).
  3. the specific config section in your snex.conf.yaml (the section name is prefix for snippets default is reserved.). The configuration in a specific section overwrites the default section which overwrites the global default config.


You created a /path/to/your/project/snex.conf.yaml like described in the previous topic.

From the project directory

cd /path/to/your/project
snex run

This will read snex.conf.yaml in the current directory and dump the snippets into the configured output_path.

From a different directory

snex run /path/to/your/project

This will read /path/to/your/project/snex.conf.yaml and dump the snippets into the configured output_path.

From a different directory to a different snippet output directory

snex run /path/to/your/project /path/custom/snippet/output/dir

This will read /path/to/your/project/snex.conf.yaml and dump the snippets into /path/custom/snippet/output/dir.


This invocation will overwrite the output dir of all defined config sections. Which means that all snippets are dumped into the same directory.

Caveats (or features)

  • Snippets are overwritten without confirmation. This makes it easy to update everything, but you have to take care that you will not overwrite stuff you want to keep.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

snex-3000.2.1.tar.gz (14.6 kB view hashes)

Uploaded Source

Built Distribution

snex-3000.2.1-py3-none-any.whl (10.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page