ipython-postfix-completion 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

ipython_postfix_completion/__init__.py

@@ -35,6 +35,19 @@ _NO_MAGIC_ATTR = object()
 _ACTIVE_STATE: PostfixState | None = None
 _VAR_TEMPLATE = "key = {expr}"
 _VAR_PLACEHOLDER = "key"
+_FOR_TEMPLATE = "for item in {expr}:\n{indent}    pass"
+_FORI_TEMPLATE = "for i, value in enumerate({expr}):\n{indent}    pass"
+_IF_TEMPLATE = "if {expr}:\n{indent}    pass"
+_EF_TEMPLATE = (
+    "if {expr}:\n{indent}    pass\n{indent}elif cond:\n{indent}    pass"
+    "\n{indent}else:\n{indent}    pass"
+)
+_TEMPLATE_PLACEHOLDERS = {
+    "for": (_FOR_TEMPLATE, ("item", "pass")),
+    "fori": (_FORI_TEMPLATE, ("i", "value", "pass")),
+    "if": (_IF_TEMPLATE, ("pass",)),
+    "ef": (_EF_TEMPLATE, ("pass", "cond", "pass", "pass")),
+}
 _PLACEHOLDER_ATTR = "_postfix_completion_placeholder"
 _OPENING_BRACKETS = {"(": ")", "[": "]", "{": "}"}
 _CLOSING_BRACKETS = {closer: opener for opener, closer in _OPENING_BRACKETS.items()}
@@ -59,8 +72,11 @@ DEFAULT_TEMPLATES: dict[str, str] = {
     "var": _VAR_TEMPLATE,
     "await": "await {expr}",
     "return": "return {expr}",
-    "if": "if {expr}:\n{indent}    ",
+    "if": _IF_TEMPLATE,
     "while": "while {expr}:\n{indent}    ",
+    "for": _FOR_TEMPLATE,
+    "fori": _FORI_TEMPLATE,
+    "ef": _EF_TEMPLATE,
     "raise": "raise {expr}",
     "yield": "yield {expr}",
     "str": "str({expr})",
@@ -68,6 +84,8 @@ DEFAULT_TEMPLATES: dict[str, str] = {
     "set": "set({expr})",
     "dict": "dict({expr})",
     "tuple": "tuple({expr})",
+    "type": "type({expr})",
+    "range": "range({expr})",
 }
 
 
@@ -143,6 +161,30 @@ def _render_template(template: str, expr: str, indent: str = "") -> str:
     return _FORMATTER.format(template, expr=expr, indent=indent)
 
 
+def _is_integer_literal(expr: str) -> bool:
+    try:
+        node = ast.parse(expr, mode="eval").body
+    except SyntaxError:
+        return False
+    if isinstance(node, ast.Constant):
+        return type(node.value) is int
+    return (
+        isinstance(node, ast.UnaryOp)
+        and isinstance(node.op, (ast.UAdd, ast.USub))
+        and _is_integer_literal(ast.unparse(node.operand))
+    )
+
+
+def _render_candidate(name: str, template: str, expr: str, indent: str = "") -> str:
+    wraps_integer = _is_integer_literal(expr) and (
+        (name == "for" and template == _FOR_TEMPLATE)
+        or (name == "fori" and template == _FORI_TEMPLATE)
+    )
+    if wraps_integer:
+        expr = f"range({expr})"
+    return _render_template(template, expr, indent)
+
+
 @dataclass
 class PostfixState:
     matcher: Callable[[CompletionContext], dict]
@@ -244,7 +286,7 @@ def _effective_templates(state: PostfixState | None = None) -> dict[str, str]:
 def _apply_template(
     name: str, expr: str, indent: str = "", state: PostfixState | None = None
 ) -> str:
-    return _render_template(_effective_templates(state)[name], expr, indent)
+    return _render_candidate(name, _effective_templates(state)[name], expr, indent)
 
 
 def _postfix_candidates(
@@ -264,7 +306,7 @@ def _postfix_candidates(
         if (name == prefix if exact else name.startswith(prefix))
     ]
     return f"{expr}.{prefix}", [
-        _render_template(templates[name], expr, indent) for name in names
+        _render_candidate(name, templates[name], expr, indent) for name in names
     ]
 
 
@@ -278,7 +320,7 @@ def _template_name(
     for name, template in _effective_templates(state).items():
         if not name.startswith(prefix):
             continue
-        if _render_template(template, expr, indent) == expansion:
+        if _render_candidate(name, template, expr, indent) == expansion:
             return name
     return None
 
@@ -306,7 +348,28 @@ def _expand_buffer(buffer) -> bool:
     buffer.delete_before_cursor(len(matched_fragment))
     expansion_start = buffer.cursor_position
     buffer.insert_text(candidates[0])
+    placeholder_config = (
+        _TEMPLATE_PLACEHOLDERS.get(parsed[2]) if parsed is not None else None
+    )
     if (
+        parsed is not None
+        and placeholder_config is not None
+        and _effective_templates().get(parsed[2]) == placeholder_config[0]
+    ):
+        search_from = 0
+        ranges = []
+        for placeholder_text in placeholder_config[1]:
+            start = candidates[0].index(placeholder_text, search_from)
+            end = start + len(placeholder_text)
+            ranges.append((start, end))
+            search_from = end
+        _select_placeholders(
+            buffer,
+            expansion_start,
+            ranges,
+            buffer.cursor_position,
+        )
+    elif (
         parsed is not None
         and parsed[2] == "var"
         and _effective_templates().get("var") == _VAR_TEMPLATE
@@ -321,35 +384,93 @@ def _expand_buffer(buffer) -> bool:
 
 
 def _select_placeholder(buffer, start: int, end: int, final_cursor: int) -> None:
+    _select_placeholders(buffer, start, [(start, end)], final_cursor, absolute=True)
+
+
+def _select_placeholders(
+    buffer,
+    start: int,
+    ranges: list[tuple[int, int]],
+    final_cursor: int,
+    *,
+    absolute: bool = False,
+    index: int = 0,
+) -> None:
     from prompt_toolkit.selection import SelectionState, SelectionType
 
-    buffer.cursor_position = end
-    buffer.selection_state = SelectionState(start, SelectionType.CHARACTERS)
+    if not absolute:
+        ranges = [(start + left, start + right) for left, right in ranges]
+    setattr(buffer, _PLACEHOLDER_ATTR, (ranges, index, final_cursor))
+    left, right = ranges[index]
+    buffer.cursor_position = right
+    buffer.selection_state = SelectionState(left, SelectionType.CHARACTERS)
     buffer.selection_state.enter_shift_mode()
-    setattr(buffer, _PLACEHOLDER_ATTR, (start, end, final_cursor))
 
 
 def _has_active_placeholder(buffer) -> bool:
     placeholder = getattr(buffer, _PLACEHOLDER_ATTR, None)
     selection = buffer.selection_state
-    if placeholder is None or selection is None:
+    if placeholder is None:
         return False
-    start, end, _ = placeholder
-    return (
-        selection.shift_mode
+    ranges, index, _ = placeholder
+    start, end = ranges[index]
+    return (selection is None and len(ranges) > 1) or (
+        selection is not None
+        and selection.shift_mode
         and selection.original_cursor_position == start
         and buffer.cursor_position == end
-        and buffer.text[start:end] == _VAR_PLACEHOLDER
+        and (len(ranges) > 1 or buffer.text[start:end] == _VAR_PLACEHOLDER)
     )
 
 
 def _accept_placeholder(buffer) -> bool:
     if not _has_active_placeholder(buffer):
         return False
-    _, _, final_cursor = getattr(buffer, _PLACEHOLDER_ATTR)
-    buffer.exit_selection()
-    buffer.cursor_position = final_cursor
-    delattr(buffer, _PLACEHOLDER_ATTR)
+    ranges, index, final_cursor = _update_placeholder_after_edit(buffer)
+    if buffer.selection_state is not None:
+        buffer.exit_selection()
+    if index + 1 < len(ranges):
+        _select_placeholders(
+            buffer, 0, ranges, final_cursor, absolute=True, index=index + 1
+        )
+    else:
+        delattr(buffer, _PLACEHOLDER_ATTR)
+        buffer.cursor_position = final_cursor
+    return True
+
+
+def _update_placeholder_after_edit(buffer):
+    ranges, index, final_cursor = getattr(buffer, _PLACEHOLDER_ATTR)
+    if buffer.selection_state is None:
+        start, old_end = ranges[index]
+        new_end = buffer.cursor_position
+        delta = new_end - old_end
+        final_cursor += delta
+        ranges = [
+            (start, new_end)
+            if stop == index
+            else (left + delta, right + delta)
+            if stop > index
+            else (left, right)
+            for stop, (left, right) in enumerate(ranges)
+        ]
+        setattr(buffer, _PLACEHOLDER_ATTR, (ranges, index, final_cursor))
+    return ranges, index, final_cursor
+
+
+def _reverse_placeholder(buffer) -> bool:
+    if not _has_active_placeholder(buffer):
+        return False
+    ranges, index, final_cursor = _update_placeholder_after_edit(buffer)
+    previous_index = max(0, index - 1)
+    _select_placeholders(
+        buffer,
+        0,
+        ranges,
+        final_cursor,
+        absolute=True,
+        index=previous_index,
+    )
     return True
 
 
@@ -657,6 +778,10 @@ def _make_key_bindings(state: PostfixState | None = None):
     def accept_placeholder(event) -> None:
         _accept_placeholder(event.current_buffer)
 
+    @key_bindings.add("s-tab", filter=has_active_placeholder)
+    def reverse_placeholder(event) -> None:
+        _reverse_placeholder(event.current_buffer)
+
     @key_bindings.add("enter", filter=has_active_placeholder)
     def accept_placeholder_with_enter(event) -> None:
         _accept_placeholder(event.current_buffer)

ipython_postfix_completion-0.2.1.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: ipython-postfix-completion
+Version: 0.2.1
+Summary: Configurable postfix completion extension for IPython.
+Author: IPython Postfix Completion Contributors
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/fishandsheep/ipython-postfix-completion
+Project-URL: Repository, https://github.com/fishandsheep/ipython-postfix-completion
+Project-URL: Issues, https://github.com/fishandsheep/ipython-postfix-completion/issues
+Project-URL: Changelog, https://github.com/fishandsheep/ipython-postfix-completion/blob/main/CHANGELOG.md
+Keywords: ipython,completion,postfix,extension
+Classifier: Framework :: IPython
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipython<10,>=9.0
+Requires-Dist: traitlets>=5.13
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ipython-postfix-completion[test]; extra == "dev"
+Dynamic: license-file
+
+# IPython Postfix Completion
+
+Complete Python expressions with postfix templates in IPython: type an
+expression, a dot, and a template name, then press Tab.
+
+## Install
+
+```bash
+uv tool install ipython --with ipython-postfix-completion
+```
+
+Start IPython and load the extension:
+
+```python
+%load_ext ipython_postfix_completion
+```
+
+## Common Templates
+
+`items.for<Tab>` creates a loop. Tab selects `item`, then `pass`; type to
+replace a selection.
+
+```python
+for item in items:
+    pass
+```
+
+An integer literal is wrapped in `range(...)`, so `10.for<Tab>` produces
+`for item in range(10):`.
+
+`items.fori<Tab>` creates an indexed loop. Tab selects `i`, `value`, then
+`pass`. For an integer literal, it uses `enumerate(range(n))`.
+
+`condition.if<Tab>` creates an `if` block with a selected `pass`:
+
+```python
+if condition:
+    pass
+```
+
+`condition.ef<Tab>` creates `if`/`elif`/`else` branches. Tab selects each
+placeholder in order: `pass`, `cond`, `pass`, `pass`. The `cond` selection
+does not include its colon.
+
+Other built-ins: `print`, `len`, `not`, `par`, `var`, `await`, `return`,
+`while`, `raise`, `yield`, `str`, `list`, `set`, `dict`, `tuple`, `type`, and
+`range`. Use `%postfix_template list` to see their expansions.
+
+Shift+Tab moves back to the previous placeholder. Custom Tab navigation is
+supported in terminal IPython.
+
+## Load Automatically
+
+The default configuration file is:
+
+```text
+~/.ipython/profile_default/ipython_config.py
+```
+
+Create it with:
+
+```bash
+ipython profile create
+```
+
+Add the extension and any persistent templates there:
+
+```python
+c.InteractiveShellApp.extensions = ["ipython_postfix_completion"]
+c.PostfixCompletionConfig.templates = {
+    "debug": "print({expr}=)",
+}
+```
+
+`IPYTHONDIR` and `--ipython-dir` can change the configuration directory. Use
+`ipython locate profile default` to find the active profile. See the [official
+IPython configuration guide](https://ipython.readthedocs.io/en/stable/development/config.html).
+
+For runtime template commands, detailed behavior, and contributor or release
+steps, see [the extended guide](docs/REFERENCE.md).

ipython_postfix_completion-0.2.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+ipython_postfix_completion/__init__.py,sha256=OeNt29f_YF-MT01GxZu233B28Il7xUuWLOVLiSdWEPk,34444
+ipython_postfix_completion-0.2.1.dist-info/licenses/LICENSE,sha256=omLR-7QW1K3l6AG7ih1N5L8Z58UY-ROrQL82ANN9PnM,1547
+ipython_postfix_completion-0.2.1.dist-info/METADATA,sha256=uLGeW00R_fljuKcFU9TGUX8UUaC6B9EreQvi_qmfVnE,3655
+ipython_postfix_completion-0.2.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ipython_postfix_completion-0.2.1.dist-info/top_level.txt,sha256=W2sJCvsBheoCB2nbzJeD7-p5PR6lVDNicVLxNxmeraY,27
+ipython_postfix_completion-0.2.1.dist-info/RECORD,,

ipython_postfix_completion-0.2.0.dist-info/METADATA

@@ -1,282 +0,0 @@
-Metadata-Version: 2.4
-Name: ipython-postfix-completion
-Version: 0.2.0
-Summary: Configurable postfix completion extension for IPython.
-Author: IPython Postfix Completion Contributors
-License-Expression: BSD-3-Clause
-Project-URL: Homepage, https://github.com/fishandsheep/ipython-postfix-completion
-Project-URL: Repository, https://github.com/fishandsheep/ipython-postfix-completion
-Project-URL: Issues, https://github.com/fishandsheep/ipython-postfix-completion/issues
-Project-URL: Changelog, https://github.com/fishandsheep/ipython-postfix-completion/blob/main/CHANGELOG.md
-Keywords: ipython,completion,postfix,extension
-Classifier: Framework :: IPython
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: ipython<10,>=9.0
-Requires-Dist: traitlets>=5.13
-Provides-Extra: test
-Requires-Dist: pytest>=7; extra == "test"
-Provides-Extra: dev
-Requires-Dist: build; extra == "dev"
-Requires-Dist: pip-audit>=2.7; extra == "dev"
-Requires-Dist: ruff>=0.8; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: ipython-postfix-completion[test]; extra == "dev"
-Dynamic: license-file
-
-# IPython Postfix Completion
-
-Configurable postfix completion extension for IPython.
-
-Package on PyPI: `ipython-postfix-completion`
-
-## Install
-
-Install into the current Python environment with `uv`:
-
-```bash
-uvx --with ipython-postfix-completion ipython
-```
-
-Install into the current ipython environment with `uv`:
-
-```bash
-uv tool install ipython --with ipython-postfix-completion
-```
-
-## Load
-
-Inside IPython:
-
-```python
-%load_ext ipython_postfix_completion
-```
-
-To load it automatically, add this to `ipython_config.py`:
-
-```python
-c.InteractiveShellApp.extensions = ["ipython_postfix_completion"]
-```
-
-Smart Tab key bindings are supported in terminal IPython. Postfix matcher
-completion can also work in other IPython frontends, but this package does not
-promise frontend-specific Tab behavior outside the terminal.
-
-## Quick Example: Add a `for` Template
-
-Add a template for the current IPython session:
-
-```python
-%postfix_template add for "for item in {expr}:\n{indent}    "
-```
-
-Use it:
-
-```python
-items.for<Tab>
-```
-
-It expands to:
-
-```python
-for item in items:
-    
-```
-
-Runtime templates only affect the current IPython session. Put templates in
-`ipython_config.py` if you want them to persist.
-
-## Runtime Magic
-
-List effective templates:
-
-```python
-%postfix_template list
-```
-
-Add or override a template for the current session:
-
-```python
-%postfix_template add debug "print({expr}=)"
-%postfix_template add forin "for item in {expr}:\n{indent}    "
-```
-
-Disable a template for the current session:
-
-```python
-%postfix_template remove tuple
-```
-
-Reset one runtime change:
-
-```python
-%postfix_template reset forin
-```
-
-Reset all runtime changes:
-
-```python
-%postfix_template reset --all
-```
-
-## Persistent Config
-
-Add persistent templates in `ipython_config.py`:
-
-```python
-c.PostfixCompletionConfig.templates = {
-    "debug": "print({expr}=)",
-    "forin": "for item in {expr}:\n{indent}    ",
-}
-
-c.PostfixCompletionConfig.disabled_templates = ["tuple"]
-```
-
-Smart Tab jump is enabled by default. Disable it while keeping postfix
-completion with:
-
-```python
-c.PostfixCompletionConfig.smart_tab_jump = False
-```
-
-Template names must match `[A-Za-z_][A-Za-z0-9_]*`.
-
-Templates must include `{expr}` and may also use `{indent}`. No other template
-fields are allowed.
-
-## `.var` Placeholder
-
-The built-in `.var` template creates an assignment and selects `key` as an
-editable placeholder:
-
-```text
-"hello".var<Tab>  ->  key = "hello"
-                       ^^^ selected
-```
-
-While `key` remains selected:
-
-- Tab accepts `key` and moves cursor to the end of the assignment.
-- Enter behaves like Tab for this selection only; press Enter again to submit.
-- Any other typed text replaces `key` with a custom variable name.
-
-In 0.1.x, `.var` produced `expr = ` with the cursor after the assignment
-target. Version 0.2.0 changes this to `key = expr` with an editable
-placeholder; use a custom template if you need the old behavior.
-
-## Smart Tab Jump
-
-When cursor is immediately before a valid Python closing token, Tab moves over
-it without changing source text. Repeated Tab presses exit nested constructs:
-
-```text
-"hello|"                 -> "hello"|
-print("hello|")          -> print("hello"|) -> print("hello")|
-print(f"{name|}")        -> print(f"{name}|") -> print(f"{name}"|) -> print(f"{name}")|
-items[index|]            -> items[index]|
-list[dict[str, int|]]    -> list[dict[str, int]|] -> list[dict[str, int]]|
-{"name": value|}         -> {"name": value}|
-```
-
-`|` marks cursor and is not typed. Supported closers are single and triple
-quotes plus `)`, `]`, and `}`. Detection follows Python tokens, including
-multiline input, string prefixes, and f-string expressions. Tab still accepts
-the `.var` name selection or an exact postfix template first; otherwise it
-falls back to IPython completion or indentation. Ambiguous `< >`, colon, and
-comma are intentionally excluded.
-
-## Built-in Templates
-
-Default templates:
-
-| Name | Expansion |
-| --- | --- |
-| `print` | `print({expr})` |
-| `len` | `len({expr})` |
-| `not` | `not {expr}` |
-| `par` | `({expr})` |
-| `var` | `key = {expr}`; selects `key`; Tab or Enter accepts it |
-| `await` | `await {expr}` |
-| `return` | `return {expr}` |
-| `if` | `if {expr}:\n{indent}    ` |
-| `while` | `while {expr}:\n{indent}    ` |
-| `raise` | `raise {expr}` |
-| `yield` | `yield {expr}` |
-| `str` | `str({expr})` |
-| `list` | `list({expr})` |
-| `set` | `set({expr})` |
-| `dict` | `dict({expr})` |
-| `tuple` | `tuple({expr})` |
-
-Use `%postfix_template list` in IPython to see the exact effective set, including
-custom and disabled templates.
-
-## Local Validation
-
-Run tests:
-
-```bash
-uv run --extra test pytest -q
-uv run --extra dev ruff check .
-uv run --extra dev ruff format --check .
-uv run --isolated --no-project --with "ipython>=9,<10" --with "traitlets>=5.13" --with "pip-audit>=2.7" pip-audit --strict --local
-```
-
-Build and check release artifacts:
-
-```bash
-uv run --extra dev python -m build
-uv run --extra dev python -m twine check dist/*
-```
-
-Validate the wheel in a clean local virtual environment:
-
-```bash
-uv venv .venv-check
-uv pip install --python .venv-check/bin/python dist/*.whl
-.venv-check/bin/ipython
-```
-
-Then inside IPython:
-
-```python
-%load_ext ipython_postfix_completion
-%postfix_template add for "for item in {expr}:\n{indent}    "
-%postfix_template list
-```
-
-## Publish
-
-Publishing uses GitHub Actions and PyPI Trusted Publishing. Configure the
-existing PyPI project once under **Manage > Publishing > Add a new publisher**:
-
-| Setting | Value |
-| --- | --- |
-| Owner | `fishandsheep` |
-| Repository | `ipython-postfix-completion` |
-| Workflow | `publish.yml` |
-| Environment | `pypi` |
-
-For each release, update `project.version` in `pyproject.toml`, commit and push
-the change, then create a matching `v` tag. For this release:
-
-```bash
-git tag v0.2.0
-git push origin v0.2.0
-```
-
-The workflow verifies the tag against `project.version`, runs tests, builds and
-checks both distributions, then publishes them to PyPI using a short-lived OIDC
-credential. PyPI versions are immutable: never reuse a published version or tag;
-fixes require the next version.
-
-See [CHANGELOG.md](CHANGELOG.md) for release notes and migration guidance.

ipython_postfix_completion-0.2.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-ipython_postfix_completion/__init__.py,sha256=K9fMAo6kLY3JeUe9SfEp83Om-KsYTcDrC6Fyhhy3VUQ,30361
-ipython_postfix_completion-0.2.0.dist-info/licenses/LICENSE,sha256=omLR-7QW1K3l6AG7ih1N5L8Z58UY-ROrQL82ANN9PnM,1547
-ipython_postfix_completion-0.2.0.dist-info/METADATA,sha256=CwKUKdYbwrxPvVFLnTEJ3n-_sD_E4CRvBoiM1pHb_ds,7767
-ipython_postfix_completion-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-ipython_postfix_completion-0.2.0.dist-info/top_level.txt,sha256=W2sJCvsBheoCB2nbzJeD7-p5PR6lVDNicVLxNxmeraY,27
-ipython_postfix_completion-0.2.0.dist-info/RECORD,,