docstring-to-text 0.0.2__tar.gz → 1.0.1__tar.gz

{docstring_to_text-0.0.2 → docstring_to_text-1.0.1}/.github/workflows/publish-release-to-pypi.yml

@@ -33,22 +33,32 @@ on:
     paths:
       - "src/docstring_to_text/__package_meta.py"
 
+# ====== CONCURRENCY ======
+
+# Prevent multiple simultaneous builds for the same version:
+concurrency:
+  group: pypi-publish
+  # To group by version:
+  #group: pypi-publish-${{ github.ref }}-${{ hashFiles('src/docstring_to_text/__package_meta.py') }}
+  cancel-in-progress: false  # the second pending run is put into a queue, the third one is cancelled (GitHub limitation)
+
 # ======= ENV VARS =======
 
 env:
   # The name on PyPI:
   PACKAGE_NAME: 'docstring-to-text'
+  VERSION_FILE: 'src/docstring_to_text/__package_meta.py'
   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 🏷️
+    name: Parse version 🔢
+    # 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' }}
     runs-on: ubuntu-latest
     permissions:
@@ -64,15 +74,53 @@ jobs:
         with:
           fetch-depth: 0 # Fetch full history to avoid issues with tags and branches
 
-      - name: Extract version from package meta 📝
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - 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 }})")
+          # Try doing it with Python first:
+          VERSION=$(
+            python -c \
+            "from ${{ env.VERSION_MODULE }} import ${{ env.VERSION_VARIABLE }}; print(${{ env.VERSION_VARIABLE }})" \
+            2>/dev/null \
+            | head -1
+          )
+          if [ $? -ne 0 ] || [ -z "$VERSION" ]; then  # previous command had non-zero exit status or version is empty
+            echo "Failed to retrieve version with python. Attempting to parse it directly from file, with regexp..."
+            VERSION=$(
+              grep -oP "^\s*${{ env.VERSION_VARIABLE }}\s*=\s*['\"]\K[^'\"]+" "${{ env.VERSION_FILE }}" \
+              2>/dev/null \
+              | head -1
+            )
+          fi
+          if [ $? -ne 0 ] || [ -z "$VERSION" ]; then
+            echo "Error: Failed to retrieve version." >&2
+            exit 1
+          fi
           echo "Version string: $VERSION"
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
 
-      - name: Parse Version 🧱
+      # TODO: get rid of the following bash insanity and just parse it with a special python script / shared module.
+      # Writing the output would use:
+      #   with open(os.environ['GITHUB_OUTPUT'], 'a') as fh:
+      #     print(f"{key}={value}", file=fh)
+#      - name: Parse Version with Python
+#        id: parse-with-python
+#        run: >-
+#          python parse_version.py
+#          "${{ steps.get_version_string.outputs.version }}"
+#        # Alternatively:
+#        #run: |
+#        #  python -c "
+#        #  # The entire python script inline
+#        #  version_str = '${{ steps.get_version_string.outputs.version }}'.lstrip('v')
+#        #  "
+
+      - name: Parse Version into parts 🧱
         id: parse
         # The main magic happens in regexps...
         # - `grep -qP`: verify that the tag matches the given pattern
@@ -121,29 +169,16 @@ jobs:
           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`
+    # It was in the template from official tutorial, but it got redundant with our deep version parsing and verification
+    # Kept here just as a condition example:
     #  && startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
 
@@ -165,6 +200,8 @@ jobs:
         build
         --user
 
+    # TODO: run tests before the build
+
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
 
@@ -233,30 +270,43 @@ jobs:
   # --------------------------------------------------------
 
   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
+    name: Create GitHub Tag 🏷️ and 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 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: ${{ needs.detect-version.outputs.tag_name }}
+
+      - 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.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: docstring-to-text
+Version: 1.0.1
+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.1/README.md

@@ -0,0 +1,59 @@
+# 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.1/src/docstring_to_text/__init__.py

@@ -0,0 +1,167 @@
+# 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__
+
+# TODO:
+# - lists
+#   formatted with indents
+#   in all lines except for the first one
+#
+# Also...
+#   - preserve indents
+#   - of the entire list
+#
+# And...
+#   - ensure
+#     that
+#     - it all works
+#       with nested lists
+
+
+_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.2 → docstring_to_text-1.0.1}/src/docstring_to_text/__package_meta.py

@@ -1,3 +1,3 @@
 # encoding: utf-8
 
-VERSION = "0.0.2"
+VERSION = "1.0.1"

docstring_to_text-0.0.2/PKG-INFO

@@ -1,18 +0,0 @@
-Metadata-Version: 2.4
-Name: docstring-to-text
-Version: 0.0.2
-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)

docstring_to_text-0.0.2/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.2/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__