ipython-postfix-completion 0.2.0__tar.gz → 0.2.1__tar.gz

{ipython_postfix_completion-0.2.0 → ipython_postfix_completion-0.2.1}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project are documented here.
 
+## [0.2.1] - 2026-10-05
+
+### Added
+
+- Added built-in `.for`, `.fori`, `.ef`, `.type`, and `.range` templates.
+- Added editable, sequential Tab stops for loop and conditional templates,
+  with Shift+Tab navigation to previous stops.
+- Wrapped integer literals in `range(...)` for `.for` and `.fori` templates.
+
+### Changed
+
+- Updated the built-in `.if` template to include an editable `pass` body.
+- Simplified the README and moved detailed usage and maintenance notes to
+  `docs/REFERENCE.md`.
+
 ## [0.2.0] - 2026-08-09
 
 ### Added

{ipython_postfix_completion-0.2.0 → ipython_postfix_completion-0.2.1}/MANIFEST.in

@@ -2,3 +2,4 @@ include LICENSE
 include README.md
 include CHANGELOG.md
 recursive-include tests *.py
+recursive-include docs *.md

ipython_postfix_completion-0.2.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,80 @@
+# 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/docs/REFERENCE.md

@@ -0,0 +1,150 @@
+# Extended Reference
+
+This guide contains detailed template, configuration, Tab behavior, development,
+and release information. For installation and common usage, see the [README](../README.md).
+
+## Template Reference
+
+Templates take the expression to the left of the dot as `{expr}`. `{indent}` is
+the leading indentation of the input line. These are the built-in templates:
+
+| Name | Expansion |
+| --- | --- |
+| `print` | `print({expr})` |
+| `len` | `len({expr})` |
+| `not` | `not {expr}` |
+| `par` | `({expr})` |
+| `var` | `key = {expr}`; selects `key` |
+| `await` | `await {expr}` |
+| `return` | `return {expr}` |
+| `if` | `if {expr}:` with an indented `pass` |
+| `while` | `while {expr}:` with an indented blank body |
+| `for` | `for item in {expr}:` with an indented `pass` |
+| `fori` | `for i, value in enumerate({expr}):` with an indented `pass` |
+| `ef` | `if {expr}:`, `elif cond:`, and `else:` branches, each with `pass` |
+| `raise` | `raise {expr}` |
+| `yield` | `yield {expr}` |
+| `str` | `str({expr})` |
+| `list` | `list({expr})` |
+| `set` | `set({expr})` |
+| `dict` | `dict({expr})` |
+| `tuple` | `tuple({expr})` |
+| `type` | `type({expr})` |
+| `range` | `range({expr})` |
+
+Integer literals used with `.for` or `.fori` are wrapped in `range(...)`.
+Signed and underscored integer literals are recognized. A variable such as `n`
+is left unchanged because completion cannot know its runtime type. Thus
+`10.fori` uses `enumerate(range(10))`, while `items.fori` uses
+`enumerate(items)`.
+
+When a partial name matches multiple templates, the completion menu lists each
+match. In particular, `.f` can show both `for` and `fori`; Tab on the exact
+`.if` suffix expands `if`.
+
+## Placeholder and Tab Behavior
+
+For built-in `.var`, `.for`, `.if`, `.fori`, and `.ef` templates, Tab accepts
+the selected placeholder and advances to the next one. Shift+Tab selects the
+previous placeholder. Typing replaces the selected text. After the final stop,
+Tab accepts it and places the cursor after the expansion. Enter accepts the
+selected `.var` name; press Enter again to submit the input.
+
+The built-in placeholder behavior is enabled only when the corresponding
+template retains its built-in definition. Overriding a built-in template
+disables its special selection behavior.
+
+### Smart Tab Jump
+
+Smart Tab jump is enabled by default in terminal IPython. When the cursor is
+immediately before a valid Python closing token, Tab moves over it without
+changing source text. Repeated 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 the 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 processes an
+active placeholder and an exact postfix template first, then falls back to
+IPython completion, closer movement, or indentation. Ambiguous `< >`, colon,
+and comma are not treated as closers.
+
+Disable smart Tab jump while retaining postfix completion with:
+
+```python
+c.PostfixCompletionConfig.smart_tab_jump = False
+```
+
+## Runtime Template Commands
+
+Add or override a template for the current IPython session:
+
+```python
+%postfix_template add debug "print({expr}=)"
+%postfix_template add forin "for item in {expr}:\n{indent}    pass"
+```
+
+Disable, reset one, or reset all runtime changes:
+
+```python
+%postfix_template remove tuple
+%postfix_template reset forin
+%postfix_template reset --all
+```
+
+Runtime changes last only for the current session. Use
+`%postfix_template list` to see built-in, custom, and disabled entries.
+
+Persistent configuration belongs in
+`~/.ipython/profile_default/ipython_config.py` by default. Create the profile
+with `ipython profile create`; locate the active path with
+`ipython locate profile default`. `IPYTHONDIR` or `--ipython-dir` can change
+the IPython directory. See the [official IPython configuration guide](https://ipython.readthedocs.io/en/stable/development/config.html).
+
+Template names must match `[A-Za-z_][A-Za-z0-9_]*`. Templates must include
+`{expr}` and may also use `{indent}`. No other fields, conversions, or format
+specifiers are allowed.
+
+## Development
+
+Run tests and style checks:
+
+```bash
+uv run --extra test pytest -q
+uv run --extra dev ruff check .
+uv run --extra dev ruff format --check .
+```
+
+Run IPython against the current checkout without installing into system Python:
+
+```bash
+uv run --with ipython --with-editable . ipython
+```
+
+Then load `ipython_postfix_completion` in that IPython session.
+
+Build and validate release artifacts:
+
+```bash
+uv run --extra dev python -m build
+uv run --extra dev python -m twine check dist/*
+```
+
+## Publishing
+
+Releases use GitHub Actions and PyPI Trusted Publishing. Configure the PyPI
+publisher for the `fishandsheep/ipython-postfix-completion` repository, the
+`publish.yml` workflow, and the `pypi` environment. Update the version in
+`pyproject.toml`, push the change, then create and push the matching `v` tag.
+The workflow checks the tag against the project version, runs tests, builds and
+checks distributions, and publishes them. Published PyPI versions and release
+tags are immutable; use a new version for fixes.
+
+See [CHANGELOG.md](../CHANGELOG.md) for release history.

{ipython_postfix_completion-0.2.0 → ipython_postfix_completion-0.2.1}/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)