papertrail 0.1.0__tar.gz

papertrail-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.3
+Name: papertrail
+Version: 0.1.0
+Summary: Add your description here
+Author: ed cuss
+Author-email: ed cuss <edcussmusic@gmail.com>
+Requires-Dist: attrs>=25.4.0
+Requires-Dist: black>=26.1.0
+Requires-Dist: io-adapters==0.2.2
+Requires-Dist: pytest>=9.0.2
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# papertrail
+
+### Motivation
+- Documentation can get out of date quickly
+- Sometimes its harder to explain what a function does in plain english than it is to just show what the input and outputs would be:
+    - e.g:
+        - "Multiply the value strings by the amount that is the key".
+    - vs
+        - `f({"a": 1, "b": 2, "c": 4}) == ['a', 'bb', 'cccc']`
+- Tests are the best form of documentation because they complain when they go out of sync
+- Doctests are an interesting way of writing tests however they can be fiddly and harder to set up than proper testing frameworks
+- Resorting to only using doctests means missing out on features like fixtures and parameterisation
+- Having some tests that are written in tests and some that are in doctests means keeping track of two places as the "source of truth"
+
+### Installation
+```shell
+uv add papertrail
+```
+
+### Example
+Use the `example` function to capture an example from a test to add to the docstring.
+
+Wrap the example around the function before the equality operation and the function result will be captured and added to the docstring of the function.
+This only happens if the tests pass!
+
+```python
+from papertrail import example
+
+def test_add():
+    assert example(add, 2, 3) == 5
+```
+
+This has captured the example and now once the tests are finished the docstring of the function will be updated like this:
+
+```python
+def add(a: int, b: int) -> int:
+    """Papertrail examples:
+
+        >>> add(2, 3) == 5
+        True
+    ::
+    """
+    return a + b
+```
+
+You can use it with parametrized tests too:
+
+```python
+@pytest.mark.parametrize(
+    ("args", "kwargs", "expected_result"),
+    [
+        pytest.param((2, 2), {}, 0),
+        pytest.param((2,), {"b": 3}, -1),
+    ],
+)
+def test_func_b(args, kwargs, expected_result):
+    assert example(func_b, *args, **kwargs) == expected_result
+```
+
+This captures all the cases and adds them to the functions docstring:
+
+```python
+def func_b(a: float, b: float) -> float:
+    """Simple docstring
+
+    Args:
+        a (float)
+        b (float)
+
+    Returns:
+        float
+
+    Papertrail examples:
+
+        >>> func_b(3, 4) == -1
+        True
+    ::
+    """
+    return a - b
+```
+
+# Repo map
+```
+├── .github
+│   └── workflows
+│       ├── ci_tests.yaml
+│       └── publish.yaml
+├── docs
+│   └── source
+│       └── conf.py
+├── src
+│   └── papertrail
+│       ├── adapters
+│       │   ├── __init__.py
+│       │   └── io_funcs.py              # The IO functions for the IO adapters
+│       ├── core
+│       │   ├── collection
+│       │   │   ├── __init__.py
+│       │   │   ├── example.py           # User entrypoint `example` and it's inner class `Example`
+│       │   │   ├── record.py
+│       │   │   └── recorder.py
+│       │   ├── transformation
+│       │   │   ├── __init__.py
+│       │   │   ├── ast_editing.py
+│       │   │   ├── format_examples.py
+│       │   │   └── transform.py         # Updates the the docstrings for all the funcs in the files in the example cache.
+│       │   ├── __init__.py
+│       │   └── logger.py
+│       ├── __init__.py
+│       └── __main__.py                  # the pytest hook for sessionfinish
+├── tests
+│   ├── _mock_data
+│   │   ├── mock_src
+│   │   │   ├── __init__.py
+│   │   │   ├── mod_a.py
+│   │   │   └── mod_b.py
+│   │   └── tests
+│   │       ├── __init__.py
+│   │       ├── conftest.py
+│   │       ├── test_mod_a.py
+│   │       └── test_mod_b.py
+│   ├── core
+│   │   ├── collection
+│   │   │   ├── __init__.py
+│   │   │   ├── test_example.py
+│   │   │   ├── test_record.py
+│   │   │   └── test_recorder.py
+│   │   └── transformation
+│   │       ├── __init__.py
+│   │       ├── test_ast_editing.py
+│   │       └── test_format_examples.py
+│   └── test_main.py
+├── .pre-commit-config.yaml
+├── README.md
+├── pyproject.toml
+├── ruff.toml
+└── uv.lock
+
+(generated with repo-mapper-rs)
+::
+```

papertrail-0.1.0/README.md

@@ -0,0 +1,141 @@
+# papertrail
+
+### Motivation
+- Documentation can get out of date quickly
+- Sometimes its harder to explain what a function does in plain english than it is to just show what the input and outputs would be:
+    - e.g:
+        - "Multiply the value strings by the amount that is the key".
+    - vs
+        - `f({"a": 1, "b": 2, "c": 4}) == ['a', 'bb', 'cccc']`
+- Tests are the best form of documentation because they complain when they go out of sync
+- Doctests are an interesting way of writing tests however they can be fiddly and harder to set up than proper testing frameworks
+- Resorting to only using doctests means missing out on features like fixtures and parameterisation
+- Having some tests that are written in tests and some that are in doctests means keeping track of two places as the "source of truth"
+
+### Installation
+```shell
+uv add papertrail
+```
+
+### Example
+Use the `example` function to capture an example from a test to add to the docstring.
+
+Wrap the example around the function before the equality operation and the function result will be captured and added to the docstring of the function.
+This only happens if the tests pass!
+
+```python
+from papertrail import example
+
+def test_add():
+    assert example(add, 2, 3) == 5
+```
+
+This has captured the example and now once the tests are finished the docstring of the function will be updated like this:
+
+```python
+def add(a: int, b: int) -> int:
+    """Papertrail examples:
+
+        >>> add(2, 3) == 5
+        True
+    ::
+    """
+    return a + b
+```
+
+You can use it with parametrized tests too:
+
+```python
+@pytest.mark.parametrize(
+    ("args", "kwargs", "expected_result"),
+    [
+        pytest.param((2, 2), {}, 0),
+        pytest.param((2,), {"b": 3}, -1),
+    ],
+)
+def test_func_b(args, kwargs, expected_result):
+    assert example(func_b, *args, **kwargs) == expected_result
+```
+
+This captures all the cases and adds them to the functions docstring:
+
+```python
+def func_b(a: float, b: float) -> float:
+    """Simple docstring
+
+    Args:
+        a (float)
+        b (float)
+
+    Returns:
+        float
+
+    Papertrail examples:
+
+        >>> func_b(3, 4) == -1
+        True
+    ::
+    """
+    return a - b
+```
+
+# Repo map
+```
+├── .github
+│   └── workflows
+│       ├── ci_tests.yaml
+│       └── publish.yaml
+├── docs
+│   └── source
+│       └── conf.py
+├── src
+│   └── papertrail
+│       ├── adapters
+│       │   ├── __init__.py
+│       │   └── io_funcs.py              # The IO functions for the IO adapters
+│       ├── core
+│       │   ├── collection
+│       │   │   ├── __init__.py
+│       │   │   ├── example.py           # User entrypoint `example` and it's inner class `Example`
+│       │   │   ├── record.py
+│       │   │   └── recorder.py
+│       │   ├── transformation
+│       │   │   ├── __init__.py
+│       │   │   ├── ast_editing.py
+│       │   │   ├── format_examples.py
+│       │   │   └── transform.py         # Updates the the docstrings for all the funcs in the files in the example cache.
+│       │   ├── __init__.py
+│       │   └── logger.py
+│       ├── __init__.py
+│       └── __main__.py                  # the pytest hook for sessionfinish
+├── tests
+│   ├── _mock_data
+│   │   ├── mock_src
+│   │   │   ├── __init__.py
+│   │   │   ├── mod_a.py
+│   │   │   └── mod_b.py
+│   │   └── tests
+│   │       ├── __init__.py
+│   │       ├── conftest.py
+│   │       ├── test_mod_a.py
+│   │       └── test_mod_b.py
+│   ├── core
+│   │   ├── collection
+│   │   │   ├── __init__.py
+│   │   │   ├── test_example.py
+│   │   │   ├── test_record.py
+│   │   │   └── test_recorder.py
+│   │   └── transformation
+│   │       ├── __init__.py
+│   │       ├── test_ast_editing.py
+│   │       └── test_format_examples.py
+│   └── test_main.py
+├── .pre-commit-config.yaml
+├── README.md
+├── pyproject.toml
+├── ruff.toml
+└── uv.lock
+
+(generated with repo-mapper-rs)
+::
+```

papertrail-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "papertrail"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "ed cuss", email = "edcussmusic@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "attrs>=25.4.0",
+    "black>=26.1.0",
+    "io-adapters==0.2.2",
+    "pytest>=9.0.2",
+    "python-dotenv>=1.2.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.151.4",
+    "ipykernel>=7.1.0",
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "repo-mapper-rs>=0.4.0",
+    "ruff>=0.14.14",
+    "sphinx>=9.0.4",
+]
+
+# [project.entry-points.pytest11]
+# papertrail = "papertrail.__main__"
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+omit = [
+    "src/papertrail/__main__.py",
+    "src/papertrail/core/logger.py"
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 95

papertrail-0.1.0/src/papertrail/__init__.py

@@ -0,0 +1,3 @@
+from papertrail.core import example
+
+__all__ = ["example"]

papertrail-0.1.0/src/papertrail/__main__.py

@@ -0,0 +1,30 @@
+"""repo-map-desc: the pytest hook for sessionfinish
+
+Calls an inner main function for testability
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from typing import Any
+
+import pytest
+from _pytest.config import ExitCode
+from _pytest.main import Session
+
+from papertrail.core.collection.recorder import _RECORDER, Recorder
+from papertrail.core.transformation.transform import update_modified_docstrings
+
+
+@pytest.hookimpl(hookwrapper=True, trylast=True)
+def pytest_sessionfinish(
+    session: Session,  # noqa: ARG001
+    exitstatus: int | ExitCode,  # noqa: ARG001
+) -> Generator[Any, None, None]:
+    yield
+    main(_RECORDER)
+
+
+def main(recorder: Recorder) -> None:
+    recorder.prepare_files().write_examples()
+    update_modified_docstrings(recorder.adapter, recorder.path)

papertrail-0.1.0/src/papertrail/adapters/io_funcs.py

@@ -0,0 +1,43 @@
+"""repo-map-desc: The IO functions for the IO adapters
+
+Currently only uses simple registries
+"""
+
+import json
+from enum import Enum, unique
+from pathlib import Path
+from typing import Any
+
+from io_adapters import register_read_fn, register_write_fn
+
+
+@unique
+class FileType(Enum):
+    STR = "str"
+    JSON = "json"
+
+
+@register_read_fn(FileType.STR)
+def read_str(path: str, **kwargs: dict[str, Any]) -> str:
+    return Path(path).read_text(**kwargs)
+
+
+@register_write_fn(FileType.STR)
+def write_str(data: str, path: str, **kwargs: dict[str, Any]) -> None:
+    _make_dirs(path).write_text(data, **kwargs)
+
+
+@register_read_fn(FileType.JSON)
+def read_json(path: str, **kwargs: dict[str, Any]) -> dict:
+    return json.loads(Path(path).read_text(), **kwargs)
+
+
+@register_write_fn(FileType.JSON)
+def write_json(data: str, path: str, **kwargs: dict[str, Any]) -> None:
+    _make_dirs(path).write_text(json.dumps(data, indent=2, sort_keys=False, default=str, **kwargs))
+
+
+def _make_dirs(path: str) -> Path:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path

papertrail-0.1.0/src/papertrail/core/__init__.py

@@ -0,0 +1,4 @@
+from papertrail.core.collection import example
+from papertrail.core.logger import REPO_ROOT, logger
+
+__all__ = ["REPO_ROOT", "example", "logger"]

papertrail-0.1.0/src/papertrail/core/collection/__init__.py

@@ -0,0 +1,5 @@
+from papertrail.core.collection.example import Example, example
+from papertrail.core.collection.record import ExampleRecord
+from papertrail.core.collection.recorder import Recorder
+
+__all__ = ["Example", "ExampleRecord", "Recorder", "example"]

papertrail-0.1.0/src/papertrail/core/collection/example.py

@@ -0,0 +1,121 @@
+"""repo-map-desc: User entrypoint `example` and it's inner class `Example`
+
+The equality operator is where the magic happens
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, TypeVar
+
+import attrs
+
+from papertrail.core.collection.record import ExampleRecord
+from papertrail.core.collection.recorder import _RECORDER, Recorder
+
+T = TypeVar("T")
+
+
+@attrs.define
+class Example:
+    fn: Callable
+    args: tuple[Any, ...]
+    kwargs: dict[str, Any]
+    value: Any
+    recorder: Recorder
+
+    def __eq__(self, expected: T) -> bool:
+        record = ExampleRecord(
+            fn_name=self.fn.__name__,
+            module=self.fn.__module__,
+            src_file=str(Path(inspect.getsourcefile(self.fn))),
+            args=self.args,
+            kwargs=self.kwargs,
+            returned=self.value,
+            expected=expected,
+        )
+
+        self.recorder.record_example(record)
+        return self.value == expected
+
+    def __hash__(self) -> int:
+        hash_value = "".join(
+            [
+                self.fn.__name__,
+                self.fn.__module__,
+                str(self.args),
+                str(self.kwargs),
+                str(self.value),
+            ]
+        )
+        return hash(hash_value)
+
+
+def example(fn: Callable, *args: tuple[Any, ...], **kwargs: dict[str, Any]) -> Example:
+    """Capture an example from a test to add to the docstring.
+
+    Wrap the example around the function before the equality operation and the function result will be captured and added to the docstring of the function.
+    This only happens if the tests pass!
+
+    .. code-block:: python
+
+        from papertrail import example
+
+        def test_add():
+            assert example(add, 2, 3) == 5
+
+
+    This has captured the example and now once the tests are finished the docstring of the function will be updated like this:
+
+    .. code-block:: python
+
+        def add(a: int, b: int) -> int:
+            \"\"\"Papertrail examples:
+
+                >>> add(2, 3) == 5
+                True
+            ::
+            \"\"\"
+            return a + b
+
+
+    You can use it with parametrized tests too:
+
+    .. code-block:: python
+
+        @pytest.mark.parametrize(
+            ("args", "kwargs", "expected_result"),
+            [
+                pytest.param((2, 2), {}, 0),
+                pytest.param((2,), {"b": 3}, -1),
+            ],
+        )
+        def test_func_b(args, kwargs, expected_result):
+            assert example(func_b, *args, **kwargs) == expected_result
+
+    This captures all the cases and adds them to the functions docstring:
+
+    .. code-block:: python
+
+        def func_b(a: float, b: float) -> float:
+            \"\"\"Simple docstring
+
+            Args:
+                a (float)
+                b (float)
+
+            Returns:
+                float
+
+            Papertrail examples:
+
+                >>> func_b(3, 4) == -1
+                True
+            ::
+            \"\"\"
+            return a - b
+    """
+    value = fn(*args, **kwargs)
+    return Example(fn, args, kwargs, value, recorder=_RECORDER)

papertrail-0.1.0/src/papertrail/core/collection/record.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+import attrs
+
+
+@attrs.define(frozen=True, eq=True)
+class ExampleRecord:
+    fn_name: str
+    module: str
+    src_file: str
+    args: tuple[Any, ...]
+    kwargs: dict[str, Any]
+    returned: Any
+    expected: Any
+
+    def to_dict(self) -> dict[str, str]:
+        return attrs.asdict(self)

papertrail-0.1.0/src/papertrail/core/collection/recorder.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Self
+
+import attrs
+from io_adapters import IoAdapter, RealAdapter
+
+from papertrail.adapters.io_funcs import FileType
+from papertrail.core.collection.record import ExampleRecord
+
+
+@attrs.define
+class Recorder:
+    path: str | Path = "./.papertrail_cache/examples.json"
+    records: list[ExampleRecord] = attrs.field(factory=list)
+    adapter: IoAdapter = attrs.field(factory=RealAdapter)
+    files: dict = attrs.field(factory=dict)
+
+    def __attrs_post_init__(self) -> None:
+        self.path = Path(self.path)
+
+    def record_example(self, example: ExampleRecord) -> Self:
+        self.records.append(example)
+        return self
+
+    def prepare_files(self) -> Self:
+        self.files[(self.path, FileType.JSON)] = [r.to_dict() for r in self.records]
+        self.files[(self.path.parent / ".gitignore", FileType.STR)] = (
+            "# automatically created by papertrail\n*"
+        )
+        return self
+
+    def write_examples(self) -> Self:
+        for k, data in self.files.items():
+            path, file_type = k
+            self.adapter.write(data, path, file_type)
+        return self
+
+
+_RECORDER = Recorder()

papertrail-0.1.0/src/papertrail/core/logger.py

@@ -0,0 +1,31 @@
+import logging
+import os
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+logger = logging.getLogger(__name__)
+logger.propagate = False
+
+REPO_ROOT = Path(__file__).absolute().parents[3]
+load_dotenv(f"{REPO_ROOT}/envs/.env")
+
+if os.getenv("LOGGING_ENABLED", "false").lower() == "true":
+    formatter = logging.Formatter(
+        "%(asctime)s | %(levelname)-8s [%(filename)s:%(lineno)d:%(funcName)s] %(message)s"
+    )
+    logger.setLevel(logging.DEBUG)
+    stream_handler = logging.StreamHandler()
+    stream_handler.setLevel(logging.DEBUG)
+    stream_handler.setFormatter(formatter)
+
+    log_path = f"{REPO_ROOT}/logs/app.log"
+    os.makedirs(os.path.dirname(log_path), exist_ok=True)
+
+    file_handler = RotatingFileHandler(log_path, maxBytes=2_000_000, backupCount=1)
+    file_handler.setLevel(logging.DEBUG)
+    file_handler.setFormatter(formatter)
+
+    logger.addHandler(stream_handler)
+    logger.addHandler(file_handler)

papertrail-0.1.0/src/papertrail/core/transformation/ast_editing.py

@@ -0,0 +1,84 @@
+import ast
+import re
+from typing import Self
+
+import attrs
+
+
+def update_function_docstrings(code: str, examples: dict[str, str]) -> str:
+    replacements = create_replacements(code, examples)
+    return replace_docstrings(code, replacements)
+
+
+@attrs.define(frozen=True)
+class DocString:
+    doc: str
+    start_line: int
+    end_line: int
+    indent: str = "    "
+
+    @classmethod
+    def from_doc_node(cls, node: ast.AST) -> Self:
+        return cls(node.value.value.rstrip(), node.lineno - 1, node.end_lineno)
+
+    @classmethod
+    def from_non_doc_node(cls, node: ast.AST) -> Self:
+        start = node.lineno - 1
+        return cls("", start, start)
+
+    def with_example(self, example: str) -> Self:
+        example = "".join(
+            [
+                f"{self.indent}{line}" if line.strip() else line
+                for line in example.splitlines(keepends=True)
+            ]
+        )
+        pattern = r"(?ms)^[ \t]*Papertrail examples:\n.*?\n[ \t]*::"
+        replaced_doc, n = re.subn(pattern, example, self.doc)
+
+        new_doc = replaced_doc if n else f"{self.doc}\n\n{example}"
+        return DocString(new_doc.strip(), self.start_line, self.end_line)
+
+    def to_doc(self) -> str:
+        return f'{self.indent}"""{self.doc.strip()}\n{self.indent}"""\n'
+
+
+def create_replacements(code: str, examples: dict[str, str]) -> list[DocString]:
+    tree = ast.parse(code)
+
+    replacements = []
+
+    for node in ast.walk(tree):
+        if not _is_fn_with_body(node) or not (example := examples.get(node.name, "")):
+            continue
+
+        first = node.body[0]
+
+        if _is_docstring(first):
+            docstring = DocString.from_doc_node(first)
+        else:
+            docstring = DocString.from_non_doc_node(first)
+
+        replacements.append(docstring.with_example(example))
+
+    return replacements
+
+
+def replace_docstrings(code: str, replacements: list[DocString]) -> str:
+    lines = code.splitlines(keepends=True)
+    for doc in reversed(replacements):
+        lines[doc.start_line : doc.end_line] = [doc.to_doc()]
+
+    return "".join(lines)
+
+
+def _is_fn_with_body(node: ast.AST) -> bool:
+    return isinstance(node, ast.FunctionDef) and node.body
+
+
+def _is_docstring(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Expr)
+        and isinstance(node.value, ast.Constant)
+        and isinstance(node.value.value, str)
+    )

papertrail-0.1.0/src/papertrail/core/transformation/format_examples.py

@@ -0,0 +1,50 @@
+from collections import defaultdict
+
+import black
+
+from papertrail.core.collection.record import ExampleRecord
+
+
+def collect_example_strs(examples: list[dict]) -> dict[str, dict[str, list[str]]]:
+    fn_examples = defaultdict(_inner)
+
+    for data in examples:
+        ex = ExampleRecord(**data)
+
+        if ex.returned != ex.expected:
+            continue
+
+        fn_examples[ex.src_file][ex.fn_name].append(example_to_str(ex))
+
+    return {k: dict(v) for k, v in fn_examples.items()}
+
+
+def _inner() -> defaultdict:
+    return defaultdict(list)
+
+
+def example_to_str(example: ExampleRecord) -> str:
+    sig = ", ".join(
+        part
+        for part in (
+            ", ".join(map(str, example.args)),
+            ", ".join(f"{k}={v}" for k, v in example.kwargs.items()),
+        )
+        if part
+    )
+    expr = f"{example.fn_name}({sig}) == {example.returned}"
+    formatted = black.format_str(expr, mode=black.Mode())
+    lines = formatted.rstrip().splitlines()
+    doctest = "\n".join(
+        f"{'    >>>' if i == 0 else '    ...'} {line}" for i, line in enumerate(lines)
+    )
+    return f"{doctest}\n    True"
+
+
+def reduce_examples_to_example_str(
+    fn_examples: dict[str, dict[str, list[str]]],
+) -> dict[str, dict[str, str]]:
+    return {
+        path: {k: "Papertrail examples:\n\n" + "\n\n".join(v) + "\n::" for k, v in fn.items()}
+        for path, fn in fn_examples.items()
+    }

papertrail-0.1.0/src/papertrail/core/transformation/transform.py

@@ -0,0 +1,24 @@
+"""repo-map-desc: Updates the the docstrings for all the funcs in the files in the example cache.
+
+This is the main entry point for the transformation module.
+"""
+
+from io_adapters import IoAdapter
+
+from papertrail.adapters.io_funcs import FileType
+from papertrail.core.transformation.ast_editing import update_function_docstrings
+from papertrail.core.transformation.format_examples import (
+    collect_example_strs,
+    reduce_examples_to_example_str,
+)
+
+
+def update_modified_docstrings(adapter: IoAdapter, examples_cache_path: str) -> None:
+    examples = adapter.read(examples_cache_path, FileType.JSON)
+    reduced_examples = reduce_examples_to_example_str(collect_example_strs(examples))
+
+    for path, module_examples in reduced_examples.items():
+        code = adapter.read(path, FileType.STR)
+        new_code = update_function_docstrings(code, module_examples)
+        if new_code != code:
+            adapter.write(new_code, path, FileType.STR)