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

{docstring_to_text-1.0.0 → docstring_to_text-1.0.2}/.github/workflows/publish-release-to-pypi.yml

@@ -31,24 +31,34 @@ on:
     branches:
       - main
     paths:
-      - "src/docstring_to_text/__package_meta.py"
+      - "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_MODULE: 'src.docstring_to_text.__package_meta'
+  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: GitHub Tag 🏷️ + 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.0 → docstring_to_text-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-to-text
-Version: 1.0.0
+Version: 1.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
@@ -13,15 +13,26 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 
+<div align="center">
+  
 # docstring-to-text
 
+[![PyPI][pypi-shield]][pypi-url]
+[![][github-release-shield]][github-release-url]
+
+[pypi-shield]: https://img.shields.io/pypi/v/docstring-to-text?logo=pypi
+[pypi-url]: https://pypi.org/p/docstring-to-text
+[github-release-shield]: https://img.shields.io/github/v/release/Lex-DRL/Py-docstring-to-text?logo=github
+[github-release-url]: https://github.com/Lex-DRL/Py-docstring-to-text/releases/latest
+</div>
+
 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.
+  This is a class docstring.
   
   
   It has sphinx-like paragraphs, which can
@@ -34,12 +45,14 @@ class MyClass:
   to preserve paragraphs themselves.
   
   Also, when it comes to lists:
-  - You probably want to separate items
+    - You probably want to separate items
     with new lines.
-  - However, you don't want to preserve
+    - However, you don't want to preserve
     lines inside each item.
-  * And you might need various bullet
-    characters.
+  
+  And...
+  * ... you might need various bullet
+  characters.
   • Including unicode ones.
   
   And don't forget that the list still needs
@@ -58,14 +71,15 @@ clean_text = format_object_docstring(MyClass)
 
 Then, the resulting string would be:
 ```text
-Here's a class.
+This is a class docstring.
 
 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.
+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 → docstring_to_text-1.0.2}/README.md

@@ -1,12 +1,23 @@
+<div align="center">
+  
 # docstring-to-text
 
+[![PyPI][pypi-shield]][pypi-url]
+[![][github-release-shield]][github-release-url]
+
+[pypi-shield]: https://img.shields.io/pypi/v/docstring-to-text?logo=pypi
+[pypi-url]: https://pypi.org/p/docstring-to-text
+[github-release-shield]: https://img.shields.io/github/v/release/Lex-DRL/Py-docstring-to-text?logo=github
+[github-release-url]: https://github.com/Lex-DRL/Py-docstring-to-text/releases/latest
+</div>
+
 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.
+  This is a class docstring.
   
   
   It has sphinx-like paragraphs, which can
@@ -19,12 +30,14 @@ class MyClass:
   to preserve paragraphs themselves.
   
   Also, when it comes to lists:
-  - You probably want to separate items
+    - You probably want to separate items
     with new lines.
-  - However, you don't want to preserve
+    - However, you don't want to preserve
     lines inside each item.
-  * And you might need various bullet
-    characters.
+  
+  And...
+  * ... you might need various bullet
+  characters.
   • Including unicode ones.
   
   And don't forget that the list still needs
@@ -43,14 +56,15 @@ clean_text = format_object_docstring(MyClass)
 
 Then, the resulting string would be:
 ```text
-Here's a class.
+This is a class docstring.
 
 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.
+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 → docstring_to_text-1.0.2}/pyproject.toml

@@ -29,4 +29,4 @@ classifiers = [
 Issues = "https://github.com/Lex-DRL/Py-docstring-to-text/issues"
 
 [tool.hatch.version]
-path = "src/docstring_to_text/__package_meta.py"
+path = "src/docstring_to_text/___package_meta.py"

docstring_to_text-1.0.0/src/docstring_to_text/__package_meta.py → docstring_to_text-1.0.2/src/docstring_to_text/___package_meta.py

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

{docstring_to_text-1.0.0 → docstring_to_text-1.0.2}/src/docstring_to_text/__init__.py

@@ -3,13 +3,32 @@
 A simple pip package converting docstrings into clean text (proper paragraphs and indents).
 """
 
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
 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__
+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