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

ipython_postfix_completion-0.2.1/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+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
+
+- Smart Tab navigation over Python string and bracket closing tokens.
+- Editable `key` placeholder for the built-in `.var` template.
+- Runtime configuration for enabling or disabling Smart Tab.
+- CI coverage for Python 3.11–3.14 and IPython 9.x.
+
+### Changed
+
+- `.var` now expands `expr.var` to `key = expr` and selects `key`.
+- Smart Tab navigation is enabled by default in terminal IPython.
+- IPython 10+ is not currently supported.
+
+### Migration from 0.1.x
+
+The `.var` expansion changed from `expr = ` to `key = expr`. Users who
+depend on the old cursor position or assignment shape should keep using a
+custom template until they migrate.
+
+## [0.1.1] - 2026-07-10
+
+- Added the `.var` and `.await` templates.
+
+## [0.1.0] - 2026-07-05
+
+- Initial release.

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

@@ -1,3 +1,5 @@
 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.