docstring-to-text 0.0.1__tar.gz → 1.0.0__tar.gz

docstring_to_text-1.0.0/.github/workflows/publish-release-to-pypi.yml

@@ -0,0 +1,262 @@
+# Prerequisites:
+#
+# - In GitHub repo - create the publishing environment (here, `pypi` / `testpypi`)
+#   https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments
+#
+# - Create a "Trusted Publisher" in the project settings on (test)PyPI
+#   https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+#   https://pypi.org/manage/project/docstring-to-text/settings/publishing/
+
+# Tutorials:
+# https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+# https://www.youtube.com/watch?v=NMQwzI9hprg
+# https://github.com/ArjanCodes/moneysnake/blob/main/.github/workflows/release.yaml
+
+name: Publish Python 🐍 distribution 📦 to PyPI
+
+# ======= TRIGGERS =======
+
+#on:
+#  push:
+#    tags:
+#      # Trigger on tags with '[v]<int>.<int>whatever' pattern: 'v1.0.0', 'v2.1.4', etc
+#      # https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet
+#      # https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onpushbranchestagsbranches-ignoretags-ignore
+#      - 'v[0-9]+.[0-9]**'
+#      - '[0-9]+.[0-9]**'
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - "src/docstring_to_text/__package_meta.py"
+
+# ======= ENV VARS =======
+
+env:
+  # The name on PyPI:
+  PACKAGE_NAME: 'docstring-to-text'
+  VERSION_MODULE: 'src.docstring_to_text.__package_meta'
+  VERSION_VARIABLE: 'VERSION'
+
+
+# ========= JOBS =========
+
+jobs:
+
+  detect-version:
+    # https://emojidb.org/query-emojis
+    name: Parse version 🔢 + add Tag 🏷️
+    if: ${{ github.repository_owner == 'Lex-DRL' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Needed for tag creation
+    outputs:
+      tag_name: ${{ steps.parse.outputs.tag_name }}
+      version_full: ${{ steps.parse.outputs.version_full }}
+      version_num: ${{ steps.parse.outputs.version_num }}
+      suffix: ${{ steps.parse.outputs.suffix }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch full history to avoid issues with tags and branches
+
+      - name: Extract version from package meta 📝
+        id: get_version_string
+        run: |
+          # VERSION=$(grep -oP 'VERSION\s*=\s*["'\'']\K[^"'\'']+' src/docstring_to_text/__package_meta.py)
+          VERSION=$(python -c "from ${{ env.VERSION_MODULE }} import ${{ env.VERSION_VARIABLE }}; print(${{ env.VERSION_VARIABLE }})")
+          echo "Version string: $VERSION"
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Parse Version 🧱
+        id: parse
+        # The main magic happens in regexps...
+        # - `grep -qP`: verify that the tag matches the given pattern
+        # - `sed -E 's/regex_pattern/replacement/optional_flags'`, with '\1' in replacement meaning first group
+        # The regexp itself:
+        # - '^v?([0-9]+\.[0-9]+\.[0-9]+)' - matches 'v1.2.3' / '1.2.3' from start of the string, 'v' stripped
+        #   - '^' - start of the input string.
+        #   - 'v?(...)' - optional 'v' prefix (might be missing), and what follows is captured as a group.
+        #   - '[0-9]+' - a sequence of 1 or more digits.
+        #   - '\.' - literal dot (just '.' matches any character).
+        # - '(-.+)?$' - suffix captured as a group:
+        #   - '-' - just a hyphen.
+        #   - '.+' - any non-empty string (at least one any character - including another hyphen, dot or digit).
+        #   - '(...)?$' - a group that might be present or not.
+        #   - '$' - the end of the input string.
+        run: |
+          VERSION_STR="${{ steps.get_version_string.outputs.version }}"
+          echo "Version string: $VERSION_STR"
+          if echo "$VERSION_STR" | grep -qP '^v?[0-9]+\.[0-9]+\.[0-9]+(-.+)?$'; then
+            VERSION_NUMBER=$(echo "$VERSION_STR" | sed -E 's/^v?([0-9]+\.[0-9]+\.[0-9]+)(-.+)?$/\1/')
+            echo "Version number: $VERSION_NUMBER"
+            if echo "$VERSION_STR" | grep -q '-'; then
+              # We can only get into this branch if the initial grep regex worked AND '-' is there
+              # So it's '[v]1.2.3-something'
+              SUFFIX=$(echo "$VERSION_STR" | sed -E 's/^v?([0-9]+\.[0-9]+\.[0-9]+)-(.+)$/\2/')
+              if echo "$SUFFIX" | grep -q '-'; then
+                echo "Invalid suffix (it contains hyphen): $SUFFIX" >&2
+                exit 1
+              fi
+              SUFFIX_WITH_SEP=$(echo "-$SUFFIX")
+            else
+              SUFFIX=""
+              SUFFIX_WITH_SEP=""
+            fi
+            echo "Suffix: $SUFFIX"
+          else
+            echo "Version string doesn't match the '[v]1.2.3[-suffix]' pattern: $VERSION_STR" >&2
+            exit 1
+          fi
+          VERSION_FULL=$(echo "${VERSION_NUMBER}${SUFFIX_WITH_SEP}")
+          echo "Full parsed Version: $VERSION_FULL"
+          TAG_NAME=$(echo "v${VERSION_FULL}")
+          echo "Tag name: $TAG_NAME"
+          echo "tag_name=$TAG_NAME" >> "$GITHUB_OUTPUT"
+          echo "version_full=$VERSION_FULL" >> "$GITHUB_OUTPUT"
+          echo "version_num=$VERSION_NUMBER" >> "$GITHUB_OUTPUT"
+          echo "suffix=$SUFFIX" >> "$GITHUB_OUTPUT"
+
+      - name: Create tag 🏷️ from version
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.git.createRef({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: `refs/tags/${process.env.TAG}`,
+              sha: context.sha
+            })
+        env:
+          TAG: ${{ steps.parse.outputs.tag_name }}
+
+  # --------------------------------------------------------
+
+  build:
+    name: Build distribution 📦
+    needs: [detect-version]  # No need to even try, if we failed tag parsing
+    # Just to be nice - let's check the GitHub user and prevent unwanted auto-runs on forks made solely for a PR.
+    if: >-
+      github.repository_owner == 'Lex-DRL'
+    # Second condition: only run on tag pushes...
+    # It was in the template from official tutorial, but it got redundant, since the only trigger is `on.push.tags`
+    #  && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  # --------------------------------------------------------
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI ⬆️
+    if: ${{ github.repository_owner == 'Lex-DRL' }}
+    needs:
+    - build  # Requires the previous 'build' job to succeed
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ env.PACKAGE_NAME }}
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  # --------------------------------------------------------
+
+#  publish-to-testpypi:
+#    name: Publish Python 🐍 distribution 📦 to TestPyPI ❗
+#    if: ${{ github.repository_owner == 'Lex-DRL' }}
+#    needs:
+#    - build  # Requires the previous 'build' job to succeed
+#    runs-on: ubuntu-latest
+#
+#    environment:
+#      #name: testpypi
+#      # Yes, it's "not cool" to use the same environment for testing and publishing,
+#      # but in this particular repo I only use the TestPyPI for initial debugging of the workflow
+#      name: pypi
+#      url: https://test.pypi.org/p/${{ env.PACKAGE_NAME }}
+#    permissions:
+#      id-token: write  # IMPORTANT: mandatory for trusted publishing
+#
+#    steps:
+#    - name: Download all the dists
+#      uses: actions/download-artifact@v4
+#      with:
+#        name: python-package-distributions
+#        path: dist/
+#
+#    - name: Publish distribution 📦 to TestPyPI
+#      uses: pypa/gh-action-pypi-publish@release/v1
+#      with:
+#        repository-url: https://test.pypi.org/legacy/
+
+  # --------------------------------------------------------
+
+  github_release:
+      name: Create GitHub Release 🔄
+      needs: [build, detect-version]
+      runs-on: ubuntu-latest
+      permissions:
+        contents: write
+      steps:
+        - name: Checkout Code
+          uses: actions/checkout@v4
+          with:
+            fetch-depth: 0 # Fetch full history to avoid issues with tags and branches
+
+        - name: Download artifacts
+          uses: actions/download-artifact@v4
+          with:
+            name: python-package-distributions
+            path: dist/
+
+        - name: Create GitHub Release
+          id: create_release
+          env:
+            GH_TOKEN: ${{ github.token }}
+          run: >-
+            gh release create
+            ${{ needs.detect-version.outputs.tag_name }}
+            dist/*
+            --title ${{ needs.detect-version.outputs.tag_name }}
+            --generate-notes

docstring_to_text-1.0.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: docstring-to-text
+Version: 1.0.0
+Summary: A simple pip package converting docstrings into clean text (proper paragraphs and indents)
+Project-URL: Source Code, https://github.com/Lex-DRL/Py-docstring-to-text
+Project-URL: Issues, https://github.com/Lex-DRL/Py-docstring-to-text/issues
+Author: Lex Darlog (Lex-DRL)
+License-Expression: MPL-2.0
+License-File: LICENSE.md
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# docstring-to-text
+
+A simple pip package converting docstrings into clean text (proper paragraphs and indents).
+
+For example, here's a class docstring:
+```python
+class MyClass:
+  """
+  Here's a class.
+  
+  
+  It has sphinx-like paragraphs, which can
+  span multiple lines. Any modern IDE would
+  display them as a single line, that wraps
+  the given width.
+  
+  You can't just remove all the new lines
+  in the entire string, because you want
+  to preserve paragraphs themselves.
+  
+  Also, when it comes to lists:
+  - You probably want to separate items
+    with new lines.
+  - However, you don't want to preserve
+    lines inside each item.
+  * And you might need various bullet
+    characters.
+  • Including unicode ones.
+  
+  And don't forget that the list still needs
+  to be separated from the following text.
+  """
+  ...
+```
+
+With this package, you could do:
+```python
+from docstring_to_text import *
+
+clean_text = format_docstring(cleandoc(MyClass.__doc__))
+clean_text = format_object_docstring(MyClass)
+```
+
+Then, the resulting string would be:
+```text
+Here's a class.
+
+It has sphinx-like paragraphs, which can span multiple lines. Any modern IDE would display them as a single line, that wraps the given width.
+You can't just remove all the new lines in the entire string, because you want to preserve paragraphs themselves.
+Also, when it comes to lists:
+- You probably want to separate items with new lines.
+- However, you don't want to preserve lines inside each item.
+* And you might need various bullet characters.
+• Including unicode ones.
+And don't forget that the list still needs to be separated from the following text.
+```

docstring_to_text-1.0.0/README.md

@@ -0,0 +1,56 @@
+# docstring-to-text
+
+A simple pip package converting docstrings into clean text (proper paragraphs and indents).
+
+For example, here's a class docstring:
+```python
+class MyClass:
+  """
+  Here's a class.
+  
+  
+  It has sphinx-like paragraphs, which can
+  span multiple lines. Any modern IDE would
+  display them as a single line, that wraps
+  the given width.
+  
+  You can't just remove all the new lines
+  in the entire string, because you want
+  to preserve paragraphs themselves.
+  
+  Also, when it comes to lists:
+  - You probably want to separate items
+    with new lines.
+  - However, you don't want to preserve
+    lines inside each item.
+  * And you might need various bullet
+    characters.
+  • Including unicode ones.
+  
+  And don't forget that the list still needs
+  to be separated from the following text.
+  """
+  ...
+```
+
+With this package, you could do:
+```python
+from docstring_to_text import *
+
+clean_text = format_docstring(cleandoc(MyClass.__doc__))
+clean_text = format_object_docstring(MyClass)
+```
+
+Then, the resulting string would be:
+```text
+Here's a class.
+
+It has sphinx-like paragraphs, which can span multiple lines. Any modern IDE would display them as a single line, that wraps the given width.
+You can't just remove all the new lines in the entire string, because you want to preserve paragraphs themselves.
+Also, when it comes to lists:
+- You probably want to separate items with new lines.
+- However, you don't want to preserve lines inside each item.
+* And you might need various bullet characters.
+• Including unicode ones.
+And don't forget that the list still needs to be separated from the following text.
+```

{docstring_to_text-0.0.1 → docstring_to_text-1.0.0}/_build.bat

@@ -1,23 +1,24 @@
-@echo off
-
-call .\venv\Scripts\activate.bat
-
-echo Where python:
-echo.
-where python
-echo.
-echo Continue?
-
-pause
-
-.\venv\Scripts\python.exe -m pip install -U pip
-.\venv\Scripts\python.exe -m pip install -U build
-
-echo.
-echo.
-echo ============================================================
-echo.
-echo.
-
-.\venv\Scripts\python.exe -m build
-pause
+@echo off
+
+call .\venv\Scripts\activate.bat
+
+echo Where python:
+echo.
+where python
+echo.
+echo                     BUILD?
+echo.
+
+pause
+
+.\venv\Scripts\python.exe -m pip install -U pip
+.\venv\Scripts\python.exe -m pip install -U build
+
+echo.
+echo.
+echo ============================================================
+echo.
+echo.
+
+.\venv\Scripts\python.exe -m build
+pause

docstring_to_text-1.0.0/_upload-release.bat

@@ -0,0 +1,24 @@
+@echo off
+
+call .\venv\Scripts\activate.bat
+
+echo Where python:
+echo.
+where python
+echo.
+echo                     RELEASE?
+echo.
+
+pause
+
+.\venv\Scripts\python.exe -m pip install -U pip
+.\venv\Scripts\python.exe -m pip install -U twine
+
+echo.
+echo.
+echo ============================================================
+echo.
+echo.
+
+.\venv\Scripts\python.exe -m twine upload dist/*
+pause

docstring_to_text-1.0.0/_upload-test.bat

@@ -0,0 +1,24 @@
+@echo off
+
+call .\venv\Scripts\activate.bat
+
+echo Where python:
+echo.
+where python
+echo.
+echo                     Upload to TEST PyPI?
+echo.
+
+pause
+
+.\venv\Scripts\python.exe -m pip install -U pip
+.\venv\Scripts\python.exe -m pip install -U twine
+
+echo.
+echo.
+echo ============================================================
+echo.
+echo.
+
+.\venv\Scripts\python.exe -m twine upload --repository testpypi dist/*
+pause

{docstring_to_text-0.0.1 → docstring_to_text-1.0.0}/pyproject.toml

@@ -1,3 +1,5 @@
+# https://packaging.python.org/en/latest/tutorials/packaging-projects/
+
 [build-system]
 requires = ["hatchling >= 1.26"]
 build-backend = "hatchling.build"
@@ -23,7 +25,7 @@ classifiers = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/Lex-DRL/Py-docstring-to-text"
+"Source Code" = "https://github.com/Lex-DRL/Py-docstring-to-text"
 Issues = "https://github.com/Lex-DRL/Py-docstring-to-text/issues"
 
 [tool.hatch.version]

docstring_to_text-1.0.0/src/docstring_to_text/__init__.py

@@ -0,0 +1,152 @@
+# encoding: utf-8
+"""
+A simple pip package converting docstrings into clean text (proper paragraphs and indents).
+"""
+
+import typing as _t
+
+from inspect import cleandoc, getdoc
+import re as _re
+
+from .__package_meta import VERSION
+from .__package_meta import VERSION as __version__
+
+
+_re_indent_match = _re.compile(r"(\t*)( +)(\t*)(.*?)$").match
+_re_tab_indent_match = _re.compile(r"(\t+)(.*?)$").match
+_re_list_line_match = _re.compile(
+	r"(\s*)("
+	r"[-*•]+"
+	r"|"
+	r"[a-zA-Z]\s*[.)]"
+	r"|"
+	r"[0-9+]\s*[.)]"
+	r")\s+"
+).match
+
+
+def _recover_tab_indents(line: str, tab_size: int):
+	"""Turn indenting spaces back to tabs using regexp. Half-tab indents are rounded."""
+	assert bool(line) and isinstance(line, str)
+
+	n_tabs = 0.0
+
+	match = _re_indent_match(line)
+	while match:
+		pre_tabs, spaces, post_tabs, line = match.groups()
+		n_tabs_from_spaces = float(len(spaces)) / tab_size + 0.00001
+		n_post_tabs = len(post_tabs)
+		if n_post_tabs > 0:
+			# There are tabs after spaces. Don't preserve the fractional spaces-indent, truncate it:
+			n_tabs_from_spaces = int(n_tabs_from_spaces)
+		n_tabs += len(pre_tabs) + n_tabs_from_spaces + n_post_tabs
+		match = _re_indent_match(line)
+
+	if n_tabs < 0.5:
+		return line
+
+	tabs_prefix = '\t' * int(n_tabs + 0.50001)
+	return f"{tabs_prefix}{line}"
+
+
+def _join_paragraph_and_format_tabs(paragraph: _t.List[str], tab_size: int):
+	"""
+	Given "continuous" paragraph (i.e., with no empty newlines between chunks), recover tabs for each chunk
+	and join them together into a single actual line.
+	Works as a generator to account for blocks with different indents - to make each its own line.
+	"""
+	pending_indent = 0
+	pending_chunks: _t.List[str] = list()
+
+	def join_pending_chunks() -> str:
+		return "{}{}".format('\t' * pending_indent, ' '.join(pending_chunks))
+
+	for chunk in paragraph:
+		chunk = _recover_tab_indents(chunk, tab_size)
+
+		cur_indent = 0
+		match = _re_tab_indent_match(chunk)
+		if match:
+			tab_indent, chunk = match.groups()  # We've detected indent. Now, get rid of it.
+			cur_indent = len(tab_indent)
+
+		match_list_line = _re_list_line_match(chunk)
+		# In case of a bulleted/numbered list, we'll need to start a new block, too.
+		if cur_indent == pending_indent and not match_list_line:
+			pending_chunks.append(chunk)
+			continue
+
+		# Indent mismatch or a list line:
+		# we're either ended one block or entered another. Either way, the previous block ends.
+		if pending_chunks:
+			yield join_pending_chunks()
+			pending_chunks = list()
+		assert not pending_chunks
+		pending_chunks.append(chunk)
+		pending_indent = cur_indent
+
+	if pending_chunks:
+		yield join_pending_chunks()
+
+
+def _formatted_paragraphs_gen(doc: str, tab_size: int):
+	"""
+	Generator, which splits docstring into lines and transforms them into an actual printable output:
+	- From each bulk of empty lines, the first one is skipped...
+	- ... thus, non-empty lines are joined into continuous paragraphs.
+	- Recover tabs in the beginning oh lines (``inspect.cleandoc()`` converts them into spaces).
+	"""
+	if not doc:
+		return
+	doc = str(doc)
+	if not doc.strip():
+		return
+
+	tab_size = max(int(tab_size), 1)
+
+	cur_paragraph: _t.List[str] = list()
+
+	for line in doc.splitlines():
+		line: str = line.rstrip()
+		if line:
+			cur_paragraph.append(line)
+			continue
+
+		assert not line
+		if cur_paragraph:
+			for block in _join_paragraph_and_format_tabs(cur_paragraph, tab_size):
+				yield block
+			cur_paragraph = list()
+			# Just skip the current empty line entirely - do nothing with it.
+			continue
+
+		# We're in a chain of empty lines, and we've already skipped the first one. Preserve the remaining ones:
+		yield ''
+
+	# Return the last paragraph post-loop:
+	if cur_paragraph:
+		for block in _join_paragraph_and_format_tabs(cur_paragraph, tab_size):
+			yield block
+
+
+def format_docstring(doc: str, tab_size: int = 8) -> str:
+	"""
+	Turn a pre-cleaned-up docstring (with tabs as spaces and newlines mid-sentence)
+	into an actually printable output:
+	- mid-paragraph new lines are replaced with spaces...
+	- ... while still keeping indented blocks separate.
+
+	Remember to pass a pre-cleaned-up docstring - i.e., with one of:
+	- format_docstring(inspect.cleandoc(__doc__))
+	- format_docstring(inspect.getdoc(class_or_function))
+	"""
+	return '\n'.join(_formatted_paragraphs_gen(doc, tab_size))
+
+
+def format_object_docstring(_obj, tab_size: int = 8) -> str:
+	"""Find the object's docstring and format it with ``format_docstring()``"""
+	doc = getdoc(_obj)
+	if not doc:
+		return ''
+	# noinspection PyArgumentList
+	return format_docstring(doc, tab_size=tab_size)

{docstring_to_text-0.0.1 → docstring_to_text-1.0.0}/src/docstring_to_text/__package_meta.py

@@ -1,3 +1,3 @@
 # encoding: utf-8
 
-VERSION = "0.0.1"
+VERSION = "1.0.0"

docstring_to_text-0.0.1/PKG-INFO

@@ -1,18 +0,0 @@
-Metadata-Version: 2.4
-Name: docstring-to-text
-Version: 0.0.1
-Summary: A simple pip package converting docstrings into clean text (proper paragraphs and indents)
-Project-URL: Homepage, https://github.com/Lex-DRL/Py-docstring-to-text
-Project-URL: Issues, https://github.com/Lex-DRL/Py-docstring-to-text/issues
-Author: Lex Darlog (Lex-DRL)
-License-Expression: MPL-2.0
-License-File: LICENSE.md
-Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-
-# docstring-to-text
-
-A simple pip package converting docstrings into clean text (proper paragraphs and indents)

docstring_to_text-0.0.1/README.md

@@ -1,3 +0,0 @@
-# docstring-to-text
-
-A simple pip package converting docstrings into clean text (proper paragraphs and indents)

docstring_to_text-0.0.1/src/docstring_to_text/__init__.py

@@ -1,6 +0,0 @@
-# encoding: utf-8
-"""
-"""
-
-from .__package_meta import VERSION
-from .__package_meta import VERSION as __version__