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

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

@@ -31,7 +31,7 @@ on:
     branches:
       - main
     paths:
-      - "src/docstring_to_text/__package_meta.py"
+      - "src/docstring_to_text/___package_meta.py"
 
 # ====== CONCURRENCY ======
 
@@ -39,7 +39,7 @@ on:
 concurrency:
   group: pypi-publish
   # To group by version:
-  #group: pypi-publish-${{ github.ref }}-${{ hashFiles('src/docstring_to_text/__package_meta.py') }}
+  #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 =======
@@ -47,8 +47,8 @@ concurrency:
 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_FILE: 'src/docstring_to_text/___package_meta.py'
+  VERSION_MODULE: 'src.docstring_to_text.___package_meta'
   VERSION_VARIABLE: 'VERSION'
 
 # ========= JOBS =========
@@ -270,7 +270,7 @@ jobs:
   # --------------------------------------------------------
 
   github_release:
-    name: Create GitHub Tag 🏷️ and Release 🔄
+    name: GitHub Tag 🏷️ + Release 🔄
     needs: [build, detect-version]
     runs-on: ubuntu-latest
     permissions:

docstring_to_text-1.0.3/.github/workflows/test.yml

@@ -0,0 +1,68 @@
+# https://docs.github.com/en/actions/tutorials/build-and-test-code/python
+name: Tests 🔬
+# Alt emojis: https://emojidb.org/debug-emojis 👀 🔎 👷 🚧 🛠️ 🔨 👾 🤖 👨🏻‍💻 🧐
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+  pull_request:
+    branches: [ main ]
+    # types: [ opened, synchronize, reopened ]  # default values; comments, labels, etc. are ignored
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    # runs-on: ${{ matrix.os }}  # when multi-OS-testing specified below
+    runs-on: ubuntu-latest
+    timeout-minutes: 5  # Prevent stuck jobs
+
+    strategy:
+      matrix:
+        # To test on multiple OSes:
+        # https://docs.github.com/en/actions/tutorials/build-and-test-code/python#excluding-a-version
+        # os: [ubuntu-latest, macos-latest, windows-latest]
+
+        # Python versions to test against:
+        python-version:
+          # > The version '3.7' with architecture 'x64' was not found for Ubuntu 24.04.
+          # - '3.7'  # seems no longer supported by GitHub
+          - '3.8'
+          - '3.9'
+          - '3.10'
+          - '3.11'
+          - '3.12'
+          - '3.13'
+          - '3.14'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'  # Enable built-in pip caching
+          cache-dependency-path: 'pyproject.toml'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # Just to be safe, in case some pytest plugins need the package itself installed into venv,
+          # do the "editable" install... and since we're doing it anyway,
+          # let's also install the test dependencies from pyproject.toml, too:
+          pip install -e .[test]
+          # Alternatively:
+          # pip install pytest pytest-cov  # Only test deps, no package, but doesn't use deps from pyproject.toml
+
+      - name: Run tests with pytest
+        run: |
+          python -m pytest

{docstring_to_text-1.0.1 → docstring_to_text-1.0.3}/.gitignore

@@ -121,6 +121,9 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *.cover
+# The next one is NOT a typo - whether a bug in coverage lib or not, but it
+# can actually create a file with such "extension" (with comma):
+# https://github.com/nedbat/coveragepy/blob/8827634adcfe4a4baf71cf0b3e1cd967cf9b14a2/coverage/annotate.py#L84
 *,cover
 .hypothesis/
 .pytest_cache/

{docstring_to_text-1.0.1 → docstring_to_text-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-to-text
-Version: 1.0.1
+Version: 1.0.3
 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
@@ -11,17 +11,34 @@ 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
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
 Description-Content-Type: text/markdown
 
+<div align="center">
+  
 # docstring-to-text
 
+[![PyPI][pypi-shield]][pypi-url]
+[![GitHub Release][github-release-shield]][github-release-url]
+[![Test status][github-tests-shield]][github-tests-url]
+
+[pypi-shield]: https://img.shields.io/pypi/v/docstring-to-text?logo=pypi
+[pypi-url]: https://pypi.org/p/docstring-to-text
+[github-tests-shield]: https://github.com/Lex-DRL/Py-docstring-to-text/actions/workflows/test.yml/badge.svg?branch=main
+[github-tests-url]: https://github.com/Lex-DRL/Py-docstring-to-text/actions/workflows/test.yml?query=branch%3Amain
+[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
@@ -60,7 +77,7 @@ 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.

{docstring_to_text-1.0.1 → docstring_to_text-1.0.3}/README.md

@@ -1,12 +1,26 @@
+<div align="center">
+  
 # docstring-to-text
 
+[![PyPI][pypi-shield]][pypi-url]
+[![GitHub Release][github-release-shield]][github-release-url]
+[![Test status][github-tests-shield]][github-tests-url]
+
+[pypi-shield]: https://img.shields.io/pypi/v/docstring-to-text?logo=pypi
+[pypi-url]: https://pypi.org/p/docstring-to-text
+[github-tests-shield]: https://github.com/Lex-DRL/Py-docstring-to-text/actions/workflows/test.yml/badge.svg?branch=main
+[github-tests-url]: https://github.com/Lex-DRL/Py-docstring-to-text/actions/workflows/test.yml?query=branch%3Amain
+[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
@@ -45,7 +59,7 @@ 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.

docstring_to_text-1.0.3/pyproject.toml

@@ -0,0 +1,74 @@
+# https://packaging.python.org/en/latest/tutorials/packaging-projects/
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "docstring-to-text"
+dynamic = ["version"]
+# version = "0.0.1" # used dynamically, see tool.hatch.version
+description = "A simple pip package converting docstrings into clean text (proper paragraphs and indents)"
+authors = [
+	{ name="Lex Darlog (Lex-DRL)" },
+]
+readme = "README.md"
+# https://packaging.python.org/en/latest/specifications/core-metadata/#license-expression
+# https://spdx.org/licenses/
+license = "MPL-2.0"
+license-files = ["LICEN[CS]E*"]
+requires-python = ">=3.7"
+classifiers = [
+	"Programming Language :: Python :: 3",
+	"Operating System :: OS Independent",
+	"License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
+]
+
+[project.urls]
+"Source Code" = "https://github.com/Lex-DRL/Py-docstring-to-text"
+Issues = "https://github.com/Lex-DRL/Py-docstring-to-text/issues"
+
+[project.optional-dependencies]
+# For: pip install .[test]
+test = [
+	"pytest",
+	"pytest-cov",
+]
+
+[tool.hatch.version]
+path = "src/docstring_to_text/___package_meta.py"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]  # Don't scan for tests anywhere else; speeds up test collection
+addopts = [
+	"--import-mode=importlib",  # Recommended for new projects to avoid sys.path manipulation issues
+	"-ra",  # Show summary of all test outcomes
+	"--ignore=tests/data/",  # Excludes this exact path from discovery
+	"--cov=docstring_to_text",  # Measure the package coverage
+	"--cov-report=term-missing",  # Show missing lines in terminal
+	"--cov-fail-under=0",  # Never fail tests due to low coverage
+]
+
+[tool.coverage.run]
+source = ["src/docstring_to_text"]
+omit = [
+	"*/tests/*",
+	"*/test_*",
+	"*/__pycache__/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+	"pragma: no cover",
+	"def __repr__",
+	"if self\\.debug",
+	"if settings\\.DEBUG",
+	"raise AssertionError",
+	"raise NotImplementedError",
+	"if 0:",
+	"if __name__ == [\"']__main__[\"']:",
+	"@(abc\\.)?abstractmethod",
+]
+ignore_errors = true
+precision = 2  # Number of shown decimal places. E.g.: 12.34%

docstring_to_text-1.0.3/src/docstring_to_text/___package_meta.py

@@ -0,0 +1,111 @@
+# encoding: utf-8
+
+# It should be a hard-coded string, as close to the beginning of file as possible,
+# for Hatchling build tools to properly parse it:
+VERSION = "1.0.3"
+
+
+# =============================================================
+# Parsing it into a tuple, more suitable for version comparison
+
+
+import typing as _t
+
+import re as _re
+
+_re_separate = _re.compile(
+	# r'^'  # not necessary with `re.match()`
+	r'([a-zA-Z_0-9\s]*)'  # valid version-seg characters - greedy
+	r'[^a-zA-Z_0-9\s]+'  # anything else
+	r'(.*?)'  # the remainder of the string, possibly with a mix of both - lazy
+	r'$'  # must match the entire string
+).match
+
+
+def _raw_version_parts_gen(ver_str: str) -> _t.Generator[str, _t.Any, None]:
+	"""Splits version string into parts.
+
+	Parts contain only alphanumeric characters, underscores and spaces/tabs.
+	Anything else considered a separator.
+	Integer sub-parts aren't extracted yet.
+	"""
+	assert ver_str and isinstance(ver_str, str)
+	remainder: str = ver_str.strip()
+
+	match = _re_separate(remainder)
+	while match:
+		groups = [
+			x.strip() if x else ''
+			for x in match.groups()
+		]
+		while len(groups) < 2:
+			groups.append('')
+		part, remainder = groups[:2]
+
+		# to replace any whitespace sequences to single spaces:
+		part = ' '.join(part.split())
+		if part:
+			yield part
+
+		match = _re_separate(remainder)
+
+	if remainder:
+		yield remainder
+
+
+_re_int_extractor = _re.compile(
+	r'([^0-9]*)'
+	r'([0-9]+)'
+	r'([^0-9].*?)?'
+	r'$'
+).match
+
+
+def _part_to_final_segs_gen(str_part: str) -> _t.Generator[_t.Union[int, str], _t.Any, None]:
+	"""Given one part, separates it into actual version segments."""
+	assert str_part and isinstance(str_part, str)
+	remainder: str = str_part
+
+	while remainder:
+		remainder = remainder.strip().strip('_')
+		match = _re_int_extractor(remainder)
+		if not match:
+			assert not any(x in remainder for x in '0123456789'), (
+				f"Internal error: last version-remainder for {str_part!r} part still contains digits: {remainder!r}"
+			)
+			break
+
+		groups = [
+			x.strip().strip('_') if x else ''
+			for x in match.groups()
+		]
+		while len(groups) < 3:
+			groups.append('')
+		text_prefix, int_str, remainder = groups[:3]
+
+		if text_prefix:
+			yield text_prefix
+
+		yield int(int_str)
+
+	if remainder:
+		yield remainder
+
+
+def _version_parts_gen(ver_str: str) -> _t.Generator[_t.Union[int, str], _t.Any, None]:
+	"""Parse version string into parts, with ints.
+
+	- '0.1.2' -> (0, 1, 2)
+	- '0.1.2rc' -> (0, 1, 2, 'rc')
+	- '0.1.2rc0123' -> (0, 1, 2, 'rc', 123)
+	- '0.1.2-alpha1' -> (0, 1, 2, 'alpha', 1)
+	- '0-1-2-beta-1' -> (0, 1, 2, 'beta', 1)  # though, non-compliant with semantic versioning
+	- '0.1.2.beta.2' -> (0, 1, 2, 'beta', 2)
+	"""
+	for str_part in _raw_version_parts_gen(ver_str):
+		for seg in _part_to_final_segs_gen(str_part):
+			yield seg
+
+
+# For actual python code to compare:
+VERSION_TUPLE: _t.Tuple[_t.Union[int, str], ...] = tuple(_version_parts_gen(VERSION))

{docstring_to_text-1.0.1 → docstring_to_text-1.0.3}/src/docstring_to_text/__init__.py

@@ -3,13 +3,17 @@
 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

docstring_to_text-1.0.3/tests/import_test.py

@@ -0,0 +1,18 @@
+# encoding: utf-8
+"""A sanity-check import test - just to have at least one test, which (supposedly) always passes."""
+
+
+def test_import_package():
+	try:
+		import docstring_to_text
+	except ImportError:
+		assert False, "Can't import the package"
+	assert True
+
+
+def test_import_version():
+	try:
+		from docstring_to_text import VERSION
+	except ImportError:
+		assert False, "Can't import the package version"
+	assert isinstance(VERSION, str)

docstring_to_text-1.0.3/tests/test____package_meta.py

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+# 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 typing import Union as _U
+
+import pytest
+
+from docstring_to_text.___package_meta import _version_parts_gen
+
+@pytest.mark.parametrize(
+	"ver_str, ver_tuple",
+	[
+		('1.2:3', (1, 2, 3)),
+		('4`5 6', (4, 5, 6)),
+		('7 8!`-~9--.__Release Candidate__', (7, 8, 9, 'Release Candidate')),
+		('0.1.2', (0, 1, 2)),
+		('0.1.2rc', (0, 1, 2, 'rc')),
+		('0.1.2rc0', (0, 1, 2, 'rc', 0)),
+		('0.1.2rc1', (0, 1, 2, 'rc', 1)),
+		('0.1.2rc0123', (0, 1, 2, 'rc', 123)),
+		('0.1.2-alpha', (0, 1, 2, 'alpha')),
+		('0.1.2-alpha1', (0, 1, 2, 'alpha', 1)),
+		('0-1-2-beta-1', (0, 1, 2, 'beta', 1)),
+		('0.1.2.beta.2', (0, 1, 2, 'beta', 2)),
+	]
+)
+def test__version_parts_gen(ver_str: str, ver_tuple: _t.Tuple[_U[int, str], ...]):
+	assert tuple(_version_parts_gen(ver_str)) == ver_tuple

docstring_to_text-1.0.1/pyproject.toml

@@ -1,32 +0,0 @@
-# https://packaging.python.org/en/latest/tutorials/packaging-projects/
-
-[build-system]
-requires = ["hatchling >= 1.26"]
-build-backend = "hatchling.build"
-
-[project]
-name = "docstring-to-text"
-dynamic = ["version"]
-# version = "0.0.1"
-description = "A simple pip package converting docstrings into clean text (proper paragraphs and indents)"
-authors = [
-	{ name="Lex Darlog (Lex-DRL)" },
-]
-readme = "README.md"
-# https://packaging.python.org/en/latest/specifications/core-metadata/#license-expression
-# https://spdx.org/licenses/
-license = "MPL-2.0"
-license-files = ["LICEN[CS]E*"]
-requires-python = ">=3.7"
-classifiers = [
-	"Programming Language :: Python :: 3",
-	"Operating System :: OS Independent",
-	"License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
-]
-
-[project.urls]
-"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]
-path = "src/docstring_to_text/__package_meta.py"

docstring_to_text-1.0.1/src/docstring_to_text/__package_meta.py

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