pythonic-fp.splitends 2.0.0__tar.gz → 2.0.3__tar.gz

pythonic_fp_splitends-2.0.3/.github/workflows/static.yml

@@ -0,0 +1,64 @@
+name: Build and Deploy Furo Themed Sphinx Documentation
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+env:
+  RELEASE: '2.0.3'
+  DEVEL: '2.0.4'
+  PYTHON: '3.14'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Select Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install Sphinx Dependencies
+        run: |
+          pip install -r docs/requirements.txt
+          sudo apt-get install -y graphviz
+
+      - name: Build Release Docs
+        run: |
+          pip install pythonic-fp-splitends
+          docs/gen_conf.py release ${{ env.RELEASE }} Splitends splitends > docs/source/conf.py
+          sphinx-build -M html docs/source docs/build/release
+
+      - name: Build Development Docs
+        run: |
+          pip install -e .
+          docs/gen_conf.py devel ${{ env.DEVEL }} Splitends splitends > docs/source/conf.py
+          sphinx-build -M html docs/source docs/build/development
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/build
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v5
+        id: deployment

{pythonic_fp_splitends-2.0.0 → pythonic_fp_splitends-2.0.3}/.gitignore

@@ -1,6 +1,8 @@
 # Minimal version - only add to when necessary
 **/__pycache__/
 dist/
+docs/build/
+docs/source/conf.py
 **/.dmypy.json
 **/.mypy_cache/
 **/.pytest_cache/

{pythonic_fp_splitends-2.0.0 → pythonic_fp_splitends-2.0.3}/CHANGELOG.rst

@@ -17,6 +17,22 @@ See `Semantic Versioning 2.0.0 <https://semver.org>`_.
 Releases and Important Milestones
 ---------------------------------
 
+PyPI 2.0.3 - 2026-05-13
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- Documentation now in maintenance mode.
+
+Development Status Reappraisal - 2026-05-05
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Maintainer appraised the Development Status for
+pythonic-fp-splitends to be ``"3 - Alpha"``.
+
+PyPI 2.0.2 - 2026-01-22
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- Docstring improvements.
+
 PyPI 2.0.0 - 2025-09-09
 ~~~~~~~~~~~~~~~~~~~~~~~
 

{pythonic_fp_splitends-2.0.0 → pythonic_fp_splitends-2.0.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pythonic-fp-splitends
-Version: 2.0.0
-Summary: Mutable stack objects that can safely share data.
+Version: 2.0.3
+Summary: .. admonition:: Mutable stack objects that can safely share data
 Keywords: SplitEnd,lifo,stack
 Author-email: "Geoffrey R. Scheller" <geoffrey@scheller.com>
 Requires-Python: >=3.13
@@ -11,16 +11,16 @@ Classifier: Framework :: Pytest
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: pythonic-fp-fptools>=5.1.2
-Requires-Dist: pythonic-fp-iterables>=5.1.2
-Requires-Dist: pythonic-fp-queues>=5.1.0
+Requires-Dist: pythonic-fp-fptools>=5.2.0
+Requires-Dist: pythonic-fp-iterables>=5.1.3
+Requires-Dist: pythonic-fp-queues>=5.1.1
 Requires-Dist: pytest>=8.4.1 ; extra == "test"
 Project-URL: Changelog, https://github.com/grscheller/pythonic-fp-splitends/blob/main/CHANGELOG.rst
-Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/splitends/development/build/html/
-Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/homepage/build/html/
+Project-URL: Documentation, https://grscheller.github.io/pythonic-fp/projects/splitends.html
+Project-URL: Homepage, https://grscheller.github.io/pythonic-fp/
 Project-URL: Source, https://github.com/grscheller/pythonic-fp-splitends
 Provides-Extra: test
 
@@ -28,7 +28,8 @@ Pythonic FP - SplitEnds
 =======================
 
 PyPI project
-`pythonic-fp.splitends <https://pypi.org/project/pythonic-fp.splitends/>`_.
+`pythonic-fp.splitends
+<https://pypi.org/project/pythonic-fp-splitends/>`_.
 
 Python package Implementing a singularly linked LIFO queue called
 a ``SplitEnd``. These data structures can safely share data nodes
@@ -45,19 +46,23 @@ between themselves.
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp/homepage/build/html/index.html>`_
+<https://grscheller.github.io/pythonic-fp/>`_
 PyPI projects.
 
 Documentation
 -------------
 
+Documentation and other links for this project are hosted on
+`GitHub Pages
+<https://grscheller.github.io/pythonic-fp/projects/splitends.html>`_.
+
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/splitends/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp-splitends/development/html/>`_.
 
 Copyright and License
 ---------------------
 
-Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.
 

{pythonic_fp_splitends-2.0.0 → pythonic_fp_splitends-2.0.3}/README.rst

@@ -2,7 +2,8 @@ Pythonic FP - SplitEnds
 =======================
 
 PyPI project
-`pythonic-fp.splitends <https://pypi.org/project/pythonic-fp.splitends/>`_.
+`pythonic-fp.splitends
+<https://pypi.org/project/pythonic-fp-splitends/>`_.
 
 Python package Implementing a singularly linked LIFO queue called
 a ``SplitEnd``. These data structures can safely share data nodes
@@ -19,18 +20,22 @@ between themselves.
 
 Part of the
 `pythonic-fp
-<https://grscheller.github.io/pythonic-fp/homepage/build/html/index.html>`_
+<https://grscheller.github.io/pythonic-fp/>`_
 PyPI projects.
 
 Documentation
 -------------
 
+Documentation and other links for this project are hosted on
+`GitHub Pages
+<https://grscheller.github.io/pythonic-fp/projects/splitends.html>`_.
+
 Documentation for this project is hosted on
 `GitHub Pages
-<https://grscheller.github.io/pythonic-fp/splitends/development/build/html>`_.
+<https://grscheller.github.io/pythonic-fp-splitends/development/html/>`_.
 
 Copyright and License
 ---------------------
 
-Copyright (c) 2023-2025 Geoffrey R. Scheller. Licensed under the Apache
+Copyright (c) 2023-2026 Geoffrey R. Scheller. Licensed under the Apache
 License, Version 2.0. See the LICENSE file for details.

pythonic_fp_splitends-2.0.3/docs/Makefile

@@ -0,0 +1,78 @@
+# Makefile for Sphinx documentation
+
+# Last and future releases
+#  - former needs to agree with PyPI
+#  - later needs to agree with pyproject.toml
+PROJECT_NAME = Splitends
+PYPI_NAME = splitends
+RELEASE_VERSION = 2.0.3
+DEVEL_VERSION = 2.0.4
+CUSTOM_VERSION = 0.0.0
+
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+STATICDIR = source/_static
+TEMPLATEDIR = source/_templates
+
+# Put help first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean_source:
+	@rm -f "$(SOURCEDIR)"/conf.py
+
+clean_devel:
+	@rm -rf "$(BUILDDIR)"/development
+
+clean_release:
+	@rm -rf "$(BUILDDIR)"/release
+
+clean_custom:
+	@rm -rf "$(BUILDDIR)"/custom
+
+clean: clean_devel clean_release clean_custom clean_source
+	@rm -rf $(BUILDDIR)
+	@echo Removed all doc build artifacts.
+
+setup_devel: clean_devel
+	@./gen_conf.py devel "$(DEVEL_VERSION)" "$(PROJECT_NAME)" "$(PYPI_NAME)" > "$(SOURCEDIR)"/conf.py
+
+setup_release: clean_release
+	@./gen_conf.py release "$(RELEASE_VERSION)" "$(PROJECT_NAME)" "$(PYPI_NAME)" > "$(SOURCEDIR)"/conf.py
+
+setup_custom: clean_custom
+	@./gen_conf.py custom "$(CUSTOM_VERSION)" "$(PROJECT_NAME)" "$(PYPI_NAME)" > "$(SOURCEDIR)"/conf.py
+
+setup_redo: clean_custom
+	@echo Redoing custom build with a possibly reeditted conf.py
+	@./gen_conf.py redo "" "" ""
+
+# Build development labeled html docs.
+devel: Makefile setup_devel
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/development $(SPHINXOPTS)
+
+# Build release labeled html docs.
+release: Makefile setup_release
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/release $(SPHINXOPTS)
+
+# Build custom labeled html docs.
+custom: Makefile setup_custom
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/custom $(SPHINXOPTS)
+
+# Build HTML docs with previous generated (possibly hand edited) source/conf.py,
+# put results in $(BUILDDIR)/custom.
+redo: Makefile setup_redo
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)"/custom $(SPHINXOPTS)
+
+# Catch-all target: route all unknown targets to Sphinx and save to $(BUILDDIR)/custom.
+# Reuse a previously generated source/conf.py.
+%: Makefile setup_redo
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)"/custom $(SPHINXOPTS)
+
+.PHONY: help Makefile
+.PHONY: setup_devel setup_release setup_custom
+.PHONY: devel release
+.PHONY: clean_source clean_devel clean_release clean_custom clean

pythonic_fp_splitends-2.0.3/docs/gen_conf.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python
+# Generate conf.py Sphinx configuration executable
+
+import sys
+import os
+
+project_prefix = 'Pythonic FP'
+pypi_prefix = 'pythonic-fp'
+author = 'Geoffrey R. Scheller'
+copyright = f'2023-2026, {author}'
+
+args = sys.argv[1:]
+num_args = len(args)
+
+if num_args == 4:
+    build_type, version, project_name, pypi_name = args
+    project = project_prefix + ' - ' + project_name
+    pypi_project_repo = pypi_prefix + '-' + pypi_name
+    project_url_rst = f'`{project} <https://pypi.org/project/{pypi_project_repo}/>`_'
+    homepage_url_rst = f'`{project_prefix} <https://grscheller.github.io/{pypi_prefix}/>`_'
+
+else:
+    sys.exit('Error: gen_conf.py takes exactly 4 arguments')
+
+match build_type:
+    case 'custom':
+        release = f'{version}'
+        release_string = f'**Custom PyPI Non-release version {release}**'
+    case 'devel':
+        release = f'{version}'
+        release_string = f'**Proposed PyPI release version {release}**'
+    case 'release':
+        release = f'{version}'
+        release_string = f'**PyPI release version {release}**'
+    case 'redo':
+        if not os.path.isfile('source/conf.py'):
+            sys.exit('Error: cannot redo without source/conf.py')
+        sys.exit()
+    case _:
+        sys.exit(f'Error: unknown built_type {build_type} given')
+
+print(f'''# Generated conf.py Sphinx configuration executable
+
+from typing import Any
+from sphinx.application import Sphinx
+
+project = '{project}'
+author = '{author}'
+copyright = '{copyright}'
+release = '{release}'
+release_string = '{release_string}'
+
+def skip_abc_methods(
+    app: Any, what: str, name: str, obj: Any, skip: bool, options: Any
+) -> bool:
+    if name in [
+        '__init_subclass__',
+        '__subclasshook__',
+        '__class_getitem__',
+        '__weakref__',
+    ]:
+        return True  # Skip these members
+    return skip
+
+
+def setup(app: Sphinx) -> None:
+    app.connect('autodoc-skip-member', skip_abc_methods)
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.graphviz',
+]
+
+autodoc_default_options = {{
+    'members': True,
+    'private-members': True,
+    'special-members': True,
+    'inherited-members': False,
+    'show-inheritance': True,
+}}
+autodoc_member_order = 'bysource'
+autoclass_content = 'class'
+autodoc_class_signature = 'separated'
+autodoc_typehints_format = 'short'
+autodoc_use_type_comments = True
+autodoc_docstring_signature = False
+autodoc_preserve_defaults = True
+autodoc_warningiserror = False
+
+templates_path = ['_templates']
+exclude_patterns: list[str] = []
+
+html_theme_options = {{
+    'light_css_variables': {{
+        'color-link--visited': 'var(--color-link)',
+    }},
+    'dark_css_variables': {{
+        'color-link--visited': 'var(--color-link)',
+    }},
+}}
+html_theme = 'furo'
+html_static_path = ['_static']
+html_css_files = ['custom.css']
+
+rst_epilog = """
+.. |RELEASE_STRING| replace:: {release_string}
+
+"""
+''')

pythonic_fp_splitends-2.0.3/docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx>=9.1
+furo

pythonic_fp_splitends-2.0.3/docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+dl.field-list > dt {
+    text-transform: none !important;
+}

pythonic_fp_splitends-2.0.3/docs/source/api/index.rst

@@ -0,0 +1,15 @@
+Splitends
+=========
+
+.. automodule:: pythonic_fp.splitends
+    :no-members:
+    :ignore-module-all:
+    :no-index:
+
+.. toctree::
+    :caption: Splitends
+    :maxdepth: 1
+
+    splitend
+    splitend_node
+

pythonic_fp_splitends-2.0.3/docs/source/api/splitend.rst

@@ -0,0 +1,8 @@
+module splitend
+---------------
+
+**Mutable LIFO stacks safely share immutable data between themselves.**
+
+.. automodule:: pythonic_fp.splitends.splitend
+    :members:
+    :special-members:

pythonic_fp_splitends-2.0.3/docs/source/api/splitend_node.rst

@@ -0,0 +1,8 @@
+module splitend_node
+--------------------
+
+**Immutable data nodes used by splitend stacks.**
+
+.. automodule:: pythonic_fp.splitends.splitend_node
+    :members:
+    :special-members:

pythonic_fp_splitends-2.0.3/docs/source/changelog.rst

@@ -0,0 +1,7 @@
+changelog
+---------
+
+Change log for the
+`pythonic-fp-splitends
+<https://github.com/grscheller/pythonic-fp-splitends/blob/main/CHANGELOG.rst>`_
+PyPI project.

pythonic_fp_splitends-2.0.3/docs/source/description.rst

@@ -0,0 +1,7 @@
+Description
+-----------
+
+.. automodule:: pythonic_fp.splitends
+    :synopsis:
+    :noindex:
+

pythonic_fp_splitends-2.0.3/docs/source/index.rst

@@ -0,0 +1,30 @@
+pythonic-fp-splitends
+=====================
+
+Project
+`Pypythonic-fp-Splitends <https://pypi.org/project/pythonic-fp-splitends/>`_
+one of the
+`Pythonic FP <https://grscheller.github.io/pythonic-fp/>`_
+PyPI projects.
+
+|RELEASE_STRING|
+
+.. toctree::
+    :caption: Overview
+    :hidden:
+
+    self
+
+.. toctree::
+    :caption: User Documentation
+
+    description
+    usage
+    releases
+    changelog
+
+.. toctree::
+    :caption: API Documentation
+    :maxdepth: 1
+
+    api/index

pythonic_fp_splitends-2.0.3/docs/source/releases.rst

@@ -0,0 +1,24 @@
+PyPI releases
+=============
+
+**pythonic-fp-splitends:** pythonic_fp.splitends
+
++---------------------------------------------------------------------------------------+--------------+
+| PyPI Release                                                                          | Release date |
++=======================================================================================+==============+
+| `development <https://grscheller.github.io/pythonic-fp-splitends/development/html/>`_ |              |
++---------------------------------------------------------------------------------------+--------------+
+| `v2.0.3 <https://grscheller.github.io/pythonic-fp-splitends/release/html/>`_          | 2026-05-13   |
++---------------------------------------------------------------------------------------+--------------+
+| v2.0.2                                                                                | 2026-01-22   |
++---------------------------------------------------------------------------------------+--------------+
+| v2.0.0                                                                                | 2025-09-28   |
++---------------------------------------------------------------------------------------+--------------+
+| v1.0.2                                                                                | 2025-09-09   |
++---------------------------------------------------------------------------------------+--------------+
+| v1.0.1                                                                                | 2025-09-09   |
++---------------------------------------------------------------------------------------+--------------+
+| v1.0.0                                                                                | 2025-08-02   |
++---------------------------------------------------------------------------------------+--------------+
+| v0.30.0                                                                               | 2025-07-06   |
++---------------------------------------------------------------------------------------+--------------+

pythonic_fp_splitends-2.0.3/docs/source/usage.rst

@@ -0,0 +1,21 @@
+usage
+=====
+
+How to install the package
+--------------------------
+
+Install the project into your Python environment:
+
+.. code:: console
+
+    $ pip install pythonic-fp.splitends
+
+Importing the package
+---------------------
+
+Import the Splitend class and its supporting infrastructure (TODO)
+into your code.
+
+.. code:: python
+
+    from pythonic_fp.splitends.splitend import Splitend

{pythonic_fp_splitends-2.0.0 → pythonic_fp_splitends-2.0.3}/pyproject.toml

@@ -1,31 +1,40 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
 [project]
 name = "pythonic-fp-splitends"
-version = "2.0.0"
+version = "2.0.3"
 readme = "README.rst"
 requires-python = ">=3.13"
-license = { file = "LICENSE" }
-authors = [{ name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" }]
-keywords = ["SplitEnd", "lifo", "stack"]
+authors = [
+  { name = "Geoffrey R. Scheller", email = "geoffrey@scheller.com" },
+]
+keywords = [
+  "SplitEnd",
+  "lifo",
+  "stack",
+]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Framework :: Pytest",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",
   "Operating System :: OS Independent",
-  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Typing :: Typed",
 ]
 dependencies = [
-  "pythonic-fp-fptools>=5.1.2",
-  "pythonic-fp-iterables>=5.1.2",
-  "pythonic-fp-queues>=5.1.0",
+  "pythonic-fp-fptools>=5.2.0",
+  "pythonic-fp-iterables>=5.1.3",
+  "pythonic-fp-queues>=5.1.1",
 ]
 dynamic = ["description"]
 
 [project.urls]
 Changelog = "https://github.com/grscheller/pythonic-fp-splitends/blob/main/CHANGELOG.rst"
-Documentation = "https://grscheller.github.io/pythonic-fp/splitends/development/build/html/"
-Homepage = "https://grscheller.github.io/pythonic-fp/homepage/build/html/"
+Documentation = "https://grscheller.github.io/pythonic-fp/projects/splitends.html"
+Homepage = "https://grscheller.github.io/pythonic-fp/"
 Source = "https://github.com/grscheller/pythonic-fp-splitends"
 
 [project.optional-dependencies]
@@ -33,17 +42,11 @@ test = [
   "pytest>=8.4.1",
 ]
 
-[build-system]
-requires = ["flit_core>=3.12,<4"]
-build-backend = "flit_core.buildapi"
-
 [tool.flit.module]
 name = "pythonic_fp.splitends"
 
 [tool.mypy]
-enable_incomplete_feature = "NewGenericSyntax"
 explicit_package_bases = true
-implicit_reexport = false
 local_partial_types = true
 namespace_packages = true
 warn_redundant_casts = true
@@ -57,19 +60,24 @@ dmypy = false
 strict = true
 report_progress = true
 
-[tool.pytest.ini_options]
-addopts = "-ra"
+[tool.pytest]
+addopts = [
+  "-ra",
+]
 consider_namespace_packages = true
 testpaths = ["tests/"]
 
 [tool.ruff]
-target-version = "py313"
+target-version = "py314"
 
 [tool.ruff.lint.flake8-quotes]
 docstring-quotes = "double"
 
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = ["C901"]
+"tests/**/*.py" = [
+  "E731",
+  "C901",
+]
 "**/*.py" = ["E741"]
 
 [tool.ruff.format]

pythonic_fp_splitends-2.0.3/src/pythonic_fp/splitends/__init__.py

@@ -0,0 +1,41 @@
+# Copyright 2024-2026 Geoffrey R. Scheller
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+.. admonition:: Mutable stack objects that can safely share data
+
+    Python package implementing a singularly linked stack of nodes called a ``SplitEnd``.
+    While mutable, these data structures can safely share immutable data nodes between
+    themselves. These nodes, of type ``SENode``, always contain data. A root node is
+    a node whose previous node is itself. Root nodes mark the bottom of the stack.
+
+    Like one of many "split ends" from shafts of hair, a ``SplitEnd`` can be "snipped"
+    shorter or "extended" further from its "end" node at the top of the stack. Its "root"
+    node is at the bottom of the stack and can not be "snipped" or "cut" off.
+
+    A ``SplitEnd`` can be duplicated onto a compatible root node. By compatible, the
+    new root must contain data that compares as equal to the old root node.
+
+    .. admonition:: Future directions
+
+        A ``scalp`` is a container of root nodes all of whose contained data must
+        be hashable. The ``scalp.add(d)`` method will return the unique root node with data
+        that compares as equal to ``d``, or create a new root node if such a contained node
+        does not exist.
+
+"""
+
+__author__ = 'Geoffrey R. Scheller'
+__copyright__ = 'Copyright (c) 2023-2026 Geoffrey R. Scheller'
+__license__ = 'Apache License 2.0'

{pythonic_fp_splitends-2.0.0 → pythonic_fp_splitends-2.0.3}/src/pythonic_fp/splitends/splitend.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,27 +14,33 @@
 
 """
 Class SplitEnds
-===============
+---------------
 
-**LIFO stacks safely sharing immutable data.**
+.. admonition:: LIFO stacks safely sharing immutable data.
 
-- each ``SplitEnd`` is a very simple stateful (mutable) LIFO stack
-- data can be either "extended" to or "snipped" off the "end" 
-- the "root" of a ``SplitEnd``
-  - it is fixed and cannot be removed from the ``SplitEnd``
-- different mutable split ends can safely share the same "tail"
-- each ``SplitEnd`` sees itself as a singularly linked list
-- bush-like datastructures can be formed using multiple ``SplitEnds``
-- the ``SplitEnd.split`` and ``len`` methods are O(1)
-- in boolean context returns true if the ``SplitEnd`` is not just its "root"
+    - each ``SplitEnd`` is a very simple stateful (mutable) LIFO stack
+    - data can be either "extended" to or "snipped" off the "end"
+    - "root" of a ``SplitEnd`` is embedded in a ``scalp``
+
+      - the root data is immutable
+      - it cannot be split off
+
+    - different mutable split ends can safely share the same "tail"
+    - each ``SplitEnd`` sees itself as a singularly linked list
+    - bush-like datastructures can be formed using multiple ``SplitEnds``
+    - the ``SplitEnd.split`` and ``len`` methods are O(1)
+    - in a boolean context
+
+      - falsy just a "root"
+      - truthy otherwise
 
 """
 
 from collections.abc import Callable, Iterator
-from pythonic_fp.iterables.folding import reduce_left, fold_left
 from typing import cast, Final, overload
-from pythonic_fp.queues.lifo import LIFOQueue
 from pythonic_fp.gadgets.sentinels.flavored import Sentinel
+from pythonic_fp.iterables.folding import reduce_left, fold_left
+from pythonic_fp.queues.lifo import LIFOQueue
 from .splitend_node import SENode
 
 __all__ = ['SplitEnd']
@@ -50,8 +56,11 @@ class SplitEnd[D]:
 
     def __init__(self, *ds: D, root: SENode[D] | _Sentinel = _sentinel) -> None:
         """
-        :param root_data: Irremovable initial data at bottom of stack.
-        :param data: Removable data to be pushed onto splitend stack.
+        .. admonition:: init
+
+            :param root_data: Irremovable initial data at bottom of stack.
+            :param ds: Removable data to be pushed onto splitend stack.
+
         """
         if root is _sentinel:
             if ds:
@@ -75,27 +84,57 @@ class SplitEnd[D]:
         self._end, self._root, self._count = end, root_node, count
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: iter
+
+            Iterate from end to root.
+
+            :yields: data from end to root
+
+        """
         return iter(self._end)
 
     def __reversed__(self) -> Iterator[D]:
+        """
+        .. admonition:: reverse iter
+
+            Iterate from end to root.
+
+            :yields: data from end to root
+
+        """
         return reversed(list(self))
 
     def __bool__(self) -> bool:
         """
-        :returns: ``True`` is ``SplitEnd`` is not just its root node.
+        .. admonition:: bool
+
+            :returns: ``True`` if ``SplitEnd`` is not just its root node.
+
         """
         return bool(self._end)
 
     def __len__(self) -> int:
-        return self._count
+        """
+        .. admonition:: len
 
-    def __repr__(self) -> str:
-        return 'SplitEend(' + ', '.join(map(repr, reversed(self))) + ')'
+            :returns: The number of nodes on the ``Splitend``.
 
-    def __str__(self) -> str:
-        return '>< ' + ' -> '.join(map(str, self)) + ' ||'
+        """
+        return self._count
 
     def __eq__(self, other: object, /) -> bool:
+        """
+        .. admonition:: equality comparison
+
+            Efficiently compare two ``SplitEnds``.
+
+            :returns: ``True`` only if ``other`` is also a ``Splitend``
+                      whose corresponding data to ``self`` compares as
+                      equal and both share the same root node.
+                      Otherwise ``False``.
+
+        """
         if not isinstance(other, type(self)):
             return False
 
@@ -116,11 +155,55 @@ class SplitEnd[D]:
                 right = right.prev()
         return True
 
+    def __repr__(self) -> str:
+        """
+        .. admonition:: repr string
+
+            Construct string to reproduce the ``SplitEnd``.
+            TODO: Fix, does not include root node.
+
+            :returns: String to reproduce the ``SplitEnd``.
+
+        """
+        return 'SplitEend(' + ', '.join(map(repr, reversed(self))) + ')'
+
+    def __str__(self) -> str:
+        """
+        .. admonition:: user string
+
+            Construct string meaningful to an end user.
+            Does not give root node info.
+
+            :returns: String to reproduce the ``SplitEnd``.
+
+        """
+        return '>< ' + ' -> '.join(map(str, self)) + ' ||'
+
+    def snip(self) -> D:
+        """
+        .. admonition:: cut just tip
+
+            :returns: Data from snipped tip,
+                    just return root data if at root.
+
+        """
+        if self._count > 1:
+            data, self._end, self._count = self._end.both() + (self._count - 1,)
+        else:
+            data = self._end.data()
+
+        return data
+
     def cut(self, num: int | None = None) -> tuple[D, ...]:
-        """Cut data off end of ``SplitEnd``.
+        """
+        .. admonition:: Cut data off end of SplitEnd
+
+            Pop "cut" data off Split, just copy root data.
+
+            :param num: Optional number of nodes to cut,
+                        default is entire stack.
+            :returns: Tuple of data cut off from end towards root.
 
-        :param num: Optional number of nodes to cut, default is entire stack.
-        :returns: Tuple of data cut off from end.
         """
         if num is None or num > self._count:
             num = self._count
@@ -142,42 +225,63 @@ class SplitEnd[D]:
         return data
 
     def extend(self, *ds: D) -> None:
-        """Add data onto the tip of the SplitEnd. Like adding a hair
-        extension.
+        """
+        .. admonition:: extend SplitEnd with data
+
+            Add data onto the tip of the SplitEnd. Like adding
+            a hair extension.
+
+            :param ds: data to extend the splitend
 
-        :param ds: data to extend the splitend
         """
         for d in ds:
             node = SENode(d, self._end)
             self._end, self._count = node, self._count + 1
 
     def peak(self) -> D:
-        """Return the data at end (top) of SplitEnd without consuming it.
+        """
+        .. admonition:: peak at end
+
+            Return the data at end (top) of the SplitEnd
+            without consuming it.
+
+            :returns: The data at the end (tip) of the SplitEnd.
 
-        :returns: The data at the end of the SplitEnd.
         """
         return self._end.data()
 
     def root(self) -> SENode[D]:
         """
-        :returns: The root SENode node of the SplitEnd.
+        .. admonition:: get root
+
+            :returns: The root SENode node of the SplitEnd.
+
         """
         return self._root
 
     def reroot(self, root: SENode[D]) -> 'SplitEnd[D]':
-        """Create a brand new SplitEnd with the same data but different root.
+        """
+        .. admonition:: re-root SplitEnd
+
+            Create a brand new SplitEnd with the same data but different root.
+
+            :returns: New SplitEnd with the same data
+                      and the new ``root``.
+            :raises ValueError: If new and original root nodes
+                                are not compatible.
+
+            .. note::
 
-        .. note::
+                Two nodes are compatible root nodes if and only if
 
-            Two nodes are compatible root nodes if and only if
+                - they are both actually root nodes
 
-            - they are both actually root nodes
-              - that is their previous nodes are themselves
-            - their data compare as equal
-              - comparing by identity is too strong for some use cases
+                - which implies that their previous nodes are themselves
+
+                - their data compare as equal
+
+                - comparing by identity is too strong
 
-        :returns: New SplitEnd with the same data and the new ``root``.
-        :raises ValueError: If new and original root nodes are not compatible.
         """
         if not root:
             msg = 'New root node is not a root node.'
@@ -193,22 +297,15 @@ class SplitEnd[D]:
 
         return SplitEnd(*lifo, root = root)
 
-    def snip(self) -> D:
-        """Snip data off tip of SplitEnd. Just return data if tip is root.
-
-        :returns: Data snipped off tip, just return root data if at root.
+    def split(self, *ds: D) -> 'SplitEnd[D]':
         """
-        if self._count > 1:
-            data, self._end, self._count = self._end.both() + (self._count - 1,)
-        else:
-            data = self._end.data()
+        .. admonition:: split
 
-        return data
+            Split the end and add more data.
 
-    def split(self, *ds: D) -> 'SplitEnd[D]':
-        """Split the end and add more data.
+            :returns: New instance, same data nodes plus
+                      additional ones on end. Same root node.
 
-        :returns: New instance, same data nodes plus additional ones on end.
         """
         se: SplitEnd[D] = SplitEnd(self._root.data())
         se._count, se._end, se._root = self._count, self._end, self._root
@@ -221,11 +318,17 @@ class SplitEnd[D]:
     def fold[T](self, f: Callable[[T, D], T], init: T) -> T: ...
 
     def fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T:
-        """Reduce with a function, folding from tip to root.
+        """
+        .. admonition:: fold
+
+            Reduce with a function, folding from tip to root.
+
+            :param f: Folding function, first argument
+                      is for the accumulator.
+            :param init: Optional initial starting value for the fold.
+            :returns: Reduced value folding from tip to root
+                      in natural LIFO order.
 
-        :param f: Folding function, first argument is for the accumulator.
-        :param init: Optional initial starting value for the fold.
-        :returns: Reduced value folding from tip to root in natural LIFO order.
         """
         if init is None:
             return self._end.fold(f)  # type: ignore
@@ -237,11 +340,16 @@ class SplitEnd[D]:
     def rev_fold[T](self, f: Callable[[T, D], T], init: T) -> T: ...
 
     def rev_fold[T](self, f: Callable[[T, D], T], init: T | None = None) -> T:
-        """Reduce with a function, fold from root to tip.
+        """
+        .. admonition:: reverse fold
+
+            Reduce with a function, fold from root to tip.
+
+            :param f: Folding function, first argument
+                      is for the accumulator.
+            :param init: Optional initial starting value for the fold.
+            :returns: Reduced value folding from root to tip.
 
-        :param f: Folding function, first argument is for the accumulator.
-        :param init: Optional initial starting value for the fold.
-        :returns: Reduced value folding from root to tip.
         """
         if init is None:
             return cast(T, reduce_left(reversed(self), cast(Callable[[D, D], D], f)))

{pythonic_fp_splitends-2.0.0 → pythonic_fp_splitends-2.0.3}/src/pythonic_fp/splitends/splitend_node.py

@@ -1,4 +1,4 @@
-# Copyright 2023-2025 Geoffrey R. Scheller
+# Copyright 2023-2026 Geoffrey R. Scheller
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,21 +13,25 @@
 # limitations under the License.
 
 """
-Class SENode
-============
-
-**Used to make inwardly directed bush-like graphs.**
-
-- designed so multiple splitends can safely share the same data
-- nodes always contain data
-- data node ``SENode[D]`` make up end-to-root singularly linked lists
-- two nodes compare as equal if
-    - both their previous Nodes are the same
-    - their data compare as equal
-- a root node is a node whose previous node is itself
-    - root nodes mark the bottom of splitend stacks
-- more than one node can point to the same proceeding node
-    - forming bush like graphs
+.. admonition:: SplitEnd node 
+
+    Used to make inwardly directed bush-like graphs.
+
+    - designed so multiple splitends can safely share the same data
+    - nodes always contain data
+    - data node ``SENode[D]`` make up end-to-root singularly linked lists
+    - two nodes compare as equal if
+
+      - both their previous Nodes are the same
+      - their data compare as equal
+
+    - a root node is a node whose previous node is itself
+
+      - root nodes mark the bottom of splitend stacks
+
+    - more than one node can point to the same proceeding node
+
+      - forming bush like graphs
 
 """
 
@@ -46,8 +50,12 @@ class SENode[D]:
 
     def __init__(self, data: D, prev: Self | _Sentinel = _sentinel) -> None:
         """
-        :param data: Nodes always contain data of type ``D``.
-        :param prev: Link to previous node. Points to ``self`` if a root node.
+        .. admonition:: init
+
+            :param data: Nodes always contain data of type ``D``.
+            :param prev: Link to previous node, points to ``self``
+                         if a root node.
+
         """
         self._data = data
         if prev is not _sentinel:
@@ -57,11 +65,20 @@ class SENode[D]:
 
     def __bool__(self) -> bool:
         """
-        :returns: ``True`` if ``SENode`` is not a root node.
+        .. admonition:: bool
+
+            :returns: ``True`` only if ``SENode`` is not a root node.
+
         """
         return self._prev is not self
 
     def __iter__(self) -> Iterator[D]:
+        """
+        .. admonition:: iter
+
+            :yields: Node date until and including root node.
+
+        """
         node = self
         while node:
             yield node._data
@@ -70,8 +87,19 @@ class SENode[D]:
 
     def __eq__(self, other: object) -> bool:
         """
-        Two ``SENodes`` nodes are equal if their previous nodes are the
-        same object and their data compare as equal.
+        .. admonition:: equality comparison
+
+            Two ``SENodes`` nodes are equal if their previous nodes
+            are the same object and their data compare as equal.
+
+            :param other: 
+            :returns: ``True`` if ``other`` is a SplitEnd which compares
+                      as equal to ``self`` as described above.
+
+            .. note::
+
+                Will be useful when consolidating SplitEnds.
+
         """
         if not isinstance(other, type(self)):
             return False
@@ -82,32 +110,44 @@ class SENode[D]:
             return True
         return False
 
-    def both(self) -> tuple[D, Self]:
-        """Peak at data and previous node, if a root then data and self.
-
-        :returns: tuple of type tuple[D, SENode[D]]
+    def data(self) -> D:
         """
-        return self._data, self._prev
+        .. admonition:: peak at data in SENode
 
-    def data(self) -> D:
-        """Peak at data.
+            :returns: The data stored in the ``SENode``.
 
-        :returns: The data stored in the ``SENode``.
         """
         return self._data
 
     def prev(self) -> Self:
-        """Peak at previous node.
+        """
+        .. admonition:: peak at previous node
+
+            :returns: The previous node stored in the ``SENode``.
 
-        :returns: The previous node stored in the ``SENode``.
         """
         return self._prev
 
+    def both(self) -> tuple[D, Self]:
+        """
+        .. admonition:: both data and previous node
+
+            Peak at data and previous node,
+            if a root then data and ``self``.
+
+            :returns: Tuple of type ``tuple[D, SENode[D]]``
+
+        """
+        return self._data, self._prev
+
     def push(self, data: D) -> Self:
-        """Create a new ``SENode[D]``.
+        """
+        .. admonition:: push date to create  new ``SENode[D]``
+
+            :param data: Data for new node to contain.
+            :returns: New ``SENode`` whose previous node is
+                      the current node.
 
-        :param data: Data for new node to contain.
-        :returns: New ``SENode`` whose previous node is the current node.
         """
         return cast(Self, SENode(data, self))
 
@@ -117,11 +157,17 @@ class SENode[D]:
     def fold[T](self, f: Callable[[T, D], T], init: T) -> T: ...
 
     def fold[T](self, f: Callable[[T, D], T], init: T | _Sentinel = _sentinel) -> T:
-        """Fold data across linked nodes with a function..
+        """
+        .. admonition:: fold
+
+            Fold data across linked nodes with a function.
+
+            :param f: Folding function, first argument
+                    is for accumulated value.`
+            :param init: Optional initial starting value for the fold.
+            :returns: Reduced value folded from end to root
+                    in natural LIFO order.
 
-        :param f: Folding function, first argument is for accumulated value.`
-        :param init: Optional initial starting value for the fold.
-        :returns: Reduced value folded from end to root in natural LIFO order.
         """
         if init is not _sentinel:
             acc = cast(T, init)

pythonic_fp_splitends-2.0.0/src/pythonic_fp/splitends/__init__.py

@@ -1,37 +0,0 @@
-# Copyright 2024-2025 Geoffrey R. Scheller
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-"""Mutable stack objects that can safely share data.
-
-Python package implementing a singularly linked stack of nodes called a ``SplitEnd``.
-While mutable, these data structures can safely share immutable data nodes between
-themselves. These nodes, of type ``SENode``, always contain data. A root node is
-a node whose previous node is itself. Root nodes mark the bottom of the stack.
-
-Like one of many "split ends" from shafts of hair, a ``SplitEnd`` can be "snipped"
-shorter or "extended" further from its "end" node at the top of the stack. Its "root"
-node is at the bottom of the stack and can not be "snipped" or "cut" off.
-
-A ``SplitEnd`` can be duplicated onto a compatible root node. By compatible, the
-new root must contain data that compares as equal to the old root node.
-
-TODO: A ``scalp`` is a container of root nodes all of whose contained data must be
-hashable. The ``scalp.add(d)`` method will return the unique root node with data
-that compares as equal to ``d``, or create a new root node if such a contained node
-does not exist.
-"""
-
-__author__ = 'Geoffrey R. Scheller'
-__copyright__ = 'Copyright (c) 2023-2025 Geoffrey R. Scheller'
-__license__ = 'Apache License 2.0'