finger2gemtext 0.0.1__tar.gz

finger2gemtext-0.0.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: finger2gemtext
+Version: 0.0.1
+Summary: A simple library for converting finger output to Gemtext
+Keywords: converter,Gemini,Gemtext,Hypertext,library,Markup,parser,Small Web,smolweb,finger
+Author: Dave Pearson
+Author-email: Dave Pearson <davep@davep.org>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Filters
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Homepage, https://finger2gemtext.davep.dev/
+Project-URL: Repository, https://github.com/davep/finger2gemtext
+Project-URL: Documentation, https://finger2gemtext.davep.dev/
+Project-URL: Source, https://github.com/davep/finger2gemtext
+Project-URL: Issues, https://github.com/davep/finger2gemtext/issues
+Project-URL: Discussions, https://github.com/davep/finger2gemtext/discussions
+Description-Content-Type: text/markdown
+
+# finger2gemtext - A simple library for converting finger output to Gemtext
+
+## Introduction
+
+`finger2gemtext` is a small and simple library that provides code for
+converting `finger` responses into [the hypertext markup language of the
+Gemini project](https://geminiprotocol.net/docs/gemtext-specification.gmi).
+
+## Installation
+
+`finger2gemtext` is [available from
+pypi](https://pypi.org/project/finger2gemtext/) and can be installed with your
+package installer of choice.
+
+With `pip`:
+
+```shell
+pip install finger2gemtext
+```
+
+With `uv`:
+
+```shell
+uv add finger2gemtext
+```
+
+## Quick start
+
+The library provides a single main conversion function called
+`finger_to_gemtext`. It is passed a string that is the finger response you
+wish to convert, and the result is a string that is the resulting Gemtext.
+
+A very minimal converter might look like:
+
+```python
+import fileinput
+from .convert import finger_to_gemtext
+
+def convert() -> None:
+    """Parse the input from stdin or files and print the parsed Gemtext."""
+    with fileinput.input() as finger_content:
+        print(finger_to_gemtext("".join(finger_content)))
+```
+
+While it is primarily intended as a library to be used from other Python
+code, it does contain a simple test command line tool, which can be accessed
+either via the Python `-m` switch, or depending on your environment, via the
+`finger2gemtext` command. For example, if you were to run this command:
+
+```sh
+finger @typed-hole.org | finger2gemtext
+```
+
+you'd get output like this:
+
+```gemtext
+[typed-hole.org]
+
+Welcome to the Typed Hole
+Uptime:  14:10:28 up 248 days, 22:12,  0 user,  load average: 0.44, 0.34, 0.44
+Users currently logged in: probably julien
+
+Available fingers:
+
+=> /finger/username username:           get user infos
+=> /finger/feed feed:                   get my latest toots
+=> /finger/lobsters lobsters:           get lobste.rs hottest stories
+=> /finger/weather weather:             get typed-hole.org current weather
+=> /finger/temp temp:                   get typed-hole.org current CPU temperature
+=> /finger/cyoa cyoa:                   finger your own adventure
+=> /finger/textfile textfile:           read a random textfile from textfiles.com
+=> /finger/smog smog:                   read SMOG e-zine issues
+```
+
+See [the main documentation](https://finger2gemtext.davep.dev/) for the full API.
+
+[//]: # (README.md ends here)

finger2gemtext-0.0.1/README.md

@@ -0,0 +1,77 @@
+# finger2gemtext - A simple library for converting finger output to Gemtext
+
+## Introduction
+
+`finger2gemtext` is a small and simple library that provides code for
+converting `finger` responses into [the hypertext markup language of the
+Gemini project](https://geminiprotocol.net/docs/gemtext-specification.gmi).
+
+## Installation
+
+`finger2gemtext` is [available from
+pypi](https://pypi.org/project/finger2gemtext/) and can be installed with your
+package installer of choice.
+
+With `pip`:
+
+```shell
+pip install finger2gemtext
+```
+
+With `uv`:
+
+```shell
+uv add finger2gemtext
+```
+
+## Quick start
+
+The library provides a single main conversion function called
+`finger_to_gemtext`. It is passed a string that is the finger response you
+wish to convert, and the result is a string that is the resulting Gemtext.
+
+A very minimal converter might look like:
+
+```python
+import fileinput
+from .convert import finger_to_gemtext
+
+def convert() -> None:
+    """Parse the input from stdin or files and print the parsed Gemtext."""
+    with fileinput.input() as finger_content:
+        print(finger_to_gemtext("".join(finger_content)))
+```
+
+While it is primarily intended as a library to be used from other Python
+code, it does contain a simple test command line tool, which can be accessed
+either via the Python `-m` switch, or depending on your environment, via the
+`finger2gemtext` command. For example, if you were to run this command:
+
+```sh
+finger @typed-hole.org | finger2gemtext
+```
+
+you'd get output like this:
+
+```gemtext
+[typed-hole.org]
+
+Welcome to the Typed Hole
+Uptime:  14:10:28 up 248 days, 22:12,  0 user,  load average: 0.44, 0.34, 0.44
+Users currently logged in: probably julien
+
+Available fingers:
+
+=> /finger/username username:           get user infos
+=> /finger/feed feed:                   get my latest toots
+=> /finger/lobsters lobsters:           get lobste.rs hottest stories
+=> /finger/weather weather:             get typed-hole.org current weather
+=> /finger/temp temp:                   get typed-hole.org current CPU temperature
+=> /finger/cyoa cyoa:                   finger your own adventure
+=> /finger/textfile textfile:           read a random textfile from textfiles.com
+=> /finger/smog smog:                   read SMOG e-zine issues
+```
+
+See [the main documentation](https://finger2gemtext.davep.dev/) for the full API.
+
+[//]: # (README.md ends here)

finger2gemtext-0.0.1/pyproject.toml

@@ -0,0 +1,111 @@
+[project]
+name = "finger2gemtext"
+version = "0.0.1"
+description = "A simple library for converting finger output to Gemtext"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+license = "MIT"
+keywords = [
+    "converter",
+    "Gemini",
+    "Gemtext",
+    "Hypertext",
+    "library",
+    "Markup",
+    "parser",
+    "Small Web",
+    "smolweb",
+    "finger",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Filters",
+    "Topic :: Text Processing :: Markup",
+    "Topic :: Text Processing",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Dave Pearson"
+email = "davep@davep.org"
+
+[project.urls]
+Homepage = "https://finger2gemtext.davep.dev/"
+Repository = "https://github.com/davep/finger2gemtext"
+Documentation = "https://finger2gemtext.davep.dev/"
+Source = "https://github.com/davep/finger2gemtext"
+Issues = "https://github.com/davep/finger2gemtext/issues"
+Discussions = "https://github.com/davep/finger2gemtext/discussions"
+
+[project.scripts]
+finger2gemtext = "finger2gemtext.__main__:convert"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+exclude = [".venv"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "UP",
+    "B",
+    "SIM",
+    "I",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 120
+
+[tool.coverage.run]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "def _repr_props",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    'class .*\bProtocol\):',
+    '@(abc\.)?abstractmethod',
+]
+
+[dependency-groups]
+dev = [
+    "codespell>=2.4.2",
+    "mypy>=2.1.0",
+    "pre-commit>=4.6.0",
+    "ruff>=0.15.17",
+]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+]
+test = [
+    "pytest>=9.1.0",
+    "pytest-cov>=7.1.0",
+]

finger2gemtext-0.0.1/pyproject.toml.orig

@@ -0,0 +1,118 @@
+[project]
+name = "finger2gemtext"
+version = "0.0.1"
+description = "A simple library for converting finger output to Gemtext"
+readme = "README.md"
+authors = [
+    { name = "Dave Pearson", email = "davep@davep.org" }
+]
+requires-python = ">=3.12"
+dependencies = []
+license = "MIT"
+keywords = [
+    "converter",
+    "Gemini",
+    "Gemtext",
+    "Hypertext",
+    "library",
+    "Markup",
+    "parser",
+    "Small Web",
+    "smolweb",
+    "finger",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Filters",
+    "Topic :: Text Processing :: Markup",
+    "Topic :: Text Processing",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://finger2gemtext.davep.dev/"
+Repository = "https://github.com/davep/finger2gemtext"
+Documentation = "https://finger2gemtext.davep.dev/"
+Source = "https://github.com/davep/finger2gemtext"
+Issues = "https://github.com/davep/finger2gemtext/issues"
+Discussions = "https://github.com/davep/finger2gemtext/discussions"
+
+[project.scripts]
+finger2gemtext = "finger2gemtext.__main__:convert"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.pyright]
+venvPath="."
+venv=".venv"
+exclude=[".venv"]
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 120
+
+[tool.coverage.run]
+omit = [
+     "tests/*"
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "def _repr_props",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+
+[dependency-groups]
+dev = [
+    "codespell>=2.4.2",
+    "mypy>=2.1.0",
+    "pre-commit>=4.6.0",
+    "ruff>=0.15.17",
+]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.7.6",
+    "mkdocstrings[python]>=1.0.4",
+]
+test = [
+    "pytest>=9.1.0",
+    "pytest-cov>=7.1.0",
+]

finger2gemtext-0.0.1/src/finger2gemtext/__init__.py

@@ -0,0 +1,34 @@
+"""A simple finger to Gemtext converter."""
+
+##############################################################################
+# Python imports.
+from importlib.metadata import version
+
+######################################################################
+# Main library information.
+__author__ = "Dave Pearson"
+__copyright__ = "Copyright 2026, Dave Pearson"
+__credits__ = ["Dave Pearson"]
+__maintainer__ = "Dave Pearson"
+__email__ = "davep@davep.org"
+__version__: str = version("finger2gemtext")
+__licence__ = "MIT"
+
+##############################################################################
+# Local imports.
+from .available_services import AvailableServicesFilter
+from .convert import finger_to_gemtext
+from .finger_filter import FingerFilter
+from .user_lists import UserListFilter
+
+##############################################################################
+# Exports.
+__all__ = [
+    "AvailableServicesFilter",
+    "finger_to_gemtext",
+    "FingerFilter",
+    "UserListFilter",
+]
+
+
+### __init__.py ends here

finger2gemtext-0.0.1/src/finger2gemtext/__main__.py

@@ -0,0 +1,22 @@
+##############################################################################
+# Python imports.
+import fileinput
+
+##############################################################################
+# Local imports.
+from .convert import finger_to_gemtext
+
+
+##############################################################################
+def convert() -> None:
+    """Parse the input from stdin or files and print the parsed Gemtext."""
+    with fileinput.input() as finger_content:
+        print(finger_to_gemtext("".join(finger_content)))
+
+
+##############################################################################
+if __name__ == "__main__":
+    convert()
+
+
+### __main__.py ends here

finger2gemtext-0.0.1/src/finger2gemtext/available_services.py

@@ -0,0 +1,71 @@
+"""Provides support code for working with available-services-type responses."""
+
+##############################################################################
+# Python imports.
+from re import Pattern, compile
+from typing import Final
+
+##############################################################################
+# Local imports.
+from .finger_filter import FingerFilter
+
+##############################################################################
+_TELL: Final[str] = "available fingers"
+"""String to look for in the Finger content to identify available services responses."""
+_SERVICE: Final[Pattern[str]] = compile(r"^(?P<name>\S+?):?\s{2,}.*$")
+
+
+##############################################################################
+class AvailableServicesFilter(FingerFilter):
+    """Filter for Finger available services responses."""
+
+    def __init__(self, peekable_lines: int = 20) -> None:
+        """Initialise the filter class.
+
+        Args:
+            peekable_lines: The number of lines to peek at when deciding the content type.
+        """
+        super().__init__(peekable_lines)
+
+    def can_likely_convert(self, finger_content: str) -> bool:
+        """Check if the filter can likely convert the given Finger content.
+
+        Args:
+            finger_content: The Finger content to check.
+
+        Returns:
+            [`True`][True] if the filter can likely convert the content;
+                [`False`][False] otherwise.
+        """
+        return any(
+            _TELL in line.lower() for line in self.peekable_lines(finger_content)
+        )
+
+    def to_gemtext(self, finger_content: str) -> str:
+        """Convert the given finger content to Gemtext.
+
+        Args:
+            finger_content: The Finger content to convert.
+
+        Returns:
+            The converted Gemtext content.
+        """
+        gemtext_lines: list[str] = []
+        gather = gemtext_lines.append
+        converting = False
+        found_services = False
+        for line in finger_content.splitlines():
+            if _TELL in line.lower():
+                gather(line)
+                converting = True
+                continue
+            if converting and (service := _SERVICE.match(line)) is not None:
+                gather(f"=> /finger/{service['name']} {line}")
+                found_services = True
+            else:
+                gather(line)
+        gather("")
+        return "\n".join(gemtext_lines) if found_services else finger_content
+
+
+### _available_services.py ends here

finger2gemtext-0.0.1/src/finger2gemtext/convert.py

@@ -0,0 +1,37 @@
+"""Provides a simple finger to Gemtext converter."""
+
+##############################################################################
+# Python imports.
+from collections.abc import Iterable
+
+##############################################################################
+# Local imports.
+from .available_services import AvailableServicesFilter
+from .finger_filter import FingerFilter
+from .user_lists import UserListFilter
+
+
+##############################################################################
+def finger_to_gemtext(
+    finger_content: str, additional_filters: Iterable[type[FingerFilter]] | None = None
+) -> str:
+    """Convert Finger content to Gemtext.
+
+    Args:
+        finger_content: The Finger content to convert.
+
+    Returns:
+        The converted Gemtext content.
+    """
+    filters: Iterable[type[FingerFilter]] = (
+        UserListFilter,
+        AvailableServicesFilter,
+        *(additional_filters or ()),
+    )
+    for current_filter in (candidate() for candidate in filters):
+        if current_filter.can_likely_convert(finger_content):
+            return current_filter.to_gemtext(finger_content)
+    return finger_content
+
+
+### convert.py ends here

finger2gemtext-0.0.1/src/finger2gemtext/finger_filter.py

@@ -0,0 +1,52 @@
+"""Provides the base finger filter class."""
+
+##############################################################################
+# Python imports.
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+
+
+##############################################################################
+class FingerFilter(ABC):
+    """Base class for finger filters."""
+
+    def __init__(self, peekable_lines: int = 10) -> None:
+        """Initialise the filter class.
+
+        Args:
+            peekable_lines: The number of lines to peek at when deciding the content type.
+        """
+        self._peekable_lines = max(1, peekable_lines)
+        """The number of lines to peek at when deciding the content type."""
+
+    def peekable_lines(self, finger_content: str) -> Iterator[str]:
+        """The number of lines to peek at when deciding the content type."""
+        for line_number, line in enumerate(finger_content.splitlines()):
+            if line_number >= self._peekable_lines:
+                break
+            yield line
+
+    @abstractmethod
+    def can_likely_convert(self, finger_content: str) -> bool:
+        """Check if the filter can likely convert the given Finger content.
+
+        Args:
+            finger_content: The Finger content to check.
+
+        Returns:
+            True if the filter can likely convert the content; False otherwise.
+        """
+
+    @abstractmethod
+    def to_gemtext(self, finger_content: str) -> str:
+        """Convert the given finger content to Gemtext.
+
+        Args:
+            finger_content: The Finger content to convert.
+
+        Returns:
+            The converted Gemtext content.
+        """
+
+
+### finger_filter.py ends here

finger2gemtext-0.0.1/src/finger2gemtext/user_lists.py

@@ -0,0 +1,65 @@
+"""Provides support code for working with user list responses."""
+
+##############################################################################
+# Python imports.
+from re import Pattern, compile
+from typing import Final
+
+##############################################################################
+# Local imports.
+from .finger_filter import FingerFilter
+
+##############################################################################
+_USER_LIST_HEADER: Final[Pattern[str]] = compile(r"^Login\s+Name\s+Login Time\s*$")
+"""Regular expression to match the header of a user list in Finger output."""
+_USER_ENTRY: Final[Pattern[str]] = compile(r"^(?P<username>\S+)\s{2,}.*$")
+"""Regular expression to match a user entry in Finger output."""
+
+
+##############################################################################
+class UserListFilter(FingerFilter):
+    """Filter for Finger user list responses."""
+
+    def can_likely_convert(self, finger_content: str) -> bool:
+        """Check if the filter can likely convert the given Finger content.
+
+        Args:
+            finger_content: The Finger content to check.
+
+        Returns:
+            [`True`][True] if the filter can likely convert the content;
+                [`False`][False] otherwise.
+        """
+        return any(
+            _USER_LIST_HEADER.match(line)
+            for line in self.peekable_lines(finger_content)
+        )
+
+    def to_gemtext(self, finger_content: str) -> str:
+        """Convert the given finger content to Gemtext.
+
+        Args:
+            finger_content: The Finger content to convert.
+
+        Returns:
+            The converted Gemtext content.
+        """
+        gemtext_lines: list[str] = []
+        gather = gemtext_lines.append
+        converting = False
+        found_users = False
+        for line in finger_content.splitlines():
+            if _USER_LIST_HEADER.match(line):
+                gather(line)
+                converting = True
+                continue
+            if converting and (user := _USER_ENTRY.match(line)) is not None:
+                gather(f"=> /finger/{user.group('username')} {line}")
+                found_users = True
+            else:
+                gather(line)
+        gather("")
+        return "\n".join(gemtext_lines) if found_users else finger_content
+
+
+### _user_lists.py ends here