Snip core

Be able to search and replace editable regions within text files

drain_swamp_snippet.snip.__all__: tuple[str, str] = ("ReplaceResult", "Snip")

Modules exports

drain_swamp_snippet.snip._logger: logging.Logger

Module level logger

drain_swamp_snippet.snip.mod_dotted_path: str = "drain_swamp_snippet.snip"

Module dotted path

drain_swamp_snippet.snip.is_module_debug: bool

Module level debug flag

class drain_swamp_snippet.snip.ReplaceResult(value)

Snippet replace result possibilities.

For membership checking, equality comparison is supported

oh_this_is_bad = ReplaceResult.VALIDATE_FAIL
assert oh_this_is_bad == ReplaceResult.VALIDATE_FAIL

hmm_looks_promising = ReplaceResult.REPLACED
assert hmm_looks_promising != oh_this_is_bad
VALIDATE_FAIL

Validation failed. Either nested or no matching start/end token

NO_MATCH

No snippet with specified snippet code

REPLACED

Snippet contents replaced

NO_CHANGE

Snippet contents same as existing, so replace skipped

class drain_swamp_snippet.snip.Snip(fname)

jinja2 templates is time consuming to get the spacing right. A snippet is an easier alternative

TOKEN_START: str = "# @@@ editable"

Beginning token of an editable section. Optionally can be followed by one whitespace and a str id. ID can contain alphanumberic characters and underscore. If there is no id, a file can contain at most one editable section

TOKEN_END: str = "# @@@ end\n"

End token denotes end of editable section. A trailing newline is expected

PATTERN_W_ID: re.Pattern

Compiled regex which allows for an optional id. Captures two groups: id and contents.

Removed regex which doesn’t not support optional id for editable sections

.* means capture greedily. .*? means shortest path match

See also

(?s) means single line mode. equivalent to compile flag re.DOTALL

regex – modifiers

Variables:

fname (str | pathlib.Path) – the file in/near the project to update

Raises:

  • TypeError – Unsupported type, fname can be either a str or Path

Todo

Take editable file paths from pyproject.toml

contents(id_=None)

Get snippet contents.

If only one snippet and id no provided, infer want the only available snippet.

Parameters:

id_ (str | None) – Default None. snippet_co. If know there is only one snippet, my opt to not specify

Returns:

snippet contents and actual snippet_co. Possible to infer snippet if only one and id not provided

Return type:

tuple[str, str] | drain_swamp_snippet.ReplaceResult

Note

context hint

By providing a context hint, could achieve a better guess and have some awareness of context

get_file()

Read the file.

Returns:

file contents

Return type:

str

Raises:
is_file_ok()

Try to grab permitted editable files from pyproject.toml.

Returns:

True if file has absolute and is permitted

Return type:

bool

Todo

r/w ??

What about confirm: readable and writable!

property is_infer

id is None or empty str. snippet_co is taken from snippet.

Returns:

True if infer snippet_co otherwise False

Return type:

bool

property path_file

Path has not necessarily been checked. Run thru a validator func.

Returns:

A raw path either relative or absolute

Return type:

pathlib.Path

print()

Human readable summary of snippets.

Returns:

tuple of snippet_co and snippet contents

Return type:

list[tuple[str, str]] | drain_swamp_snippet.ReplaceResult

replace(replacement, id_='')

Find snippet with id_. If no id_, provided the file may contain at most one snippet.

id_ should be a cringe worthy cultural reference to an object or minor character! One id should be changed for every minor version release or PR

In the changelog, in the commit, the top most lines is encouraged to be

- style: [a cringe worthy cultural reference]
Parameters:

  • replacement (str) – Just the content. Will be substituted within the file

  • id_ (str | None) – Default empty string. So as to support multiple snippets within a file. If only intended ever to have one snippet, empty string is appropriate

Returns:

VALIDATE_FAIL, NO_MATCH, REPLACED, NO_CHANGE

Return type:

drain_swamp_snippet.ReplaceResult

Raises:

  • TypeError – Unsupported type, replacement contents must be a str

property snippets

Get all snippets. No filtering by snippet_co.

Returns:

tuple of snippet_co and snippet contents

Return type:

list[tuple[str, str]] | drain_swamp_snippet.ReplaceResult

validate()

Validate target file contents are safe.

All checks must pass. Over time add additional checks

Returns:

All checks passed

Return type:

bool