indentoken 1.0.0__tar.gz

indentoken-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rockmizu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

indentoken-1.0.0/PKG-INFO

@@ -0,0 +1,395 @@
+Metadata-Version: 2.4
+Name: indentoken
+Version: 1.0.0
+Summary: An indentation token which helps you manage text indentations.
+Keywords: indentation,indent,dedent,text formatting,output formatting
+Author: Rockmizu
+Author-email: Rockmizu <Rockmizu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# indentoken
+
+A magical little token to help you manage string indentation.
+
+## Table of Contents
+
+* [Motivation](#motivation)
+* [Features](#features)
+* [Requirements](#requirements)
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Basic Indentation and Dedentation](#basic-indentation-and-dedentation)
+  * [Using Context Manager for Indentation](#using-context-manager-for-indentation)
+  * [Multi-line Text Indentation](#multi-line-text-indentation)
+  * [Initialization](#initialization)
+  * [Padding](#padding)
+  * [Indentation Addition](#indentation-addition)
+  * [Multi-parameter Print](#multi-parameter-print)
+* [License](#license)
+
+## Motivation
+
+Have you ever wanted your program output to look like this?
+
+```text
+food
+  fruit
+    apple
+    banana
+  --------
+  meat
+    pork
+    beef
+  --------
+```
+
+Normally, you need to manually track the current indentation depth:
+
+```python
+foods = {'fruit': ['apple', 'banana'], 'meat': ['pork', 'beef']}
+
+print('food')
+for category, items in foods.items():
+    print(f'  {category}')
+    #       ^^ manually track the indentations
+    for item in items:
+        print(f'    {item}')
+        #       ^^^^ manually track the indentations
+    print(f'  --------')
+    #       ^^ manually track the indentations
+```
+
+This method is not only very prone to errors, but it becomes even harder
+to track the preceding whitespace when breaking down sub-loops
+into functions.
+
+How great would it be if there was a tool to help you track indentation.
+
+This is exactly where indentoken can help!
+
+Now you can write:
+
+```python
+from indentoken import Indentation
+
+ind = Indentation()
+
+foods = {'fruit': ['apple', 'banana'], 'meat': ['pork', 'beef']}
+
+print('food')
+
+with ind.indented_context():
+    for category, items in foods.items():
+        print(f'{ind}{category}')
+
+        with ind.indented_context():
+            for item in items:
+                print(f'{ind}{item}')
+
+        print(f'{ind}--------')
+```
+
+Notice how the manual whitespace disappears, replaced by an `ind` object
+that tracks the indentation depth and converts it to a string for you.
+
+You can also pass it into a function to continuously track
+the current indentation:
+
+```python
+from collections.abc import Iterable
+
+from indentoken import Indentation
+
+
+def main() -> None:
+    ind = Indentation()
+
+    foods = {'fruit': ['apple', 'banana'], 'meat': ['pork', 'beef']}
+
+    print('food')
+
+    with ind.indented_context():
+        for category, items in foods.items():
+            print(f'{ind}{category}')
+
+            with ind.indented_context():
+                show_food_items(items, ind=ind)
+
+            print(f'{ind}--------')
+
+
+def show_food_items(items: Iterable[str], *, ind: Indentation) -> None:
+    for item in items:
+        print(f'{ind}{item}')
+
+
+if __name__ == '__main__':
+    main()
+```
+
+There are more features, please see [Usage](#usage).
+
+## Features
+
+1. Multifunctional and convenient indentation tracking token.
+2. Complete type annotations, supporting modern type checking
+   and type-safe development.
+3. Zero package dependencies, so you don't have to worry about conflicts with
+   other packages in your virtual environment during installation.
+4. Pure Python package, no C extensions, usable anywhere Python runs.
+
+## Requirements
+
+This package supports Python 3.10 and above.
+
+## Installation
+
+You can install this package using pip:
+
+```bash
+pip install indentoken
+```
+
+## Usage
+
+The following examples assume you have imported:
+
+```python
+from indentoken import Indentation
+```
+
+### Basic Indentation and Dedentation
+
+```python
+ind = Indentation()
+
+# Have no indentation at all initally.
+print(f'{ind}Line 1')  # |Line 1
+
+# Indent by 1 level.
+ind.indent()
+print(f'{ind}Line 2')  # |  Line 2
+
+# Indent by 3 levels, plus the previous 1 level.
+# Now the indentation is 4 levels deep.
+ind.indent(3)
+print(f'{ind}Line 3')  # |        Line 3
+
+# Dedent by 1 level.
+# Now the indentation is 3 levels deep.
+ind.dedent()
+print(f'{ind}Line 4')  # |      Line 4
+
+# Dedent by 99 levels.
+# Note that the indentation level is always non-negative.
+# The final indentation level will be clamped at 0.
+ind.dedent(99)
+assert ind.level == 0
+print(f'{ind}Line 5')  # |Line 5
+
+# Directly set the current indentation level to 3.
+ind.level = 3
+print(f'{ind}Line 6')  # |      Line 6
+```
+
+### Using Context Manager for Indentation
+
+If you want to increase indentation within a certain block, I recommend
+using `with` combined with `indented_context()`.
+This ensures that the indentation automatically reverts to
+the correct depth even if an exception is raised.
+
+```python
+ind = Indentation()
+
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+with ind.indented_context():
+    print(f'{ind}This line is indented.')  # |  This line is indented.
+    print(f'{ind}This line is indented.')  # |  This line is indented.
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+with ind.indented_context(2):
+    print(f'{ind}This line is indented by 2 levels.')  # |    This line is indented by 2 levels.
+    print(f'{ind}This line is indented by 2 levels.')  # |    This line is indented by 2 levels.
+    with ind.indented_context(1):  # nested indented context will stack
+        print(f'{ind}This line is indented by 3 levels.')  # |      This line is indented by 3 levels.
+        print(f'{ind}This line is indented by 3 levels.')  # |      This line is indented by 3 levels.
+    print(f'{ind}This line is indented by 2 levels.')  # |    This line is indented by 2 levels.
+```
+
+The output you will get is like this:
+
+```text
+This line is NOT indented.
+This line is NOT indented.
+  This line is indented.
+  This line is indented.
+This line is NOT indented.
+This line is NOT indented.
+    This line is indented by 2 levels.
+    This line is indented by 2 levels.
+      This line is indented by 3 levels.
+      This line is indented by 3 levels.
+    This line is indented by 2 levels.
+```
+
+### Multi-line Text Indentation
+
+For multi-line text, you can directly wrap it in `ind`
+or use the `apply_to()` method:
+
+```python
+ind = Indentation(level=1)
+
+print('No indentation.')
+print(ind('This is a multi-line text.\nAll lines will be indented.\nThe third line.'))
+# ind('something') is equivalent to ind.apply_to('something')
+```
+
+It will output:
+
+```text
+No indentation.
+  This is a multi-line text.
+  All lines will be indented.
+  The third line.
+```
+
+### Initialization
+
+During initialization, you can specify the indentation characters,
+initial indentation depth, and padding (which will be mentioned later).
+
+```python
+ind = Indentation(word='-->', level=2)
+print(f'{ind}Line 1')  # |-->-->Line 1
+ind.indent()
+print(f'{ind}Line 2')  # |-->-->-->Line 2
+```
+
+### Padding
+
+If you want the starting point of the indentation not to begin
+from the far left, you can specify padding:
+
+```python
+# Use "+++++" as padding for visualization. You can use whitespaces.
+ind = Indentation(word='-->', padding='+++++')
+print(f'{ind}Line 1')  # |+++++Line 1
+ind.indent()
+print(f'{ind}Line 2')  # |+++++-->Line 2
+ind.indent()
+print(f'{ind}Line 3')  # |+++++-->-->Line 3
+```
+
+Padding does not change with indentation depth and it always exists,
+even if the indentation depth is zero.
+
+You can also specify the `Indentation` object as padding,
+which gives you dynamic padding effects:
+
+```python
+pad = Indentation(word='++', level=2)
+ind = Indentation(word='-->', padding=pad)
+print(f'{ind}Line 1')  # |++++Line 1
+ind.indent()
+print(f'{ind}Line 2')  # |++++-->Line 2
+ind.indent()
+print(f'{ind}Line 3')  # |++++-->-->Line 3
+pad.dedent()  # Note that the `pad` object is changing, not `ind`.
+print(f'{ind}Line 4')  # |++-->-->Line 4
+
+# Convert the padding to `str` on init if you want a fixed padding.
+pad = Indentation(word='++', level=2)
+ind = Indentation(word='-->', level=1, padding=str(pad))
+print(f'{ind}Line 5')  # |++++-->Line 5
+pad.dedent()  # Note that the `pad` object is changing, not `ind`.
+print(f'{ind}Line 6')  # |++++-->Line 6
+```
+
+### Indentation Addition
+
+If you temporarily need to deepen the indentation
+without using the heavy `with` statement, you can directly add
+the desired indentation depth to the indentation object.
+
+Additionally, `Indentation` addition only changes
+the indentation depth and does not change the padding.
+
+```python
+ind = Indentation(word='-->', level=1)
+print(f'{ind}one level indented')  # |-->one level indented
+print(f'{ind}one level indented')  # |-->one level indented
+print(f'{ind + 1}one level deeper, two levels indented')  # |-->-->one level deeper, two levels indented
+print(f'{ind + 2}two levels deeper, three levels indented')  # |-->-->-->two levels deeper, three levels indented
+print(f'{ind}one level indented')  # |-->one level indented
+print(f'{ind}one level indented')  # |-->one level indented
+
+ind = Indentation(word='-->', level=1, padding='++')
+print(f'{ind}one level indented')  # |++-->one level indented
+print(f'{ind + 1}one level deeper, two levels indented')  # |++-->-->one level deeper, two levels indented
+```
+
+Indentation addition is commutative:
+
+```python
+ind = Indentation(word='-->', level=2)
+assert ind + 1 == 1 + ind
+```
+
+### Multi-parameter Print
+
+If you want the following usage of `print` to also receive indentation,
+you can wrap the `print` function with the `Indentation` object.
+
+```python
+print('Alice', 'Bob', sep=' & ')  # |Alice & Bob
+
+ind = Indentation(word='-->', level=1)
+ind(print)('Alice', 'Bob', sep=' & ')  # |-->Alice & Bob
+# Note that the parentheses wrap the `print`, not the entire statement.
+```
+
+Note that if you save `ind(print)` for later use, it will bind
+this `Indentation` object.
+If you do not want the `print` to change with the `Indentation` object,
+you can use the `fixed()` method.
+
+```python
+ind = Indentation(word='-->', level=1)
+
+print_indented = ind(print)
+
+print_indented('Alice')  # |-->Alice
+
+ind.indent()
+print_indented('Bob')  # |-->-->Bob
+
+# ===========================================
+ind = Indentation(word='-->', level=1)
+
+# Use ind.fixed() to fixed the indentation.
+print_indented_fixed = ind.fixed(print)
+
+print_indented_fixed('Alice')  # |-->Alice
+
+ind.indent()
+print_indented_fixed('Bob')  # |-->Bob
+```
+
+## License
+
+This software is distributed under the MIT License.
+Please see the [LICENSE](LICENSE) file for details.

indentoken-1.0.0/README.md

@@ -0,0 +1,375 @@
+# indentoken
+
+A magical little token to help you manage string indentation.
+
+## Table of Contents
+
+* [Motivation](#motivation)
+* [Features](#features)
+* [Requirements](#requirements)
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Basic Indentation and Dedentation](#basic-indentation-and-dedentation)
+  * [Using Context Manager for Indentation](#using-context-manager-for-indentation)
+  * [Multi-line Text Indentation](#multi-line-text-indentation)
+  * [Initialization](#initialization)
+  * [Padding](#padding)
+  * [Indentation Addition](#indentation-addition)
+  * [Multi-parameter Print](#multi-parameter-print)
+* [License](#license)
+
+## Motivation
+
+Have you ever wanted your program output to look like this?
+
+```text
+food
+  fruit
+    apple
+    banana
+  --------
+  meat
+    pork
+    beef
+  --------
+```
+
+Normally, you need to manually track the current indentation depth:
+
+```python
+foods = {'fruit': ['apple', 'banana'], 'meat': ['pork', 'beef']}
+
+print('food')
+for category, items in foods.items():
+    print(f'  {category}')
+    #       ^^ manually track the indentations
+    for item in items:
+        print(f'    {item}')
+        #       ^^^^ manually track the indentations
+    print(f'  --------')
+    #       ^^ manually track the indentations
+```
+
+This method is not only very prone to errors, but it becomes even harder
+to track the preceding whitespace when breaking down sub-loops
+into functions.
+
+How great would it be if there was a tool to help you track indentation.
+
+This is exactly where indentoken can help!
+
+Now you can write:
+
+```python
+from indentoken import Indentation
+
+ind = Indentation()
+
+foods = {'fruit': ['apple', 'banana'], 'meat': ['pork', 'beef']}
+
+print('food')
+
+with ind.indented_context():
+    for category, items in foods.items():
+        print(f'{ind}{category}')
+
+        with ind.indented_context():
+            for item in items:
+                print(f'{ind}{item}')
+
+        print(f'{ind}--------')
+```
+
+Notice how the manual whitespace disappears, replaced by an `ind` object
+that tracks the indentation depth and converts it to a string for you.
+
+You can also pass it into a function to continuously track
+the current indentation:
+
+```python
+from collections.abc import Iterable
+
+from indentoken import Indentation
+
+
+def main() -> None:
+    ind = Indentation()
+
+    foods = {'fruit': ['apple', 'banana'], 'meat': ['pork', 'beef']}
+
+    print('food')
+
+    with ind.indented_context():
+        for category, items in foods.items():
+            print(f'{ind}{category}')
+
+            with ind.indented_context():
+                show_food_items(items, ind=ind)
+
+            print(f'{ind}--------')
+
+
+def show_food_items(items: Iterable[str], *, ind: Indentation) -> None:
+    for item in items:
+        print(f'{ind}{item}')
+
+
+if __name__ == '__main__':
+    main()
+```
+
+There are more features, please see [Usage](#usage).
+
+## Features
+
+1. Multifunctional and convenient indentation tracking token.
+2. Complete type annotations, supporting modern type checking
+   and type-safe development.
+3. Zero package dependencies, so you don't have to worry about conflicts with
+   other packages in your virtual environment during installation.
+4. Pure Python package, no C extensions, usable anywhere Python runs.
+
+## Requirements
+
+This package supports Python 3.10 and above.
+
+## Installation
+
+You can install this package using pip:
+
+```bash
+pip install indentoken
+```
+
+## Usage
+
+The following examples assume you have imported:
+
+```python
+from indentoken import Indentation
+```
+
+### Basic Indentation and Dedentation
+
+```python
+ind = Indentation()
+
+# Have no indentation at all initally.
+print(f'{ind}Line 1')  # |Line 1
+
+# Indent by 1 level.
+ind.indent()
+print(f'{ind}Line 2')  # |  Line 2
+
+# Indent by 3 levels, plus the previous 1 level.
+# Now the indentation is 4 levels deep.
+ind.indent(3)
+print(f'{ind}Line 3')  # |        Line 3
+
+# Dedent by 1 level.
+# Now the indentation is 3 levels deep.
+ind.dedent()
+print(f'{ind}Line 4')  # |      Line 4
+
+# Dedent by 99 levels.
+# Note that the indentation level is always non-negative.
+# The final indentation level will be clamped at 0.
+ind.dedent(99)
+assert ind.level == 0
+print(f'{ind}Line 5')  # |Line 5
+
+# Directly set the current indentation level to 3.
+ind.level = 3
+print(f'{ind}Line 6')  # |      Line 6
+```
+
+### Using Context Manager for Indentation
+
+If you want to increase indentation within a certain block, I recommend
+using `with` combined with `indented_context()`.
+This ensures that the indentation automatically reverts to
+the correct depth even if an exception is raised.
+
+```python
+ind = Indentation()
+
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+with ind.indented_context():
+    print(f'{ind}This line is indented.')  # |  This line is indented.
+    print(f'{ind}This line is indented.')  # |  This line is indented.
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+print(f'{ind}This line is NOT indented.')  # |This line is NOT indented.
+with ind.indented_context(2):
+    print(f'{ind}This line is indented by 2 levels.')  # |    This line is indented by 2 levels.
+    print(f'{ind}This line is indented by 2 levels.')  # |    This line is indented by 2 levels.
+    with ind.indented_context(1):  # nested indented context will stack
+        print(f'{ind}This line is indented by 3 levels.')  # |      This line is indented by 3 levels.
+        print(f'{ind}This line is indented by 3 levels.')  # |      This line is indented by 3 levels.
+    print(f'{ind}This line is indented by 2 levels.')  # |    This line is indented by 2 levels.
+```
+
+The output you will get is like this:
+
+```text
+This line is NOT indented.
+This line is NOT indented.
+  This line is indented.
+  This line is indented.
+This line is NOT indented.
+This line is NOT indented.
+    This line is indented by 2 levels.
+    This line is indented by 2 levels.
+      This line is indented by 3 levels.
+      This line is indented by 3 levels.
+    This line is indented by 2 levels.
+```
+
+### Multi-line Text Indentation
+
+For multi-line text, you can directly wrap it in `ind`
+or use the `apply_to()` method:
+
+```python
+ind = Indentation(level=1)
+
+print('No indentation.')
+print(ind('This is a multi-line text.\nAll lines will be indented.\nThe third line.'))
+# ind('something') is equivalent to ind.apply_to('something')
+```
+
+It will output:
+
+```text
+No indentation.
+  This is a multi-line text.
+  All lines will be indented.
+  The third line.
+```
+
+### Initialization
+
+During initialization, you can specify the indentation characters,
+initial indentation depth, and padding (which will be mentioned later).
+
+```python
+ind = Indentation(word='-->', level=2)
+print(f'{ind}Line 1')  # |-->-->Line 1
+ind.indent()
+print(f'{ind}Line 2')  # |-->-->-->Line 2
+```
+
+### Padding
+
+If you want the starting point of the indentation not to begin
+from the far left, you can specify padding:
+
+```python
+# Use "+++++" as padding for visualization. You can use whitespaces.
+ind = Indentation(word='-->', padding='+++++')
+print(f'{ind}Line 1')  # |+++++Line 1
+ind.indent()
+print(f'{ind}Line 2')  # |+++++-->Line 2
+ind.indent()
+print(f'{ind}Line 3')  # |+++++-->-->Line 3
+```
+
+Padding does not change with indentation depth and it always exists,
+even if the indentation depth is zero.
+
+You can also specify the `Indentation` object as padding,
+which gives you dynamic padding effects:
+
+```python
+pad = Indentation(word='++', level=2)
+ind = Indentation(word='-->', padding=pad)
+print(f'{ind}Line 1')  # |++++Line 1
+ind.indent()
+print(f'{ind}Line 2')  # |++++-->Line 2
+ind.indent()
+print(f'{ind}Line 3')  # |++++-->-->Line 3
+pad.dedent()  # Note that the `pad` object is changing, not `ind`.
+print(f'{ind}Line 4')  # |++-->-->Line 4
+
+# Convert the padding to `str` on init if you want a fixed padding.
+pad = Indentation(word='++', level=2)
+ind = Indentation(word='-->', level=1, padding=str(pad))
+print(f'{ind}Line 5')  # |++++-->Line 5
+pad.dedent()  # Note that the `pad` object is changing, not `ind`.
+print(f'{ind}Line 6')  # |++++-->Line 6
+```
+
+### Indentation Addition
+
+If you temporarily need to deepen the indentation
+without using the heavy `with` statement, you can directly add
+the desired indentation depth to the indentation object.
+
+Additionally, `Indentation` addition only changes
+the indentation depth and does not change the padding.
+
+```python
+ind = Indentation(word='-->', level=1)
+print(f'{ind}one level indented')  # |-->one level indented
+print(f'{ind}one level indented')  # |-->one level indented
+print(f'{ind + 1}one level deeper, two levels indented')  # |-->-->one level deeper, two levels indented
+print(f'{ind + 2}two levels deeper, three levels indented')  # |-->-->-->two levels deeper, three levels indented
+print(f'{ind}one level indented')  # |-->one level indented
+print(f'{ind}one level indented')  # |-->one level indented
+
+ind = Indentation(word='-->', level=1, padding='++')
+print(f'{ind}one level indented')  # |++-->one level indented
+print(f'{ind + 1}one level deeper, two levels indented')  # |++-->-->one level deeper, two levels indented
+```
+
+Indentation addition is commutative:
+
+```python
+ind = Indentation(word='-->', level=2)
+assert ind + 1 == 1 + ind
+```
+
+### Multi-parameter Print
+
+If you want the following usage of `print` to also receive indentation,
+you can wrap the `print` function with the `Indentation` object.
+
+```python
+print('Alice', 'Bob', sep=' & ')  # |Alice & Bob
+
+ind = Indentation(word='-->', level=1)
+ind(print)('Alice', 'Bob', sep=' & ')  # |-->Alice & Bob
+# Note that the parentheses wrap the `print`, not the entire statement.
+```
+
+Note that if you save `ind(print)` for later use, it will bind
+this `Indentation` object.
+If you do not want the `print` to change with the `Indentation` object,
+you can use the `fixed()` method.
+
+```python
+ind = Indentation(word='-->', level=1)
+
+print_indented = ind(print)
+
+print_indented('Alice')  # |-->Alice
+
+ind.indent()
+print_indented('Bob')  # |-->-->Bob
+
+# ===========================================
+ind = Indentation(word='-->', level=1)
+
+# Use ind.fixed() to fixed the indentation.
+print_indented_fixed = ind.fixed(print)
+
+print_indented_fixed('Alice')  # |-->Alice
+
+ind.indent()
+print_indented_fixed('Bob')  # |-->Bob
+```
+
+## License
+
+This software is distributed under the MIT License.
+Please see the [LICENSE](LICENSE) file for details.

indentoken-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "indentoken"
+version = "1.0.0"
+description = "An indentation token which helps you manage text indentations."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+    "indentation",
+    "indent",
+    "dedent",
+    "text formatting",
+    "output formatting",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: General",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Rockmizu"
+email = "Rockmizu@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.5",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+ignore = ["F541"]

indentoken-1.0.0/pyproject.toml.orig

@@ -0,0 +1,50 @@
+[project]
+name = "indentoken"
+version = "1.0.0"
+description = "An indentation token which helps you manage text indentations."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Rockmizu", email = "Rockmizu@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+    "indentation",
+    "indent",
+    "dedent",
+    "text formatting",
+    "output formatting",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: General",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.5",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+ignore = [
+    "F541",  # f-string without any placeholders
+]

indentoken-1.0.0/src/indentoken/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .indentation import Indentation
+
+__all__ = ['Indentation']

indentoken-1.0.0/src/indentoken/feature_flags.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from typing import Final
+
+# The method rely on CPython implementation detail to work and should
+# only been re-implemented when PEP 533
+# Deterministic cleanup for iterators becomes available.
+INDENTOKEN_ENABLE_IT_METHOD: Final = False

indentoken-1.0.0/src/indentoken/indentation.py

@@ -0,0 +1,360 @@
+from __future__ import annotations
+
+import contextlib
+import functools
+import textwrap
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from io import StringIO
+from typing import Any, Final, ParamSpec, TypeVar, overload
+
+from .feature_flags import INDENTOKEN_ENABLE_IT_METHOD
+
+__all__ = ['Indentation']
+
+
+T = TypeVar('T')
+
+P = ParamSpec('P')
+
+# A sentinel object
+_MISSING: Final = object()
+
+
+def _wrap_print_with_post_process(
+    print_fn: Callable[P, Any],
+    post_process: Callable[[str], str],
+) -> Callable[P, None]:
+    @functools.wraps(print_fn)
+    def print_wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+        file = kwargs.pop('file', _MISSING)
+        flush = kwargs.pop('flush', _MISSING)
+        buffer = StringIO()
+        print_fn(*args, **kwargs, file=buffer, flush=False)  # type: ignore[arg-type]
+
+        text = buffer.getvalue()
+        text = post_process(text)
+
+        output_kwargs: dict[str, Any] = {}
+        if file is not _MISSING:
+            output_kwargs['file'] = file
+        if flush is not _MISSING:
+            output_kwargs['flush'] = flush
+
+        print_fn(text, end='', **output_kwargs)  # type: ignore[arg-type]
+
+    return print_wrapper
+
+
+@dataclass(slots=True, init=False, eq=False)
+class Indentation:
+    """
+    A magic token that can be used as an indentation string.
+    """
+
+    word: str = '  '
+    _level: int = field(init=False)
+    padding: str | Indentation = field(default='', kw_only=True)
+
+    def __init__(
+        self,
+        word: str = '  ',
+        level: int = 0,
+        *,
+        padding: str | Indentation = '',
+    ) -> None:
+        """
+        Initialize the Indentation object.
+
+        Args:
+            word: The string used for indentation (e.g., '  ').
+            level: The initial indentation level. Must be non-negative.
+            padding: Optional padding object or string.
+        """
+        if level < 0:
+            raise ValueError('`level` must be non-negative')
+        self.word = word
+        self.level = level
+        self.padding = padding
+
+    @property
+    def level(self) -> int:
+        """
+        Get the current indentation level.
+
+        Returns:
+            The current indentation level.
+        """
+        return self._level
+
+    @level.setter
+    def level(self, level: int, /) -> None:
+        """
+        Set the current indentation level.
+
+        Args:
+            level: The new indentation level.
+
+        Raises:
+            ValueError: If the provided `level` is negative.
+        """
+        if level < 0:
+            raise ValueError('`level` must be non-negative')
+        self._level = level
+
+    @property
+    def padding_str(self) -> str:
+        """
+        Get the padding string representation.
+
+        Returns:
+            The string representation of the padding.
+        """
+        return str(self.padding)
+
+    def copy(self) -> Indentation:
+        """
+        Create a copy of the current Indentation object.
+
+        Returns:
+            A new Indentation instance with the same properties.
+        """
+        return Indentation(
+            word=self.word,
+            level=self._level,
+            padding=self.padding,
+        )
+
+    def indent(self, delta: int = 1, /) -> None:
+        """
+        Increase the indentation level by `delta`.
+
+        * Positive values increase the indentation level.
+        * Negative values decrease the indentation level.
+        * The level is clamped at zero.
+
+        Args:
+            delta: The amount to increase the level by. Defaults to 1.
+        """
+        self._level = max(0, self.level + delta)
+
+    def dedent(self, delta: int = 1, /) -> None:
+        """
+        Decrease the indentation level by `delta`.
+
+        * Positive values decrease the indentation level.
+        * Negative values increase the indentation level.
+        * The level is clamped at zero.
+
+        Args:
+            delta: The amount to decrease the level by. Defaults to 1.
+        """
+        self._level = max(0, self.level - delta)
+
+    @contextlib.contextmanager
+    def indented_context(self, level: int = 1, /):
+        """
+        Context manager to temporarily change the indentation level.
+
+        Args:
+            level: The amount to change the indentation level by. Defaults to 1.
+
+        Yields:
+            Indentation: The current Indentation instance within the context.
+        """
+        if level < -self._level:  # noqa: PLR1730
+            level = -self._level
+
+        self.indent(level)
+        try:
+            yield self
+        finally:
+            self.dedent(level)
+
+    def apply_to(self, text: str, /) -> str:
+        """
+        Apply the current indentation to a given string.
+
+        Args:
+            text: The string to be indented.
+
+        Returns:
+            The indented string.
+        """
+        return textwrap.indent(text, prefix=str(self))
+
+    def fixed(self, print_fn: Callable[P, Any], /) -> Callable[P, None]:
+        """
+        Create a print function wrapper that applies indentation.
+
+        Args:
+            print_fn: The original print function to wrap.
+
+        Returns:
+            A wrapped print function that applies indentation.
+        """
+        return _wrap_print_with_post_process(
+            print_fn,
+            functools.partial(textwrap.indent, prefix=str(self)),
+        )
+
+    if INDENTOKEN_ENABLE_IT_METHOD:
+
+        def it(self, iterable: Iterable[T], /, delta: int = 1) -> Iterable[T]:
+            """
+            Wrap an iterable to provide the effect of `indented_context()`
+            before the iteration completes.
+
+            This method is particularly useful when you want additional
+            indentation during a `for` loop without adding an extra layer of
+            indentation to the source code.
+
+            E.g. You can write
+
+            ```python
+            ind = Indentation()
+
+            for item in ind.it(items):
+                print(f'{ind}{item}')
+
+            print(f'{ind}no indentation after loop')
+            ```
+
+            instead of
+
+            ```python
+            ind = Indentation()
+
+            with ind.indented_context():
+                for item in items:
+                    print(f'{ind}{item}')
+
+            print(f'{ind}no indentation after loop')
+            ```
+
+            Args:
+                iterable: The iterable to yield from.
+                delta: The amount to change the indentation level by. Defaults to 1.
+
+            Yields:
+                Elements from the iterable, indented.
+            """
+            with self.indented_context(delta):
+                yield from iterable
+
+    @overload
+    def __call__(self, text: str, /) -> str: ...
+    @overload
+    def __call__(self, print_fn: Callable[P, Any], /) -> Callable[P, None]: ...
+    def __call__(self, text_or_print_fn: str | Callable[P, Any], /) -> str | Callable[P, None]:
+        """
+        Apply the current indentation to a given text or
+        wrap a print function to apply indentation to its output.
+
+        Args:
+            text_or_print_fn: The string to indent, or the print function to wrap.
+
+        Returns:
+            The indented string if `text_or_print_fn` is a string, or the wrapped print function if it is a callable.
+        """
+        if isinstance(text_or_print_fn, str):
+            return self.apply_to(text_or_print_fn)
+
+        return _wrap_print_with_post_process(
+            text_or_print_fn,
+            self.apply_to,
+        )
+
+    def __add__(self, amount: int, /) -> str:
+        """
+        Return a string, which is the stringified result
+        as if adding `delta` level to this object.
+
+        ```python
+        ind = Indentation('->', level=2)
+        s1 = ind + 3  # s1 = '->->->->->'
+        assert ind.level == 2  # won't affect the original object
+        ind.indent(2)
+        s2 = str(ind)  # s2 = '->->->->->'
+        assert s1 == s2
+        ```
+
+        This is useful when you suddenly need more indentation levels
+        but don't want to use a context manager.
+
+        E.g.:
+
+        ```python
+        ind = Indentation()
+
+        print(f'{ind}not indented')
+        with ind.indented_context():
+            print(f'{ind}one level indented')
+            print(f'{ind}one level indented')
+            print(f'{ind + 1}one level deeper; two level indented')
+            print(f'{ind}one level indented')
+            print(f'{ind}one level indented')
+
+        # will output:
+        # not indented
+        #   one level indented
+        #   one level indented
+        #     one level deeper; two level indented
+        #   one level indented
+        #   one level indented
+        ```
+
+        Args:
+            times: The number of times to append the indentation string.
+
+        Returns:
+            The extended indentation string.
+        """
+        return str(self) + self.word * amount
+
+    def __radd__(self, amount: int, /) -> str:
+        """
+        Return a string, which is the stringified result
+        as if adding `amount` level to this object.
+
+        This is useful when you suddenly need more indentation levels
+        but don't want to use a context manager.
+
+        E.g.:
+
+        ```python
+        ind = Indentation()
+
+        print(f'{ind}not indented')
+        with ind.indented_context():
+            print(f'{ind}one level indented')
+            print(f'{ind}one level indented')
+            print(f'{1 + ind}one level deeper; two level indented')
+            print(f'{ind}one level indented')
+            print(f'{ind}one level indented')
+
+        # will output:
+        # not indented
+        #   one level indented
+        #   one level indented
+        #     one level deeper; two level indented
+        #   one level indented
+        #   one level indented
+        ```
+
+        Args:
+            times: The number of times to append the indentation string.
+
+        Returns:
+            The extended indentation string.
+        """
+        return str(self) + self.word * amount
+
+    def __str__(self) -> str:
+        """
+        Return the string representation of the indentation.
+
+        Returns:
+            The string representing the indentation (padding + word * level).
+        """
+        return str(self.padding) + self.word * self._level