docstring-tailor 0.1.0__tar.gz

docstring_tailor-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Folders
+__pycache__/
+.vscode/
+.ruff_cache/
+.ipynb_checkpoints/
+artifacts/
+data/
+
+# Virtual environments
+venv/
+.venv/
+.env/
+
+# Python bytecode
+*.pyc
+*.pyo
+*.pyd
+
+# Test and coverage
+htmlcov/
+.coverage
+.coverage.*
+*.cover
+.cache
+.nox/
+
+# Packaging and build
+build/
+dist/
+*.egg-info/
+.eggs/
+*.manifest
+*.spec
+
+# Logs
+*.log
+*.out
+*.err
+
+# OS-specific files (macOS + Windows)
+.DS_Store
+.AppleDouble
+._*
+Thumbs.db
+Desktop.ini
+
+# Temporary and backup files
+*.tmp
+*.temp
+*.bak
+*.swp
+*.swo
+
+# Project-specific
+bitmaps/.~lock*
+bitmaps/.~lock.*#
+**/readme.todo

docstring_tailor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Auke Bruinsma
+
+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.

docstring_tailor-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: docstring-tailor
+Version: 0.1.0
+Summary: Automatic formatting of Python docstrings according to PEP 257
+Author-email: Auke Bruinsma <afbruinsma@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Auke Bruinsma
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: libcst>=1.8.6
+Requires-Dist: logging>=0.4.9.6
+Requires-Dist: typer>=0.26.4
+Description-Content-Type: text/markdown
+
+# Docstring Tailor 🪡
+
+Automatic formatting of Python docstrings according to PEP 257 and a predefined maximum number of chacacters per line.
+
+## Docstring conventions according to PEP 257
+
+See https://peps.python.org/pep-0257/ for the complete document.
+
+**What is a docstring?** A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the `__doc__` special attribute of that object.
+
+## Different types and forms of docstrings
+
+The PEP document makes distinctions between different types of docstrings. For some docstring properties, the convention depends on the kind of object it belongs to. For module docstrings, it can also further depend on the type of python file. Therefore, a distinction is made between these **types** of docstrings:
+
+**Four types of docstrings**:
+1. Module docstrings
+    - Module docstrings for scripts (stand-alone program)
+    - Module docstrings for `__init__.py` files
+    - Module docstrings for 'normal' modules.
+2. Class docstrings
+3. Method or function docstrings
+
+Besides the types, docstrings can occur in two different **forms**.
+
+**Two forms of docstrings**:
+1. One-line docstrings
+2. Multi-line docstrings
+
+### Conventions for one-line docstrings
+1. Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.
+2. The closing quotes are on the same line as the opening quotes. This looks better for one-liners.
+3. There’s no blank line either before or after the docstring, except when the the type of docstring is a class docstring. Then there should be a blank line after the docstring.
+4. The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.
+5. The one-line docstring should NOT be a “signature” reiterating the function/method parameters (which can be obtained by introspection).
+
+### Conventions for multi-line docstrings
+1. Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.
+2. The summary line may be on the same line as the opening quotes or on the next line.
+3. The entire docstring is indented the same as the quotes at its first line.
+4. Insert a blank line after all docstrings (one-line or multi-line) that document a class.
+5. Blank lines should be removed from the beginning and end of the docstring.
+
+#### Module docstrings
+
+5. The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object’s docstring.) 
+6. The docstring of a script (a stand-alone program) should be usable as its “usage” message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a “-h” option, for “help”)
+7. The docstring for a package (i.e., the docstring of the package’s `__init__.py` module) should also list the modules and subpackages exported by the package.
+
+#### Function or method docstrings
+
+8. The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.
+
+#### Class docstrings
+
+9. The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.
+10. If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences.
+
+## Formatting operations applied by this tool
+
+**How does this tool detect docstrings?**: All string literals that start with triple double quotes (""") are recognized as docstrings and will potentially be formatted.
+
+**One-line docstrings**
+- Regarding the 5 conventions mentioned above for one-line docstrings, only convention number 2 is enforced (The closing quotes are on the same line as the opening quotes).
+- It is the user's reponsibility to adhere to convention number 1, since the triple quotes are used by this tool to detect the docstring. The same goes for convention number 3, 4 and 5.
+
+- Besides the conventions mentioned above, the docstring is formatted according to a pre-defined maximum number of characters per line (**line length**). This means:
+    - If a docstring is spread out over multiple lines, but it could fit on one line, it will be converted to a one-line docstring.
+    - If a docstring exceeds the line length, it will be converted to a multi-line docstring.
+
+**Multi-line docstrings**
+- Regarding the conventions for multi-line docstrings mentioned above, number 2 is applied. This means if the summary line is on the next line, it will be enforced on the same line as the opening triple double quotes.
+- Convention number 5 is also enforced, blank lines at the start and end of the docstring are removed.
+- Most of the other conventions are about the content of the docstring, which are not checked by this tool.
+
+Next to that, the layout of the docstring is preserved. For now the focus is on the 'Google' type docstring format, which in its most basic form, looks like this.
+
+```
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    Args:
+        param1: The first parameter.
+        param2: The second parameter.
+
+    Returns:
+        The return value. True for success, False otherwise.
+    """
+```
+
+Or it can look like this:
+
+```
+def example_generator(n):
+    """Generators have a ``Yields`` section instead of a ``Returns`` section.
+
+    Args:
+        n (int): The upper limit of the range to generate, from 0 to `n` - 1.
+
+    Yields:
+        int: The next number in the range of 0 to `n` - 1.
+
+    Examples:
+        Examples should be written in doctest format, and should illustrate how
+        to use the function.
+
+        >>> print([i for i in example_generator(4)])
+        [0, 1, 2, 3]
+
+    """
+    for i in range(n):
+        yield i
+```
+
+Maintaining this structure, while enforcing a maximum characters per line, means the following rules have to be implented in the formatting logic.
+
+- If the user starts a new line, even though there is still space on the current line for the next word, it should be corrected and the word should be moved to the current line.
+- If the line is too long, the part that exceed the line limit should be moved to the next line.
+- If the user uses two '\n' values, it means this was a deliberate choice (for example, starting the 'Args' section) and this should be preserved.
+- Single '\n' characters in for example the 'Args' section should be preserved, as each parameter should start on a new line.
+- If the docstring contains an 'Example' or 'Examples' section, the indentation for the code part and the code itself (indicated with '>>>' and '...') should be untouched, as this code should be able to be interpreted.

docstring_tailor-0.1.0/README.md

@@ -0,0 +1,120 @@
+# Docstring Tailor 🪡
+
+Automatic formatting of Python docstrings according to PEP 257 and a predefined maximum number of chacacters per line.
+
+## Docstring conventions according to PEP 257
+
+See https://peps.python.org/pep-0257/ for the complete document.
+
+**What is a docstring?** A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the `__doc__` special attribute of that object.
+
+## Different types and forms of docstrings
+
+The PEP document makes distinctions between different types of docstrings. For some docstring properties, the convention depends on the kind of object it belongs to. For module docstrings, it can also further depend on the type of python file. Therefore, a distinction is made between these **types** of docstrings:
+
+**Four types of docstrings**:
+1. Module docstrings
+    - Module docstrings for scripts (stand-alone program)
+    - Module docstrings for `__init__.py` files
+    - Module docstrings for 'normal' modules.
+2. Class docstrings
+3. Method or function docstrings
+
+Besides the types, docstrings can occur in two different **forms**.
+
+**Two forms of docstrings**:
+1. One-line docstrings
+2. Multi-line docstrings
+
+### Conventions for one-line docstrings
+1. Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.
+2. The closing quotes are on the same line as the opening quotes. This looks better for one-liners.
+3. There’s no blank line either before or after the docstring, except when the the type of docstring is a class docstring. Then there should be a blank line after the docstring.
+4. The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.
+5. The one-line docstring should NOT be a “signature” reiterating the function/method parameters (which can be obtained by introspection).
+
+### Conventions for multi-line docstrings
+1. Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.
+2. The summary line may be on the same line as the opening quotes or on the next line.
+3. The entire docstring is indented the same as the quotes at its first line.
+4. Insert a blank line after all docstrings (one-line or multi-line) that document a class.
+5. Blank lines should be removed from the beginning and end of the docstring.
+
+#### Module docstrings
+
+5. The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object’s docstring.) 
+6. The docstring of a script (a stand-alone program) should be usable as its “usage” message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a “-h” option, for “help”)
+7. The docstring for a package (i.e., the docstring of the package’s `__init__.py` module) should also list the modules and subpackages exported by the package.
+
+#### Function or method docstrings
+
+8. The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.
+
+#### Class docstrings
+
+9. The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.
+10. If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences.
+
+## Formatting operations applied by this tool
+
+**How does this tool detect docstrings?**: All string literals that start with triple double quotes (""") are recognized as docstrings and will potentially be formatted.
+
+**One-line docstrings**
+- Regarding the 5 conventions mentioned above for one-line docstrings, only convention number 2 is enforced (The closing quotes are on the same line as the opening quotes).
+- It is the user's reponsibility to adhere to convention number 1, since the triple quotes are used by this tool to detect the docstring. The same goes for convention number 3, 4 and 5.
+
+- Besides the conventions mentioned above, the docstring is formatted according to a pre-defined maximum number of characters per line (**line length**). This means:
+    - If a docstring is spread out over multiple lines, but it could fit on one line, it will be converted to a one-line docstring.
+    - If a docstring exceeds the line length, it will be converted to a multi-line docstring.
+
+**Multi-line docstrings**
+- Regarding the conventions for multi-line docstrings mentioned above, number 2 is applied. This means if the summary line is on the next line, it will be enforced on the same line as the opening triple double quotes.
+- Convention number 5 is also enforced, blank lines at the start and end of the docstring are removed.
+- Most of the other conventions are about the content of the docstring, which are not checked by this tool.
+
+Next to that, the layout of the docstring is preserved. For now the focus is on the 'Google' type docstring format, which in its most basic form, looks like this.
+
+```
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    Args:
+        param1: The first parameter.
+        param2: The second parameter.
+
+    Returns:
+        The return value. True for success, False otherwise.
+    """
+```
+
+Or it can look like this:
+
+```
+def example_generator(n):
+    """Generators have a ``Yields`` section instead of a ``Returns`` section.
+
+    Args:
+        n (int): The upper limit of the range to generate, from 0 to `n` - 1.
+
+    Yields:
+        int: The next number in the range of 0 to `n` - 1.
+
+    Examples:
+        Examples should be written in doctest format, and should illustrate how
+        to use the function.
+
+        >>> print([i for i in example_generator(4)])
+        [0, 1, 2, 3]
+
+    """
+    for i in range(n):
+        yield i
+```
+
+Maintaining this structure, while enforcing a maximum characters per line, means the following rules have to be implented in the formatting logic.
+
+- If the user starts a new line, even though there is still space on the current line for the next word, it should be corrected and the word should be moved to the current line.
+- If the line is too long, the part that exceed the line limit should be moved to the next line.
+- If the user uses two '\n' values, it means this was a deliberate choice (for example, starting the 'Args' section) and this should be preserved.
+- Single '\n' characters in for example the 'Args' section should be preserved, as each parameter should start on a new line.
+- If the docstring contains an 'Example' or 'Examples' section, the indentation for the code part and the code itself (indicated with '>>>' and '...') should be untouched, as this code should be able to be interpreted.

docstring_tailor-0.1.0/makefile

@@ -0,0 +1,54 @@
+# Default project folder
+PROJECT_NAME = src/docstring_tailor
+
+# Format and lint code with Ruff
+ruff:
+	uv run ruff check $(PROJECT_NAME) --fix
+	uv run ruff format $(PROJECT_NAME)
+	@echo "🔧 Successfully executed ruff."
+
+# Static type-check code with ty
+ty:
+	uv run ty check
+	@echo "🔍 Successfully executed ty."
+
+# Run tests with Pytest
+# -vvvs: Very verbose output, shows print() statements and extra test details
+# --cov=$(PROJECT_NAME): Measure test coverage for the project
+# --cov-report=term-missing: Show which lines are missing coverage
+# --cov-branch: Track branch coverage, not just line coverage
+pytest:
+	uv run pytest tests -vvvs \
+		--cov=$(PROJECT_NAME) \
+		--cov-report=term-missing \
+		--cov-branch
+	@echo "🧪 Successfully executed pytest."
+
+# Remove caches and temporary files
+clean:
+	@find . -type d \( \
+		-name '__pycache__' -o \
+		-name '.ruff_cache' -o \
+		-name '.mypy_cache' -o \
+		-name '.pytest_cache' \
+	\) -exec rm -rf {} +
+	@rm -f .coverage .python-version
+	@rm -rf artifacts
+	@echo "🧹 Successfully cleaned project."
+
+
+# Commit and push everything to git
+git:
+	git add -A
+	git commit -m "Updated"
+	git push
+	@echo "📤 Successfully executed git."
+
+# Run full workflow: format, type-check, test, clean, commit
+all:
+	make ruff
+	make ty
+	make pytest
+	make clean
+	make git
+	@echo "⚡ Successfully executed all tasks."

docstring_tailor-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "docstring-tailor"
+version = "0.1.0"
+description = "Automatic formatting of Python docstrings according to PEP 257"
+authors = [{ name = "Auke Bruinsma", email = "afbruinsma@gmail.com" }]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "libcst>=1.8.6",
+    "logging>=0.4.9.6",
+    "typer>=0.26.4",
+]
+
+[dependency-groups]
+dev = [
+    "prek>=0.3.8",
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.11.6",
+    "ty>=0.0.29",
+]
+
+[tool.ruff.lint]
+select = [
+    "I",    # isort-style import sorting
+    "ANN",  # annotation rules
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docstring_tailor"]
+
+[project.scripts]
+docstring_tailor = "docstring_tailor.main:app"

docstring_tailor-0.1.0/src/docstring_tailor/__init__.py

@@ -0,0 +1 @@
+""""""

docstring_tailor-0.1.0/src/docstring_tailor/cli_config.py

@@ -0,0 +1,25 @@
+"""CLI configuration constants and allowed values for docstring_tailor."""
+
+from enum import Enum
+
+# Initial argument that specifies the file(s) and/or folder(s)
+DEFAULT_PATHS = [("src")]
+
+
+# Argument: '--style'
+class DocstringStyle(str, Enum):
+    """Supported docstring styles."""
+
+    google = "google"
+    numpy = "numpy"
+    sphinx = "sphinx"
+    epydoc = "epydoc"
+
+
+SUPPORTED_STYLES = {DocstringStyle.google}
+DEFAULT_STYLE = DocstringStyle.google
+
+# Argument: '--line-length'
+LINE_LENGTH_MIN = 30
+LINE_LENGTH_MAX = 300
+LINE_LENGTH_DEFAULT = 100

docstring_tailor-0.1.0/src/docstring_tailor/constants.py

@@ -0,0 +1,50 @@
+"""Module for storing project constants."""
+
+# Encoding for reading .py files.
+ENCODING: str = "utf-8"
+
+# Docstring delimiters.
+DOCSTRING_DELIMITER: str = '"""'
+DOCSTRING_DELIMITER_LENGTH: int = len(DOCSTRING_DELIMITER)
+
+# Google-style docstring section keywords.
+GOOGLE_PLAIN_SECTIONS = frozenset(
+    {"Note", "Notes", "References", "See Also", "Todo", "Warning", "Warnings"}
+)
+GOOGLE_ITEM_SECTIONS = frozenset(
+    {"Args", "Arguments", "Attributes", "Raises", "Returns", "Yields"}
+)
+GOOGLE_CODE_SECTIONS = frozenset({"Example", "Examples"})
+GOOGLE_SECTION_HEADERS = (
+    GOOGLE_PLAIN_SECTIONS | GOOGLE_ITEM_SECTIONS | GOOGLE_CODE_SECTIONS
+)
+
+# NumPy-style docstring section keywords.
+NUMPY_ITEM_SECTIONS = frozenset(
+    {
+        "Attributes",
+        "Methods",
+        "Other Parameters",
+        "Parameters",
+        "Raises",
+        "Receives",
+        "Returns",
+        "Yields",
+    }
+)
+NUMPY_PLAIN_SECTIONS = frozenset({"Examples", "Notes", "References", "See Also"})
+NUMPY_SECTION_HEADERS = NUMPY_ITEM_SECTIONS | NUMPY_PLAIN_SECTIONS
+
+# Sphinx/reST-style docstring directive markers.
+# Directive-based rather than section-based — no section headers in the Google/NumPy sense.
+SPHINX_ITEM_DIRECTIVES = frozenset({":param", ":raises", ":returns", ":rtype", ":type"})
+SPHINX_PLAIN_DIRECTIVES = frozenset(
+    {".. example::", ".. note::", ".. seealso::", ".. warning::"}
+)
+SPHINX_DIRECTIVES = SPHINX_ITEM_DIRECTIVES | SPHINX_PLAIN_DIRECTIVES
+
+# Epydoc-style docstring tag markers.
+# Tag-based rather than section-based — no section headers in the Google/NumPy sense.
+EPYDOC_ITEM_TAGS = frozenset({"@param", "@raise", "@return", "@rtype", "@type"})
+EPYDOC_PLAIN_TAGS = frozenset({"@note", "@warning"})
+EPYDOC_TAGS = EPYDOC_ITEM_TAGS | EPYDOC_PLAIN_TAGS